JdoOperations


1   /*
2    * Copyright 2002-2006 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.jdo;
18  
19  import java.util.Collection  ;
20  import java.util.Map  ;
21  
22  import org.springframework.dao.DataAccessException;
23  
24  /**
25   * Interface that specifies a basic set of JDO operations,
26   * implemented by {@link JdoTemplate}. Not often used, but a useful
27   * option to enhance testability, as it can easily be mocked or stubbed.
28   *
29   * <p>Defines <code>JdoTemplate</code>'s data access methods that mirror
30   * various JDO {@link javax.jdo.PersistenceManager} methods. Users are
31   * strongly encouraged to read the JDO <code>PersistenceManager</code>
32   * javadocs for details on the semantics of those methods.
33   *
34   * <p>Note that lazy loading will just work with an open JDO
35   * <code>PersistenceManager</code>, either within a managed transaction or within
36   * {@link org.springframework.orm.jdo.support.OpenPersistenceManagerInViewFilter}/
37   * {@link org.springframework.orm.jdo.support.OpenPersistenceManagerInViewInterceptor}.
38   * Furthermore, some operations just make sense within transactions,
39   * for example: <code>evict</code>, <code>evictAll</code>, <code>flush</code>.
40   *
41   * <p>Updated to expose JDO 2.0 functionality, as of Spring 1.2:
42   * <code>detachCopy</code>, <code>attachCopy</code>, <code>findByNamedQuery</code>, etc.
43   * Those operations will by default only work on top of the standard JDO 2.0 API.
44   * Since Spring 1.2.2, the execution of those operations can also be adapted through
45   * the JdoDialect mechanism (for example, for vendor-specific pre-JDO2 methods).
46   *
47   * @author Juergen Hoeller
48   * @since 1.1
49   * @see JdoTemplate
50   * @see javax.jdo.PersistenceManager
51   * @see JdoTransactionManager
52   * @see JdoDialect
53   * @see org.springframework.orm.jdo.support.OpenPersistenceManagerInViewFilter
54   * @see org.springframework.orm.jdo.support.OpenPersistenceManagerInViewInterceptor
55   */
56  public interface JdoOperations {
57  
58      /**
59       * Execute the action specified by the given action object within a
60       * PersistenceManager. Application exceptions thrown by the action object
61       * get propagated to the caller (can only be unchecked). JDO exceptions
62       * are transformed into appropriate DAO ones. Allows for returning a
63       * result object, i.e. a domain object or a collection of domain objects.
64       * <p>Note: Callback code is not supposed to handle transactions itself!
65       * Use an appropriate transaction manager like JdoTransactionManager.
66       * @param action callback object that specifies the JDO action
67       * @return a result object returned by the action, or <code>null</code>
68       * @throws org.springframework.dao.DataAccessException in case of JDO errors
69       * @see JdoTransactionManager
70       * @see org.springframework.dao
71       * @see org.springframework.transaction
72       * @see javax.jdo.PersistenceManager
73       */
74      Object   execute(JdoCallback action) throws DataAccessException;
75  
76      /**
77       * Execute the specified action assuming that the result object is a
78       * Collection. This is a convenience method for executing JDO queries
79       * within an action.
80       * @param action callback object that specifies the JDO action
81       * @return a Collection result returned by the action, or <code>null</code>
82       * @throws org.springframework.dao.DataAccessException in case of JDO errors
83       */
84      Collection   executeFind(JdoCallback action) throws DataAccessException;
85  
86  
87      //-------------------------------------------------------------------------
88      // Convenience methods for load, save, delete
89      //-------------------------------------------------------------------------
90  
91      /**
92       * Return the persistent instance with the given JDO object id,
93       * throwing an exception if not found.
94       * <p>A JDO object id identifies both the persistent class and the id
95       * within the namespace of that class.
96       * @param objectId a JDO object id of the persistent instance
97       * @return the persistent instance
98       * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
99       * @throws org.springframework.dao.DataAccessException in case of JDO errors
100      * @see javax.jdo.PersistenceManager#getObjectById(Object, boolean)
101      */
102     Object   getObjectById(Object   objectId) throws DataAccessException;
103 
104     /**
105      * Return the persistent instance of the given entity class
106      * with the given id value, throwing an exception if not found.
107      * <p>The given id value is typically just unique within the namespace
108      * of the persistent class. Its toString value must correspond to the
109      * toString value of the corresponding JDO object id.
110      * <p>Usually, the passed-in value will have originated from the primary
111      * key field of a persistent object that uses JDO's application identity.
112      * @param entityClass a persistent class
113      * @param idValue an id value of the persistent instance
114      * @return the persistent instance
115      * @throws org.springframework.orm.ObjectRetrievalFailureException if not found
116      * @throws org.springframework.dao.DataAccessException in case of JDO errors
117      * @see javax.jdo.PersistenceManager#getObjectById(Object, boolean)
118      * @see javax.jdo.PersistenceManager#getObjectById(Class, Object)
119      */
120     Object   getObjectById(Class   entityClass, Object   idValue) throws DataAccessException;
121 
122     /**
123      * Remove the given object from the PersistenceManager cache.
124      * @param entity the persistent instance to evict
125      * @throws org.springframework.dao.DataAccessException in case of JDO errors
126      * @see javax.jdo.PersistenceManager#evict(Object)
127      */
128     void evict(Object   entity) throws DataAccessException;
129 
130     /**
131      * Remove all given objects from the PersistenceManager cache.
132      * @param entities the persistent instances to evict
133      * @throws org.springframework.dao.DataAccessException in case of JDO errors
134      * @see javax.jdo.PersistenceManager#evictAll(java.util.Collection)
135      */
136     void evictAll(Collection   entities) throws DataAccessException;
137 
138     /**
139      * Remove all objects from the PersistenceManager cache.
140      * @throws org.springframework.dao.DataAccessException in case of JDO errors
141      * @see javax.jdo.PersistenceManager#evictAll()
142      */
143     void evictAll() throws DataAccessException;
144 
145     /**
146      * Re-read the state of the given persistent instance.
147      * @param entity the persistent instance to re-read
148      * @throws org.springframework.dao.DataAccessException in case of JDO errors
149      * @see javax.jdo.PersistenceManager#refresh(Object)
150      */
151     void refresh(Object   entity) throws DataAccessException;
152 
153     /**
154      * Re-read the state of all given persistent instances.
155      * @param entities the persistent instances to re-read
156      * @throws org.springframework.dao.DataAccessException in case of JDO errors
157      * @see javax.jdo.PersistenceManager#refreshAll(java.util.Collection)
158      */
159     void refreshAll(Collection   entities) throws DataAccessException;
160 
161     /**
162      * Re-read the state of all persistent instances.
163      * @throws org.springframework.dao.DataAccessException in case of JDO errors
164      * @see javax.jdo.PersistenceManager#refreshAll()
165      */
166     void refreshAll() throws DataAccessException;
167 
168     /**
169      * Make the given transient instance persistent.
170      * @param entity the transient instance to make persistent
171      * @throws org.springframework.dao.DataAccessException in case of JDO errors
172      * @see javax.jdo.PersistenceManager#makePersistent(Object)
173      */
174     void makePersistent(Object   entity) throws DataAccessException;
175 
176     /**
177      * Make the given transient instances persistent.
178      * @param entities the transient instances to make persistent
179      * @throws org.springframework.dao.DataAccessException in case of JDO errors
180      * @see javax.jdo.PersistenceManager#makePersistentAll(java.util.Collection)
181      */
182     void makePersistentAll(Collection   entities) throws DataAccessException;
183 
184     /**
185      * Delete the given persistent instance.
186      * @param entity the persistent instance to delete
187      * @throws org.springframework.dao.DataAccessException in case of JDO errors
188      * @see javax.jdo.PersistenceManager#deletePersistent(Object)
189      */
190     void deletePersistent(Object   entity) throws DataAccessException;
191 
192     /**
193      * Delete all given persistent instances.
194      * <p>This can be combined with any of the find methods to delete by query
195      * in two lines of code.
196      * @param entities the persistent instances to delete
197      * @throws org.springframework.dao.DataAccessException in case of JDO errors
198      * @see javax.jdo.PersistenceManager#deletePersistentAll(java.util.Collection)
199      */
200     void deletePersistentAll(Collection   entities) throws DataAccessException;
201 
202     /**
203      * Detach a copy of the given persistent instance from the current JDO transaction,
204      * for use outside a JDO transaction (for example, as web form object).
205      * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
206      * @param entity the persistent instance to detach
207      * @see javax.jdo.PersistenceManager#detachCopy(Object)
208      */
209     Object   detachCopy(Object   entity);
210 
211     /**
212      * Detach copies of the given persistent instances from the current JDO transaction,
213      * for use outside a JDO transaction (for example, as web form objects).
214      * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
215      * @param entities the persistent instances to detach
216      * @see javax.jdo.PersistenceManager#detachCopyAll(Collection)
217      */
218     Collection   detachCopyAll(Collection   entities);
219 
220     /**
221      * Reattach the given detached instance (for example, a web form object) with
222      * the current JDO transaction, merging its changes into the current persistence
223      * instance that represents the corresponding entity.
224      * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
225      * Note that as of JDO 2.0 final, this operation is equivalent to a
226      * <code>makePersistent</code> call. This dedicated reattach operation
227      * now solely serves as distinction point for custom JdoDialects.
228      * It is still recommended to call this operation for enhanced adaptability.
229      * @param detachedEntity the detached instance to attach
230      * @return the corresponding persistent instance
231      * @see javax.jdo.PersistenceManager#makePersistent(Object)
232      */
233     Object   attachCopy(Object   detachedEntity);
234 
235     /**
236      * Reattach the given detached instances (for example, web form objects) with
237      * the current JDO transaction, merging their changes into the current persistence
238      * instances that represent the corresponding entities.
239      * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
240      * Note that as of JDO 2.0 final, this operation is equivalent to a
241      * <code>makePersistentAll</code> call. This dedicated reattach operation
242      * now solely serves as distinction point for custom JdoDialects.
243      * It is still recommended to call this operation for enhanced adaptability.
244      * @param detachedEntities the detached instances to reattach
245      * @return the corresponding persistent instances
246      * @see javax.jdo.PersistenceManager#makePersistentAll(java.util.Collection)
247      */
248     Collection   attachCopyAll(Collection   detachedEntities);
249 
250     /**
251      * Flush all transactional modifications to the database.
252      * <p>Only invoke this for selective eager flushing, for example when JDBC code
253      * needs to see certain changes within the same transaction. Else, it's preferable
254      * to rely on auto-flushing at transaction completion.
255      * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
256      * @throws org.springframework.dao.DataAccessException in case of JDO errors
257      * @see javax.jdo.PersistenceManager#flush()
258      * @see JdoDialect#flush(javax.jdo.PersistenceManager)
259      */
260     void flush() throws DataAccessException;
261 
262 
263     //-------------------------------------------------------------------------
264     // Convenience finder methods
265     //-------------------------------------------------------------------------
266 
267     /**
268      * Find all persistent instances of the given class.
269      * @param entityClass a persistent class
270      * @return the persistent instances
271      * @throws org.springframework.dao.DataAccessException in case of JDO errors
272      * @see javax.jdo.PersistenceManager#newQuery(Class)
273      */
274     Collection   find(Class   entityClass) throws DataAccessException;
275 
276     /**
277      * Find all persistent instances of the given class that match the given
278      * JDOQL filter.
279      * @param entityClass a persistent class
280      * @param filter the JDOQL filter to match (or <code>null</code> if none)
281      * @return the persistent instances
282      * @throws org.springframework.dao.DataAccessException in case of JDO errors
283      * @see javax.jdo.PersistenceManager#newQuery(Class, String)
284      */
285     Collection   find(Class   entityClass, String   filter) throws DataAccessException;
286 
287     /**
288      * Find all persistent instances of the given class that match the given
289      * JDOQL filter, with the given result ordering.
290      * @param entityClass a persistent class
291      * @param filter the JDOQL filter to match (or <code>null</code> if none)
292      * @param ordering the ordering of the result (or <code>null</code> if none)
293      * @return the persistent instances
294      * @throws org.springframework.dao.DataAccessException in case of JDO errors
295      * @see javax.jdo.PersistenceManager#newQuery(Class, String)
296      * @see javax.jdo.Query#setOrdering
297      */
298     Collection   find(Class   entityClass, String   filter, String   ordering) throws DataAccessException;
299 
300     /**
301      * Find all persistent instances of the given class that match the given
302      * JDOQL filter, using the given parameter declarations and parameter values.
303      * @param entityClass a persistent class
304      * @param filter the JDOQL filter to match
305      * @param parameters the JDOQL parameter declarations
306      * @param values the corresponding parameter values
307      * @return the persistent instances
308      * @throws org.springframework.dao.DataAccessException in case of JDO errors
309      * @see javax.jdo.PersistenceManager#newQuery(Class, String)
310      * @see javax.jdo.Query#declareParameters
311      * @see javax.jdo.Query#executeWithArray
312      */
313     Collection   find(Class   entityClass, String   filter, String   parameters, Object  [] values)
314             throws DataAccessException;
315 
316     /**
317      * Find all persistent instances of the given class that match the given
318      * JDOQL filter, using the given parameter declarations and parameter values,
319      * with the given result ordering.
320      * @param entityClass a persistent class
321      * @param filter the JDOQL filter to match
322      * @param parameters the JDOQL parameter declarations
323      * @param values the corresponding parameter values
324      * @param ordering the ordering of the result (or <code>null</code> if none)
325      * @return the persistent instances
326      * @throws org.springframework.dao.DataAccessException in case of JDO errors
327      * @see javax.jdo.PersistenceManager#newQuery(Class, String)
328      * @see javax.jdo.Query#declareParameters
329      * @see javax.jdo.Query#executeWithArray
330      * @see javax.jdo.Query#setOrdering
331      */
332     Collection   find(Class   entityClass, String   filter, String   parameters, Object  [] values, String   ordering)
333             throws DataAccessException;
334 
335     /**
336      * Find all persistent instances of the given class that match the given
337      * JDOQL filter, using the given parameter declarations and parameter values.
338      * @param entityClass a persistent class
339      * @param filter the JDOQL filter to match
340      * @param parameters the JDOQL parameter declarations
341      * @param values a Map with parameter names as keys and parameter values
342      * @return the persistent instances
343      * @throws org.springframework.dao.DataAccessException in case of JDO errors
344      * @see javax.jdo.PersistenceManager#newQuery(Class, String)
345      * @see javax.jdo.Query#declareParameters
346      * @see javax.jdo.Query#executeWithMap
347      */
348     Collection   find(Class   entityClass, String   filter, String   parameters, Map   values)
349             throws DataAccessException;
350 
351     /**
352      * Find all persistent instances of the given class that match the given
353      * JDOQL filter, using the given parameter declarations and parameter values,
354      * with the given result ordering.
355      * @param entityClass a persistent class
356      * @param filter the JDOQL filter to match
357      * @param parameters the JDOQL parameter declarations
358      * @param values a Map with parameter names as keys and parameter values
359      * @param ordering the ordering of the result (or <code>null</code> if none)
360      * @return the persistent instances
361      * @throws org.springframework.dao.DataAccessException in case of JDO errors
362      * @see javax.jdo.PersistenceManager#newQuery(Class, String)
363      * @see javax.jdo.Query#declareParameters
364      * @see javax.jdo.Query#executeWithMap
365      * @see javax.jdo.Query#setOrdering
366      */
367     Collection   find(Class   entityClass, String   filter, String   parameters, Map   values, String   ordering)
368             throws DataAccessException;
369 
370     /**
371      * Find persistent instances through the given query object
372      * in the specified query language.
373      * <p>Only available on JDO 2.0 and higher.
374      * @param language the query language (<code>javax.jdo.Query#JDOQL</code>
375      * or <code>javax.jdo.Query#SQL</code>, for example)
376      * @param queryObject the query object for the specified language
377      * @return the persistent instances
378      * @throws org.springframework.dao.DataAccessException in case of JDO errors
379      * @see javax.jdo.PersistenceManager#newQuery(String, Object)
380      * @see javax.jdo.Query#JDOQL
381      * @see javax.jdo.Query#SQL
382      */
383     Collection   find(String   language, Object   queryObject) throws DataAccessException;
384 
385     /**
386      * Find persistent instances through the given single-string JDOQL query.
387      * <p>Only available on JDO 2.0 and higher.
388      * @param queryString the single-string JDOQL query
389      * @return the persistent instances
390      * @throws org.springframework.dao.DataAccessException in case of JDO errors
391      * @see javax.jdo.PersistenceManager#newQuery(String)
392      */
393     Collection   find(String   queryString) throws DataAccessException;
394 
395     /**
396      * Find persistent instances through the given single-string JDOQL query.
397      * <p>Only available on JDO 2.0 and higher.
398      * @param queryString the single-string JDOQL query
399      * @param values the corresponding parameter values
400      * @return the persistent instances
401      * @throws org.springframework.dao.DataAccessException in case of JDO errors
402      * @see javax.jdo.PersistenceManager#newQuery(String)
403      */
404     Collection   find(String   queryString, Object  [] values) throws DataAccessException;
405 
406     /**
407      * Find persistent instances through the given single-string JDOQL query.
408      * <p>Only available on JDO 2.0 and higher.
409      * @param queryString the single-string JDOQL query
410      * @param values a Map with parameter names as keys and parameter values
411      * @return the persistent instances
412      * @throws org.springframework.dao.DataAccessException in case of JDO errors
413      * @see javax.jdo.PersistenceManager#newQuery(String)
414      */
415     Collection   find(String   queryString, Map   values) throws DataAccessException;
416 
417     /**
418      * Find persistent instances through the given named query.
419      * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
420      * @param entityClass a persistent class
421      * @param queryName the name of the query
422      * @return the persistent instances
423      * @throws org.springframework.dao.DataAccessException in case of JDO errors
424      * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
425      */
426     Collection   findByNamedQuery(Class   entityClass, String   queryName) throws DataAccessException;
427 
428     /**
429      * Find persistent instances through the given named query.
430      * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
431      * @param entityClass a persistent class
432      * @param queryName the name of the query
433      * @param values the corresponding parameter values
434      * @return the persistent instances
435      * @throws org.springframework.dao.DataAccessException in case of JDO errors
436      * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
437      */
438     Collection   findByNamedQuery(Class   entityClass, String   queryName, Object  [] values) throws DataAccessException;
439 
440     /**
441      * Find persistent instances through the given named query.
442      * <p>Only available on JDO 2.0+ or through a vendor-specific JdoDialect.
443      * @param entityClass a persistent class
444      * @param queryName the name of the query
445      * @param values a Map with parameter names as keys and parameter values
446      * @return the persistent instances
447      * @throws org.springframework.dao.DataAccessException in case of JDO errors
448      * @see javax.jdo.PersistenceManager#newNamedQuery(Class, String)
449      */
450     Collection   findByNamedQuery(Class   entityClass, String   queryName, Map   values) throws DataAccessException;
451 
452 }
453
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags