PersistenceBroker


1   package org.apache.ojb.broker;
2   
3   /* Copyright 2002-2005 The Apache Software Foundation
4    *
5    * Licensed under the Apache License, Version 2.0 (the "License");
6    * you may not use this file except in compliance with the License.
7    * You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  import org.apache.ojb.broker.accesslayer.ConnectionManagerIF;
19  import org.apache.ojb.broker.accesslayer.JdbcAccess;
20  import org.apache.ojb.broker.accesslayer.StatementManagerIF;
21  import org.apache.ojb.broker.accesslayer.sql.SqlGenerator;
22  import org.apache.ojb.broker.cache.ObjectCache;
23  import org.apache.ojb.broker.metadata.ClassDescriptor;
24  import org.apache.ojb.broker.metadata.DescriptorRepository;
25  import org.apache.ojb.broker.query.Query;
26  import org.apache.ojb.broker.util.BrokerHelper;
27  import org.apache.ojb.broker.util.ObjectModification;
28  import org.apache.ojb.broker.util.configuration.Configurable;
29  import org.apache.ojb.broker.util.sequence.SequenceManager;
30  import org.odbms.ObjectContainer;
31  
32  import java.util.Collection  ;
33  import java.util.Enumeration  ;
34  import java.util.Iterator  ;
35  
36  /**
37   *
38   * PersistenceBroker declares a protocol for persisting arbitrary objects.
39   * A typical implementation might wrap an RDBMS access layer.
40   *
41   * @see org.apache.ojb.broker.core.PersistenceBrokerImpl
42   * @see org.apache.ojb.broker.core.PersistenceBrokerBean
43   *
44   * @author Thomas Mahler
45   * @version $Id: PersistenceBroker.java,v 1.30.2.6 2005/12/22 20:40:17 tomdz Exp $
46   */
47  public interface PersistenceBroker extends Configurable, ObjectContainer
48  {
49      // *************************************************************************
50      // Services handled by the PersistenceBroker
51      // *************************************************************************
52  
53      /**
54       * Returns the {@link org.apache.ojb.broker.accesslayer.StatementManagerIF} instance associated with this broker.
55       * 
56       * @return The statement manager
57       */
58      public StatementManagerIF serviceStatementManager();
59  
60      /**
61       * Returns the {@link org.apache.ojb.broker.accesslayer.ConnectionManagerIF} instance associated with this broker.
62       * 
63       * @return The connection manager
64       */
65      public ConnectionManagerIF serviceConnectionManager();
66  
67      /**
68       * Returns the {@link org.apache.ojb.broker.accesslayer.sql.SqlGenerator} instance associated with this broker.
69       * 
70       * @return The SQL generator
71       */
72      public SqlGenerator serviceSqlGenerator();
73  
74      /**
75       * Returns the {@link org.apache.ojb.broker.accesslayer.JdbcAccess} instance associated with this broker.
76       * 
77       * @return The JDBC access object
78       */
79      public JdbcAccess serviceJdbcAccess();
80  
81      /**
82       * Returns the {@link org.apache.ojb.broker.util.sequence.SequenceManager} instance associated with this broker.
83       * 
84       * @return The sequence manager
85       */
86      public SequenceManager serviceSequenceManager();
87  
88      /**
89       * Returns the {@link org.apache.ojb.broker.util.BrokerHelper} instance associated with this broker, which
90       * makes some additional helper methods available.
91       * 
92       * @return The broker helper object
93       */
94      public BrokerHelper serviceBrokerHelper();
95  
96      /**
97       * Returns the {@link org.apache.ojb.broker.cache.ObjectCache} instance associated
98       * with this broker.
99       * 
100      * @return The object cache
101      */
102     public ObjectCache serviceObjectCache();
103 
104     /**
105      * Return the {@link IdentityFactory} instance associated with this broker.
106      * 
107      * @return The identity factory
108      */
109     public IdentityFactory serviceIdentity();
110 
111 
112     // *************************************************************************
113     // PersistenceBroker listener methods
114     // *************************************************************************
115 
116     /**
117      * Fires a broker event to inform all registered {@link PBListener} instances.
118      * 
119      * @param event The event to fire
120      */
121     public void fireBrokerEvent(PersistenceBrokerEvent event);
122 
123     /**
124      * Fires a life cycle event to inform all registered {@link PBListener} instances.
125      * 
126      * @param event The event to fire
127      */
128     public void fireBrokerEvent(PBLifeCycleEvent event);
129 
130     /**
131      * Fires a state event to inform all registered {@link PBListener} instances.
132      * 
133      * @param event The event to fire
134      */
135     public void fireBrokerEvent(PBStateEvent event);
136 
137     /**
138      * Removes all temporary listeners from this broker.
139      * Use with care, because some internals rely on this mechanism.
140      * 
141      * @see #removeListener(PBListener)
142      */
143     public void removeAllListeners() throws PersistenceBrokerException;
144 
145     /**
146      * Removes all temporary and, if desired, permanent listeners from this broker.
147      * Use with care, because some internals rely on this mechanism.
148      * 
149      * @param permanent Whether the listener will stay registered after closing
150      *                  the broker
151      * @see #removeListener(PBListener)
152      */
153     public void removeAllListeners(boolean permanent) throws PersistenceBrokerException;
154 
155 
156     /**
157      * Adds a temporary {@link org.apache.ojb.broker.PBListener} to this broker.
158      * Note that temporary listeners will be removed upon closing a broker (returning
159      * it to the pool).
160      *
161      * @param listener The listener to add
162      * @see #addListener(PBListener, boolean)
163      */
164     public void addListener(PBListener listener) throws PersistenceBrokerException;
165 
166     /**
167      * Adds a temporary or permanent {@link org.apache.ojb.broker.PBListener} to this broker,
168      * depending on the parameter value. Note that temporary listeners will be removed upon
169      * closing a broker (returning it to the pool).
170      * <br/>
171      * <b>NOTE:</b> Handle carefully when using this method, keep in mind you don't
172      * know which broker instance will be returned next time from the pool! To guarantee that
173      * a listener is connect to every broker, the best way is to define your own implementation of
174      * {@link org.apache.ojb.broker.core.PersistenceBrokerFactoryIF} or extend the default
175      * one, {@link org.apache.ojb.broker.core.PersistenceBrokerFactoryDefaultImpl}. There you
176      * can add the listener at creation of the {@link org.apache.ojb.broker.PersistenceBroker}
177      * instances.
178      * 
179      * @param listener  The listener to add
180      * @param permanent Whether the listener will stay registered after closing
181      *                  the broker
182      */
183     public void addListener(PBListener listener, boolean permanent) throws PersistenceBrokerException;
184 
185     /**
186      * Removes the specified listener from this broker.
187      * 
188      * @param listener The listener to remove
189      */
190     public void removeListener(PBListener listener) throws PersistenceBrokerException;
191 
192 
193     // *************************************************************************
194     // Transaction and instance handling stuff
195     // *************************************************************************
196 
197     /**
198      * Aborts and closes the current transaction. This abandons all persistent object modifications
199      * and releases the associated locks.
200      * 
201      * @throws TransactionNotInProgressException If no transaction is currently in progress
202      */
203     public void abortTransaction() throws TransactionNotInProgressException;
204 
205     /**
206      * Begins a transaction against the underlying RDBMS.
207      * 
208      * @throws TransactionInProgressException If there is already a transaction in progress
209      */
210     public void beginTransaction() throws TransactionInProgressException, TransactionAbortedException;
211 
212     /**
213      * Commits and closes the current transaction. This commits all database-changing statements (e.g.
214      * UPDATE, INSERT and DELETE) issued within the transaction since the last commit to the database,
215      * and releases any locks held by the transaction.
216      * 
217      * @throws TransactionNotInProgressException If there is no transaction currently in progress
218      * @throws TransactionAbortedException       If the transaction cannot be committed
219      */
220     public void commitTransaction() throws TransactionNotInProgressException, TransactionAbortedException;
221 
222     /**
223      * Determines whether there is currently a transaction in progress.
224      * 
225      * @return <code>true</code> if there is a transaction in progress
226      */
227     public boolean isInTransaction() throws PersistenceBrokerException;
228 
229     /**
230      * Closes this broker so that no further requests may be made on it. Closing a broker might release
231      * it to the pool of available brokers, or might be garbage collected, at the option of the implementation.
232      *
233      * @return <code>true</code> if the broker was successfully closed
234      */
235     public boolean close();
236 
237     /**
238      * Determines whether this broker is closed.
239      * 
240      * @return <tt>true</tt> if this instance is closed
241      */
242     public boolean isClosed();
243 
244 
245 
246     // *************************************************************************
247     // Metadata service methods
248     // *************************************************************************
249 
250     /**
251      * Returns the metadata descriptor repository associated with this broker.
252      * 
253      * @return The descriptor repository
254      */
255     public DescriptorRepository getDescriptorRepository();
256 
257     /**
258      * Get the {@link PBKey} for this broker.
259      * 
260      * @return The broker key
261      */
262     public PBKey getPBKey();
263 
264     /**
265      * Returns the class descriptor for the given persistence capable class.
266      * 
267      * @param clazz The target class
268      * @return The class descriptor
269      * @throws PersistenceBrokerException If the class is not persistence capable, i.e.
270      *         if no metadata was defined for this class and hence its class descriptor
271      *         was not found
272      */
273     public ClassDescriptor getClassDescriptor(Class   clazz) throws PersistenceBrokerException;
274 
275     /**
276      * Determines whether the given class is persistence capable and thus has an associated
277      * class descriptor in the metadata.
278      * 
279      * @param clazz The target class
280      * @return <code>true</code> if a class descriptor was found
281      */
282     public boolean hasClassDescriptor(Class   clazz);
283 
284     /**
285      * Returns the top level class (most abstract class in terms of extents) from which the
286      * given class extends. This may be a (abstract) base-class, an interface or the given
287      * class itself, if no extent is defined.
288      *
289      * @param clazz The class to get the top level class for
290      * @return The top level class for it
291      * @throws PersistenceBrokerException If the class is not persistence capable,
292      *         if no metadata was defined for this class
293      */
294     public Class   getTopLevelClass(Class   clazz) throws PersistenceBrokerException;
295 
296     // *************************************************************************
297     // Object lifecycle
298     // *************************************************************************
299 
300     /**
301      * Clears the broker's internal cache.
302      */
303     public void clearCache() throws PersistenceBrokerException;
304 
305     /**
306      * Removes the given object or, if it is an instance of {@link org.apache.ojb.broker.Identity},
307      * the object identified by it, from the broker's internal cache. Note that the removal is
308      * not recursive. This means, objects referenced by the removed object will not be
309      * automatically removed from the cache by this operation.
310      * 
311      * @param objectOrIdentity The object to be removed from the cache or its identity 
312      */
313     public void removeFromCache(Object   objectOrIdentity) throws PersistenceBrokerException;
314 
315     /**
316      * Makes the given object persistent in the underlying persistence system.
317      * This is usually done by issuing an INSERT ... or UPDATE ...  in an RDBMS.
318      *
319      * @param obj The object to store
320      * @param modification Specifies what operation to perform (for generating optimized SQL)
321      */
322     public void store(Object   obj,
323                       ObjectModification modification) throws PersistenceBrokerException;
324 
325     /**
326      * Make the given object persistent in the underlying persistence system.
327      * This is usually done by issuing an INSERT ... or UPDATE ...  in an RDBMS.
328      * 
329      * @param obj The object to store
330      */
331     public void store(Object   obj) throws PersistenceBrokerException;
332 
333     /**
334      * Deletes the given object's persistent representation in the underlying persistence system.
335      * This is usually done by issuing a DELETE ... in an RDBMS
336      * 
337      * @param obj The object to delete
338      */
339     public void delete(Object   obj) throws PersistenceBrokerException;
340 
341     /**
342      * Deletes an m:n implementor which defines the relationship between two persistent objects.
343      * This is usually a row in an indirection table.<br/>
344      * Note that OJB currently doesn't handle collection inheritance, so collections descriptors
345      * are written per class. We try to match one of these collection descriptors, iterating from the left side
346      * and looking for possible for classes on the right side using isAssignableFrom(rightClass).
347      *
348      * TODO: handle cache problems
349      * TODO: delete more than one row if possible
350      * 
351      * @param m2nImpl The m:n implementor to delete
352      */
353     public void deleteMtoNImplementor(MtoNImplementor m2nImpl) throws PersistenceBrokerException;
354 
355     /**
356      * Stores the given m:n implementor int the underlying persistence system. 
357      * This is usually done by inserting a row in an indirection table.<br/>
358      * Note that OJB currently doesn't handle collection inheritance, so collections descriptors
359      * are written per class. We try to match one of these collection descriptors, iterating from the left side
360      * and looking for possible for classes on the right side using isAssignableFrom(rightClass).
361      * 
362      * @param m2nImpl The m:n implementor to delete
363      */
364     public void addMtoNImplementor(MtoNImplementor m2nImpl) throws PersistenceBrokerException;
365 
366     /**
367      * Deletes all objects matching the given query, from the underlying persistence system.
368      * This is usually done via DELETE ... in an RDBMS.<br/>
369      * <b>Note:</b> This method directly perform the delete statement ignoring any object
370      * references and does not synchronize the cache - take care!
371      * 
372      * @param query The query determining the objects to delete
373      */
374     public void deleteByQuery(Query query) throws PersistenceBrokerException;
375 
376     // *************************************************************************
377     // Query methods
378     // *************************************************************************
379 
380     /**
381      * Retrieve all references and collections of the given object irrespective of the
382      * metadata settings defined for them.
383      *  
384      * @param obj The persistent object
385      */
386     public void retrieveAllReferences(Object   obj) throws PersistenceBrokerException;
387 
388     /**
389      * Retrieve the specified reference or collection attribute for the given persistent object.
390      * 
391      * @param obj      The persistent object
392      * @param attrName The name of the attribute to retrieve
393      */
394     public void retrieveReference(Object   obj, String   attrName) throws PersistenceBrokerException;
395 
396     /**
397      * Returns the number of elements that the given query will return.
398      * 
399      * @param query The query
400      * @return The number of elements returned by the query
401      */
402     public int getCount(Query query) throws PersistenceBrokerException;
403 
404     /**
405      * Retrieves the persistent objects matching the given query. Note that if the Query has
406      * no criteria ALL persistent objects of the class targeted by the query will be returned.
407      * 
408      * @param query The query
409      * @return The persistent objects matching the query
410      */
411     public Collection   getCollectionByQuery(Query query) throws PersistenceBrokerException;
412 
413     /**
414      * Retrieves the persistent objects matching the given query. The resulting collection will
415      * be of the supplied collection type. Note that if the Query has no criteria ALL persistent
416      * objects of the class targeted by the query will be returned.
417      * 
418      * @param collectionClass The collection type which needs to implement
419      *                        {@link ManageableCollection}
420      * @param query           The query
421      * @return The persistent objects matching the query
422      */
423     public ManageableCollection getCollectionByQuery(Class   collectionClass, Query query)
424             throws PersistenceBrokerException;
425 
426     /**
427      * Retrieves the persistent objects matching the given query and returns them as an iterator
428      * which may, depending on the configured collection type, be reloading the objects from
429      * the database upon calling {@link Iterator#next()}. Note that if the Query has no criteria
430      * ALL persistent objects of the class targeted by the query will be returned.
431      * 
432      * @param query The query
433      * @return The persistent objects matching the query
434      */
435     public Iterator   getIteratorByQuery(Query query) throws PersistenceBrokerException;
436 
437     /**
438      * Retrieves the rows (as <code>Object[]</code> instances) matching the given query and
439      * returns them as an iterator which may, depending on the configured collection type, be reloading
440      * the objects from the database upon calling {@link Iterator#next()}.
441      * 
442      * @param query The report query
443      * @return The rows matching the query
444      */
445     public Iterator   getReportQueryIteratorByQuery(Query query) throws PersistenceBrokerException;
446 
447     /**
448      * Retrieve a persistent object from the underlying datastore by its identity. However, users
449      * are encouraged to use {@link #getObjectByQuery(Query)} instead, as this method is mainly
450      * intended to be used for internal handling of materialization by OID (e.g. in Proxies).
451      * 
452      * @param id The persistent object's id
453      * @return The persistent object
454      */
455     public Object   getObjectByIdentity(Identity id) throws PersistenceBrokerException;
456 
457     /**
458      * Retrieve the (first) persistent object from the underlying datastore that matches the given
459      * query.
460      * 
461      * @param query The query
462      * @return The persistent object
463      */
464     public Object   getObjectByQuery(Query query) throws PersistenceBrokerException;
465 
466     /**
467      * Returns an enumeration of objects representing the primary keys for the objects that match
468      * the given query. Mainly useful for EJB Finder Methods.<br/>
469      * <b>Note:</b> This method is not yet aware of extents!
470      * 
471      * @param pkClass The class to use for the primary keys
472      * @param query   The query
473      * @return The pk enumeration
474      */
475     public Enumeration   getPKEnumerationByQuery(Class   pkClass, Query query)
476             throws PersistenceBrokerException;
477 }
478
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags