001: /***
002: * jwma Java WebMail
003: * Copyright (c) 2000-2003 jwma team
004: *
005: * jwma is free software; you can distribute and use this source
006: * under the terms of the BSD-style license received along with
007: * the distribution.
008: ***/package dtw.webmail.util;
009:
010: import java.util.*;
011:
012: import org.exolab.castor.jdo.*;
013: import dtw.webmail.model.JwmaException;
014:
015: /**
016: * Abstract class that encapsulates a <tt>Database</tt>
017: * from the Castor lib, to enhance performance by adding
018: * the reuse of queries (which is perfectly possible).
019: *
020: * @author Dieter Wimberger
021: * @version 0.9.7 07/02/2003
022: */
023: public abstract class CastorDatabase {
024:
025: protected Database m_Database;
026: protected HashMap m_Queries;
027:
028: /**
029: * Simple and empty constructor, to create a lightweight
030: * instance that serves only as factory object for "real"
031: * instances.
032: */
033: public CastorDatabase() {
034: }//constructor
035:
036: /**
037: * Delegates creation of an OQL query with no statement.
038: * {@link OQLQuery#create} must be called before the
039: * query can be executed.
040: *
041: * @return a new nonprepared OQL query.
042: */
043: public OQLQuery getOQLQuery() {
044: return m_Database.getOQLQuery();
045: }//OQLQuery
046:
047: /**
048: * Delegates creation of an OQL query from the
049: * supplied statement.
050: *
051: * @param query An OQL query statement
052: *
053: * @return An OQL query
054: *
055: * @throws QueryException The query syntax is invalid
056: */
057: public OQLQuery getOQLQuery(String oql) throws QueryException {
058: return m_Database.getOQLQuery(oql);
059: }//getOQLQuery
060:
061: /**
062: * Delegates loading of an object of the specified type and
063: * given identity to the encapsulated <tt>Database</tt>.
064: *
065: *
066: * @param type The object's type
067: * @param identity The object's identity
068: *
069: * @throws ObjectNotFoundException No object of the given type and
070: * identity was found in persistent storage.
071: * @throws LockNotGrantedException Timeout or deadlock occured
072: * attempting to acquire a lock on the object.
073: * @throws TransactionNotInProgressException Method called while
074: * transaction is not in progress.
075: * @throws PersistenceException An error reported by the
076: * persistence engine.
077: */
078: public Object load(Class type, Object identity)
079: throws TransactionNotInProgressException,
080: ObjectNotFoundException, LockNotGrantedException,
081: PersistenceException {
082:
083: return m_Database.load(type, identity);
084: }//load
085:
086: /**
087: * Delegates creation of a new object in persistent storage to the
088: * encapsulated <tt>Database</tt>. The object will only be persisted
089: * if the transaction commits.
090: *
091: * @param object The object to create
092: *
093: * @throws TransactionNotInProgressException Method called while
094: * transaction is not in progress.
095: * @throws DuplicateIdentityException An object with this identity
096: * already exists in persistent storage
097: * @throws ClassNotPersistenceCapableException The class is not
098: * persistent capable.
099: * @throws PersistenceException An error reported by the
100: * persistence engine.
101: */
102: public void create(Object object)
103: throws ClassNotPersistenceCapableException,
104: DuplicateIdentityException,
105: TransactionNotInProgressException, PersistenceException {
106: m_Database.create(object);
107: }//create
108:
109: /**
110: * Delegates removal of the object from persistent storage.
111: * The deletion will take effect only if the transaction is committed,
112: * but the object is no longer visible to queries in the current
113: * transaction and locks for access from other transactions will
114: * block until this transaction completes.
115: *
116: * @param object The object to remove
117: *
118: * @throws TransactionNotInProgressException Method called while
119: * transaction is not in progress.
120: * @throws ObjectNotPersistentException The object has not been
121: * queried or created in this transaction.
122: * @throws LockNotGrantedException Timeout or deadlock occured
123: * attempting to acquire a lock on the object.
124: * @throws PersistenceException An error reported by the
125: * persistence engine.
126: */
127: public void remove(Object object)
128: throws ObjectNotPersistentException,
129: LockNotGrantedException, TransactionNotInProgressException,
130: PersistenceException {
131: m_Database.remove(object);
132: }//remove
133:
134: /**
135: * Delegates updating a data object which is queried/loaded/created
136: * in <b>another transaction</b> to the encapsulated <tt>Database</tt>.
137: * This method is used only for long transaction support.
138: * Calling this method for data object queried/loaded/created
139: * in the same transaction results in Exception.
140: *
141: * @param object The object to create
142: *
143: * @throws TransactionNotInProgressException Method called while
144: * transaction is not in progress.
145: * @throws ClassNotPersistenceCapableException The class is not
146: * persistent capable.
147: * @throws PersistenceException An error reported by the
148: * persistence engine.
149: */
150: public void update(Object object)
151: throws ClassNotPersistenceCapableException,
152: TransactionNotInProgressException, PersistenceException {
153: m_Database.update(object);
154: }//update
155:
156: /**
157: * Delegates testing of the current transaction autoStore flag state
158: * to the encapsulated <tt>Database</tt>.
159: *
160: * @return true if autostoring is on, false otherwise.
161: */
162: public boolean isAutoStore() {
163: return m_Database.isAutoStore();
164: }//isAutoStore
165:
166: /**
167: * Delegates setting of the autoStore flag state
168: * to the encapsulated <tt>Database</tt>.
169: *
170: * @param autoStore true if on, false otherwise.
171: */
172: public void setAutoStore(boolean autoStore) {
173: m_Database.setAutoStore(autoStore);
174: }//setAutoStore
175:
176: /**
177: * Delegates beginning a new transaction to the encapsulated
178: * <tt>Database</tt>. A transaction must be open in order
179: * to query and persist objects.
180: *
181: * @throws PersistenceException A transaction is already open on
182: * this database, or an error reported by the persistence engine
183: */
184: public void begin() throws PersistenceException {
185: m_Database.begin();
186: }//begin
187:
188: /**
189: * Delegates the rollback method to the encapsulated
190: * <tt>Database</tt> instance.
191: */
192: public void rollback() throws TransactionNotInProgressException {
193:
194: m_Database.rollback();
195: }//rollback
196:
197: /**
198: * Delegates the commit method to the encapsulated
199: * <tt>Database</tt> instance.
200: *
201: * @throws TransactionNotInProgressException Method called while
202: * transaction is not in progress.
203: * @throws TransactionAbortedException The transaction cannot
204: * commit and has been rolled back.
205: */
206: public void commit() throws TransactionNotInProgressException,
207: TransactionAbortedException {
208:
209: m_Database.commit();
210: }//commit
211:
212: /**
213: * Tests if a transaction is currently active.
214: *
215: * @return true if a transaction is active, false otherwise.
216: */
217: public boolean isActive() {
218: return m_Database.isActive();
219: }//isActive
220:
221: /**
222: * Tests if a database has been closed.
223: *
224: * @return true if the database has been closed, false otherwise.
225: */
226: public boolean isClosed() {
227: return m_Database.isClosed();
228: }//isClosed
229:
230: /**
231: * Closes the database. If a client transaction is in progress the
232: * transaction will be rolled back and an exception thrown.
233: * If an app-server transaction is in progress, the transaction
234: * will commit/rollback when triggered by the application server.
235: *
236: * @throws PersistenceException An error occured while
237: * attempting to close the database
238: */
239: public void close() throws PersistenceException {
240: m_Database.close();
241: }//close
242:
243: /**
244: * Delegates testing of a given object's persistency state.
245: * An object is persistent if it was created or queried
246: * in this transaction. If the object was created or queried
247: * in another transaction, or there is no open transaction,
248: * this method returns null(??).
249: *
250: * @param object the object to be tested.
251: *
252: * @return True if persistent in this transaction
253: */
254: public boolean isPersistent(Object object) {
255: return m_Database.isPersistent(object);
256: }//isPersistent
257:
258: /**
259: * Delegates checking an object's identity to the encapsulated
260: * <tt>Database</tt>.
261: *
262: * @param object the object to be checked.
263: *
264: * @return the object's identity, or null if nonexistant.
265: */
266: public Object getIdentity(Object object) {
267: return m_Database.getIdentity(object);
268: }//getIdentity
269:
270: /**
271: * Returns the encapsulated <tt>Database</tt> instance.
272: *
273: * @return the encapsulated database instance.
274: */
275: public Database getDatabase() {
276: return m_Database;
277: }//getDatabase
278:
279: public OQLQuery getQuery(String identifier) {
280: return (OQLQuery) m_Queries.get(identifier);
281: }//getQuery
282:
283: public void putQuery(String identifier, OQLQuery query) {
284: m_Queries.put(identifier, query);
285: }//putQuery
286:
287: public abstract CastorDatabase createCastorDatabase()
288: throws JwmaException;
289:
290: }//CastorDatabase
|