KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > orm > ojb > PersistenceBrokerOperations


1 /*
2  * Copyright 2002-2005 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.orm.ojb;
18
19 import java.util.Collection JavaDoc;
20 import java.util.Iterator JavaDoc;
21
22 import org.apache.ojb.broker.query.Query;
23
24 import org.springframework.dao.DataAccessException;
25
26 /**
27  * Interface that specifies a basic set of OJB PersistenceBroker operations.
28  * Implemented by PersistenceBrokerTemplate. Not often used, but a useful
29  * option to enhance testability, as it can easily be mocked or stubbed.
30  *
31  * <p>Provides PersistenceBrokerTemplate's data access methods that mirror
32  * various PersistenceBroker methods. See the OJB PersistenceBroker javadocs
33  * for details on those methods. Additionally, there is a convenient
34  * <code>getObjectById</code> method (Hibernate/JDO-style).
35  *
36  * <p>Note that operations that return an Iterator (that is,
37  * <code>getIteratorByQuery</code> and <code>getReportQueryIteratorByQuery</code>)
38  * are supposed to be used within Spring-managed transactions
39  * (with PersistenceBrokerTransactionManager or JtaTransactionManager).
40  * Else, the Iterator won't be able to read results from its ResultSet anymore,
41  * as the underlying PersistenceBroker will already have been closed.
42  *
43  * @author Juergen Hoeller
44  * @since 1.1
45  * @see PersistenceBrokerTemplate
46  * @see org.apache.ojb.broker.PersistenceBroker
47  * @see #getIteratorByQuery
48  * @see #getReportQueryIteratorByQuery
49  * @see PersistenceBrokerTransactionManager
50  * @see org.springframework.transaction.jta.JtaTransactionManager
51  */
52 public interface PersistenceBrokerOperations {
53
54     /**
55      * Execute the action specified by the given action object within a
56      * PersistenceBroker. Application exceptions thrown by the action object
57      * get propagated to the caller (can only be unchecked). OJB exceptions
58      * are transformed into appropriate DAO ones. Allows for returning a
59      * result object, i.e. a domain object or a collection of domain objects.
60      * <p>Note: Callback code is not supposed to handle transactions itself!
61      * Use an appropriate transaction manager like PersistenceBrokerTransactionManager.
62      * @param action action object that specifies the OJB action
63      * @return a result object returned by the action, or null
64      * @throws org.springframework.dao.DataAccessException in case of OJB errors
65      * @see PersistenceBrokerTransactionManager
66      * @see org.springframework.dao
67      * @see org.springframework.transaction
68      */
69     Object JavaDoc execute(PersistenceBrokerCallback action) throws DataAccessException;
70
71     /**
72      * Execute the specified action assuming that the result object is a
73      * Collection. This is a convenience method for executing OJB queries
74      * within an action.
75      * @param action action object that specifies the OJB action
76      * @return a result object returned by the action, or null
77      * @throws org.springframework.dao.DataAccessException in case of OJB errors
78      */
79     Collection JavaDoc executeFind(PersistenceBrokerCallback action) throws DataAccessException;
80
81
82     //-------------------------------------------------------------------------
83 // Convenience methods for load, find, save, delete
84 //-------------------------------------------------------------------------
85
86     /**
87      * Return the persistent instance of the given entity class
88      * with the given id value, throwing an exception if not found.
89      * <p>The given id value is typically just unique within the namespace of the
90      * persistent class, corresponding to a single primary key in a database table.
91      * @param entityClass a persistent class
92      * @param idValue an id value of the persistent instance
93      * @return the persistent instance
94      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
95      * @throws org.springframework.dao.DataAccessException in case of OJB errors
96      * @see org.apache.ojb.broker.IdentityFactory#buildIdentity(Class, Object)
97      * @see org.apache.ojb.broker.PersistenceBroker#getObjectByIdentity
98      */
99     Object JavaDoc getObjectById(Class JavaDoc entityClass, Object JavaDoc idValue) throws DataAccessException;
100
101     /**
102      * @see org.apache.ojb.broker.PersistenceBroker#getObjectByQuery
103      * @throws org.springframework.dao.DataAccessException in case of OJB errors
104      */
105     Object JavaDoc getObjectByQuery(Query query) throws DataAccessException;
106
107     /**
108      * @see org.apache.ojb.broker.PersistenceBroker#getCollectionByQuery
109      * @throws org.springframework.dao.DataAccessException in case of OJB errors
110      */
111     Collection JavaDoc getCollectionByQuery(Query query) throws DataAccessException;
112
113     /**
114      * @see org.apache.ojb.broker.PersistenceBroker#getIteratorByQuery
115      * @throws org.springframework.dao.DataAccessException in case of OJB errors
116      */
117     Iterator JavaDoc getIteratorByQuery(Query query) throws DataAccessException;
118
119     /**
120      * @see org.apache.ojb.broker.PersistenceBroker#getReportQueryIteratorByQuery
121      * @throws org.springframework.dao.DataAccessException in case of OJB errors
122      */
123     Iterator JavaDoc getReportQueryIteratorByQuery(Query query) throws DataAccessException;
124     
125     /**
126      * @see org.apache.ojb.broker.PersistenceBroker#getCount
127      * @throws org.springframework.dao.DataAccessException in case of OJB errors
128      */
129     int getCount(Query query) throws DataAccessException;
130
131     /**
132      * @see org.apache.ojb.broker.PersistenceBroker#removeFromCache
133      * @throws org.springframework.dao.DataAccessException in case of OJB errors
134      */
135     void removeFromCache(Object JavaDoc entityOrId) throws DataAccessException;
136
137     /**
138      * @see org.apache.ojb.broker.PersistenceBroker#clearCache
139      * @throws org.springframework.dao.DataAccessException in case of OJB errors
140      */
141     void clearCache() throws DataAccessException;
142
143     /**
144      * @see org.apache.ojb.broker.PersistenceBroker#store
145      * @throws org.springframework.dao.DataAccessException in case of OJB errors
146      */
147     void store(Object JavaDoc entity) throws DataAccessException;
148
149     /**
150      * @see org.apache.ojb.broker.PersistenceBroker#delete
151      * @throws org.springframework.dao.DataAccessException in case of OJB errors
152      */
153     void delete(Object JavaDoc entity) throws DataAccessException;
154
155     /**
156      * @see org.apache.ojb.broker.PersistenceBroker#deleteByQuery
157      * @throws org.springframework.dao.DataAccessException in case of OJB errors
158      */
159     void deleteByQuery(Query query) throws DataAccessException;
160
161 }
162
Popular Tags