001: package org.apache.ojb.broker;
002:
003: /* Copyright 2002-2005 The Apache Software Foundation
004: *
005: * Licensed under the Apache License, Version 2.0 (the "License");
006: * you may not use this file except in compliance with the License.
007: * You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: import org.apache.ojb.broker.accesslayer.ConnectionManagerIF;
019: import org.apache.ojb.broker.accesslayer.JdbcAccess;
020: import org.apache.ojb.broker.accesslayer.StatementManagerIF;
021: import org.apache.ojb.broker.accesslayer.sql.SqlGenerator;
022: import org.apache.ojb.broker.cache.ObjectCache;
023: import org.apache.ojb.broker.metadata.ClassDescriptor;
024: import org.apache.ojb.broker.metadata.DescriptorRepository;
025: import org.apache.ojb.broker.query.Query;
026: import org.apache.ojb.broker.util.BrokerHelper;
027: import org.apache.ojb.broker.util.ObjectModification;
028: import org.apache.ojb.broker.util.configuration.Configurable;
029: import org.apache.ojb.broker.util.sequence.SequenceManager;
030: import org.odbms.ObjectContainer;
031:
032: import java.util.Collection;
033: import java.util.Enumeration;
034: import java.util.Iterator;
035:
036: /**
037: *
038: * PersistenceBroker declares a protocol for persisting arbitrary objects.
039: * A typical implementation might wrap an RDBMS access layer.
040: *
041: * @see org.apache.ojb.broker.core.PersistenceBrokerImpl
042: * @see org.apache.ojb.broker.core.PersistenceBrokerBean
043: *
044: * @author Thomas Mahler
045: * @version $Id: PersistenceBroker.java,v 1.30.2.6 2005/12/22 20:40:17 tomdz Exp $
046: */
047: public interface PersistenceBroker extends Configurable,
048: ObjectContainer {
049: // *************************************************************************
050: // Services handled by the PersistenceBroker
051: // *************************************************************************
052:
053: /**
054: * Returns the {@link org.apache.ojb.broker.accesslayer.StatementManagerIF} instance associated with this broker.
055: *
056: * @return The statement manager
057: */
058: public StatementManagerIF serviceStatementManager();
059:
060: /**
061: * Returns the {@link org.apache.ojb.broker.accesslayer.ConnectionManagerIF} instance associated with this broker.
062: *
063: * @return The connection manager
064: */
065: public ConnectionManagerIF serviceConnectionManager();
066:
067: /**
068: * Returns the {@link org.apache.ojb.broker.accesslayer.sql.SqlGenerator} instance associated with this broker.
069: *
070: * @return The SQL generator
071: */
072: public SqlGenerator serviceSqlGenerator();
073:
074: /**
075: * Returns the {@link org.apache.ojb.broker.accesslayer.JdbcAccess} instance associated with this broker.
076: *
077: * @return The JDBC access object
078: */
079: public JdbcAccess serviceJdbcAccess();
080:
081: /**
082: * Returns the {@link org.apache.ojb.broker.util.sequence.SequenceManager} instance associated with this broker.
083: *
084: * @return The sequence manager
085: */
086: public SequenceManager serviceSequenceManager();
087:
088: /**
089: * Returns the {@link org.apache.ojb.broker.util.BrokerHelper} instance associated with this broker, which
090: * makes some additional helper methods available.
091: *
092: * @return The broker helper object
093: */
094: public BrokerHelper serviceBrokerHelper();
095:
096: /**
097: * Returns the {@link org.apache.ojb.broker.cache.ObjectCache} instance associated
098: * with this broker.
099: *
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: // PersistenceBroker listener methods
113: // *************************************************************************
114:
115: /**
116: * Fires a broker event to inform all registered {@link PBListener} instances.
117: *
118: * @param event The event to fire
119: */
120: public void fireBrokerEvent(PersistenceBrokerEvent event);
121:
122: /**
123: * Fires a life cycle event to inform all registered {@link PBListener} instances.
124: *
125: * @param event The event to fire
126: */
127: public void fireBrokerEvent(PBLifeCycleEvent event);
128:
129: /**
130: * Fires a state event to inform all registered {@link PBListener} instances.
131: *
132: * @param event The event to fire
133: */
134: public void fireBrokerEvent(PBStateEvent event);
135:
136: /**
137: * Removes all temporary listeners from this broker.
138: * Use with care, because some internals rely on this mechanism.
139: *
140: * @see #removeListener(PBListener)
141: */
142: public void removeAllListeners() throws PersistenceBrokerException;
143:
144: /**
145: * Removes all temporary and, if desired, permanent listeners from this broker.
146: * Use with care, because some internals rely on this mechanism.
147: *
148: * @param permanent Whether the listener will stay registered after closing
149: * the broker
150: * @see #removeListener(PBListener)
151: */
152: public void removeAllListeners(boolean permanent)
153: throws PersistenceBrokerException;
154:
155: /**
156: * Adds a temporary {@link org.apache.ojb.broker.PBListener} to this broker.
157: * Note that temporary listeners will be removed upon closing a broker (returning
158: * it to the pool).
159: *
160: * @param listener The listener to add
161: * @see #addListener(PBListener, boolean)
162: */
163: public void addListener(PBListener listener)
164: 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)
184: throws PersistenceBrokerException;
185:
186: /**
187: * Removes the specified listener from this broker.
188: *
189: * @param listener The listener to remove
190: */
191: public void removeListener(PBListener listener)
192: throws PersistenceBrokerException;
193:
194: // *************************************************************************
195: // Transaction and instance handling stuff
196: // *************************************************************************
197:
198: /**
199: * Aborts and closes the current transaction. This abandons all persistent object modifications
200: * and releases the associated locks.
201: *
202: * @throws TransactionNotInProgressException If no transaction is currently in progress
203: */
204: public void abortTransaction()
205: throws TransactionNotInProgressException;
206:
207: /**
208: * Begins a transaction against the underlying RDBMS.
209: *
210: * @throws TransactionInProgressException If there is already a transaction in progress
211: */
212: public void beginTransaction()
213: throws TransactionInProgressException,
214: TransactionAbortedException;
215:
216: /**
217: * Commits and closes the current transaction. This commits all database-changing statements (e.g.
218: * UPDATE, INSERT and DELETE) issued within the transaction since the last commit to the database,
219: * and releases any locks held by the transaction.
220: *
221: * @throws TransactionNotInProgressException If there is no transaction currently in progress
222: * @throws TransactionAbortedException If the transaction cannot be committed
223: */
224: public void commitTransaction()
225: throws TransactionNotInProgressException,
226: TransactionAbortedException;
227:
228: /**
229: * Determines whether there is currently a transaction in progress.
230: *
231: * @return <code>true</code> if there is a transaction in progress
232: */
233: public boolean isInTransaction() throws PersistenceBrokerException;
234:
235: /**
236: * Closes this broker so that no further requests may be made on it. Closing a broker might release
237: * it to the pool of available brokers, or might be garbage collected, at the option of the implementation.
238: *
239: * @return <code>true</code> if the broker was successfully closed
240: */
241: public boolean close();
242:
243: /**
244: * Determines whether this broker is closed.
245: *
246: * @return <tt>true</tt> if this instance is closed
247: */
248: public boolean isClosed();
249:
250: // *************************************************************************
251: // Metadata service methods
252: // *************************************************************************
253:
254: /**
255: * Returns the metadata descriptor repository associated with this broker.
256: *
257: * @return The descriptor repository
258: */
259: public DescriptorRepository getDescriptorRepository();
260:
261: /**
262: * Get the {@link PBKey} for this broker.
263: *
264: * @return The broker key
265: */
266: public PBKey getPBKey();
267:
268: /**
269: * Returns the class descriptor for the given persistence capable class.
270: *
271: * @param clazz The target class
272: * @return The class descriptor
273: * @throws PersistenceBrokerException If the class is not persistence capable, i.e.
274: * if no metadata was defined for this class and hence its class descriptor
275: * was not found
276: */
277: public ClassDescriptor getClassDescriptor(Class clazz)
278: throws PersistenceBrokerException;
279:
280: /**
281: * Determines whether the given class is persistence capable and thus has an associated
282: * class descriptor in the metadata.
283: *
284: * @param clazz The target class
285: * @return <code>true</code> if a class descriptor was found
286: */
287: public boolean hasClassDescriptor(Class clazz);
288:
289: /**
290: * Returns the top level class (most abstract class in terms of extents) from which the
291: * given class extends. This may be a (abstract) base-class, an interface or the given
292: * class itself, if no extent is defined.
293: *
294: * @param clazz The class to get the top level class for
295: * @return The top level class for it
296: * @throws PersistenceBrokerException If the class is not persistence capable,
297: * if no metadata was defined for this class
298: */
299: public Class getTopLevelClass(Class clazz)
300: throws PersistenceBrokerException;
301:
302: // *************************************************************************
303: // Object lifecycle
304: // *************************************************************************
305:
306: /**
307: * Clears the broker's internal cache.
308: */
309: public void clearCache() throws PersistenceBrokerException;
310:
311: /**
312: * Removes the given object or, if it is an instance of {@link org.apache.ojb.broker.Identity},
313: * the object identified by it, from the broker's internal cache. Note that the removal is
314: * not recursive. This means, objects referenced by the removed object will not be
315: * automatically removed from the cache by this operation.
316: *
317: * @param objectOrIdentity The object to be removed from the cache or its identity
318: */
319: public void removeFromCache(Object objectOrIdentity)
320: throws PersistenceBrokerException;
321:
322: /**
323: * Makes the given object persistent in the underlying persistence system.
324: * This is usually done by issuing an INSERT ... or UPDATE ... in an RDBMS.
325: *
326: * @param obj The object to store
327: * @param modification Specifies what operation to perform (for generating optimized SQL)
328: */
329: public void store(Object obj, ObjectModification modification)
330: throws PersistenceBrokerException;
331:
332: /**
333: * Make the given object persistent in the underlying persistence system.
334: * This is usually done by issuing an INSERT ... or UPDATE ... in an RDBMS.
335: *
336: * @param obj The object to store
337: */
338: public void store(Object obj) throws PersistenceBrokerException;
339:
340: /**
341: * Deletes the given object's persistent representation in the underlying persistence system.
342: * This is usually done by issuing a DELETE ... in an RDBMS
343: *
344: * @param obj The object to delete
345: */
346: public void delete(Object obj) throws PersistenceBrokerException;
347:
348: /**
349: * Deletes an m:n implementor which defines the relationship between two persistent objects.
350: * This is usually a row in an indirection table.<br/>
351: * Note that OJB currently doesn't handle collection inheritance, so collections descriptors
352: * are written per class. We try to match one of these collection descriptors, iterating from the left side
353: * and looking for possible for classes on the right side using isAssignableFrom(rightClass).
354: *
355: * TODO: handle cache problems
356: * TODO: delete more than one row if possible
357: *
358: * @param m2nImpl The m:n implementor to delete
359: */
360: public void deleteMtoNImplementor(MtoNImplementor m2nImpl)
361: throws PersistenceBrokerException;
362:
363: /**
364: * Stores the given m:n implementor int the underlying persistence system.
365: * This is usually done by inserting a row in an indirection table.<br/>
366: * Note that OJB currently doesn't handle collection inheritance, so collections descriptors
367: * are written per class. We try to match one of these collection descriptors, iterating from the left side
368: * and looking for possible for classes on the right side using isAssignableFrom(rightClass).
369: *
370: * @param m2nImpl The m:n implementor to delete
371: */
372: public void addMtoNImplementor(MtoNImplementor m2nImpl)
373: throws PersistenceBrokerException;
374:
375: /**
376: * Deletes all objects matching the given query, from the underlying persistence system.
377: * This is usually done via DELETE ... in an RDBMS.<br/>
378: * <b>Note:</b> This method directly perform the delete statement ignoring any object
379: * references and does not synchronize the cache - take care!
380: *
381: * @param query The query determining the objects to delete
382: */
383: public void deleteByQuery(Query query)
384: throws PersistenceBrokerException;
385:
386: // *************************************************************************
387: // Query methods
388: // *************************************************************************
389:
390: /**
391: * Retrieve all references and collections of the given object irrespective of the
392: * metadata settings defined for them.
393: *
394: * @param obj The persistent object
395: */
396: public void retrieveAllReferences(Object obj)
397: throws PersistenceBrokerException;
398:
399: /**
400: * Retrieve the specified reference or collection attribute for the given persistent object.
401: *
402: * @param obj The persistent object
403: * @param attrName The name of the attribute to retrieve
404: */
405: public void retrieveReference(Object obj, String attrName)
406: throws PersistenceBrokerException;
407:
408: /**
409: * Returns the number of elements that the given query will return.
410: *
411: * @param query The query
412: * @return The number of elements returned by the query
413: */
414: public int getCount(Query query) throws PersistenceBrokerException;
415:
416: /**
417: * Retrieves the persistent objects matching the given query. Note that if the Query has
418: * no criteria ALL persistent objects of the class targeted by the query will be returned.
419: *
420: * @param query The query
421: * @return The persistent objects matching the query
422: */
423: public Collection getCollectionByQuery(Query query)
424: throws PersistenceBrokerException;
425:
426: /**
427: * Retrieves the persistent objects matching the given query. The resulting collection will
428: * be of the supplied collection type. Note that if the Query has no criteria ALL persistent
429: * objects of the class targeted by the query will be returned.
430: *
431: * @param collectionClass The collection type which needs to implement
432: * {@link ManageableCollection}
433: * @param query The query
434: * @return The persistent objects matching the query
435: */
436: public ManageableCollection getCollectionByQuery(
437: Class collectionClass, Query query)
438: throws PersistenceBrokerException;
439:
440: /**
441: * Retrieves the persistent objects matching the given query and returns them as an iterator
442: * which may, depending on the configured collection type, be reloading the objects from
443: * the database upon calling {@link Iterator#next()}. Note that if the Query has no criteria
444: * ALL persistent objects of the class targeted by the query will be returned.
445: *
446: * @param query The query
447: * @return The persistent objects matching the query
448: */
449: public Iterator getIteratorByQuery(Query query)
450: throws PersistenceBrokerException;
451:
452: /**
453: * Retrieves the rows (as <code>Object[]</code> instances) matching the given query and
454: * returns them as an iterator which may, depending on the configured collection type, be reloading
455: * the objects from the database upon calling {@link Iterator#next()}.
456: *
457: * @param query The report query
458: * @return The rows matching the query
459: */
460: public Iterator getReportQueryIteratorByQuery(Query query)
461: throws PersistenceBrokerException;
462:
463: /**
464: * Retrieve a persistent object from the underlying datastore by its identity. However, users
465: * are encouraged to use {@link #getObjectByQuery(Query)} instead, as this method is mainly
466: * intended to be used for internal handling of materialization by OID (e.g. in Proxies).
467: *
468: * @param id The persistent object's id
469: * @return The persistent object
470: */
471: public Object getObjectByIdentity(Identity id)
472: throws PersistenceBrokerException;
473:
474: /**
475: * Retrieve the (first) persistent object from the underlying datastore that matches the given
476: * query.
477: *
478: * @param query The query
479: * @return The persistent object
480: */
481: public Object getObjectByQuery(Query query)
482: throws PersistenceBrokerException;
483:
484: /**
485: * Returns an enumeration of objects representing the primary keys for the objects that match
486: * the given query. Mainly useful for EJB Finder Methods.<br/>
487: * <b>Note:</b> This method is not yet aware of extents!
488: *
489: * @param pkClass The class to use for the primary keys
490: * @param query The query
491: * @return The pk enumeration
492: */
493: public Enumeration getPKEnumerationByQuery(Class pkClass,
494: Query query) throws PersistenceBrokerException;
495: }
|