001: /*
002: * Copyright 2004 (C) TJDO.
003: * All rights reserved.
004: *
005: * This software is distributed under the terms of the TJDO License version 1.0.
006: * See the terms of the TJDO License in the documentation provided with this software.
007: *
008: * $Id: PersistenceManager.java,v 1.6 2004/01/18 03:01:05 jackknifebarber Exp $
009: */
010:
011: package com.triactive.jdo;
012:
013: import com.triactive.jdo.StateManager;
014: import com.triactive.jdo.store.StoreManager;
015: import java.io.PrintWriter;
016: import java.sql.Connection;
017: import java.sql.SQLException;
018:
019: /**
020: * An extension to the standard persistence manager interface including methods
021: * specific to TriActive JDO.
022: * <p>
023: * Applications should <em>not</em> use these methods.
024: *
025: * @author <a href="mailto:mmartin5@austin.rr.com">Mike Martin</a>
026: * @version $Revision: 1.6 $
027: */
028:
029: public interface PersistenceManager extends
030: javax.jdo.PersistenceManager {
031: /**
032: * Returns the store manager used for storage by this persistence manager.
033: */
034: StoreManager getStoreManager();
035:
036: /**
037: * Obtains a JDBC connection to the data store.
038: * If a JDO transaction is active, this is the connection on which the
039: * corresponding JDBC transaction is active.
040: * Otherwise a new connection is obtained from the underlying data source.
041: * <p>
042: *
043: * @param forWriting
044: * <code>true</code> if the connection will be used for updates.
045: *
046: * @return
047: * A JDBC connection.
048: */
049: Connection getConnection(boolean forWriting) throws SQLException;
050:
051: /**
052: * Release a previously-obtained data store connection.
053: * Must be called once for every connection obtained with
054: * {@link #getConnection} (use try/finally).
055: */
056: void releaseConnection(Connection conn) throws SQLException;
057:
058: /**
059: * Called by state managers to enlist in the transaction cache.
060: */
061: void enlistInTransaction(StateManager sm);
062:
063: /**
064: * Called by state managers to evict themselves from the transaction cache.
065: */
066: void evictFromTransaction(StateManager sm);
067:
068: /**
069: * Called by state managers when disconnecting from the managed object.
070: * Also evicts from the transaction cache.
071: */
072: void removeStateManager(StateManager sm);
073:
074: /**
075: * Locates a persistent instance in the cache of instances managed by this
076: * PersistenceManager.
077: * This is a variation of getObjectById(Object, boolean) that allows a
078: * context class to be specified for class loading purposes.
079: *
080: * @param id
081: * An object ID.
082: * @param contextClass
083: * A class to use as a class-loading context, if necessary, or
084: * <code>null</code> to use just the default class loader(s).
085: * @param validate
086: * <code>true</code> if the existence of the instance is to be
087: * validated.
088: *
089: * @return
090: * The PersistenceCapable instance having the specified object ID.
091: */
092: Object getObjectById(Object id, Class contextClass, boolean validate);
093:
094: /**
095: * Locates a persistent instance in the cache of instances managed by this
096: * PersistenceManager.
097: * This is a variation of {@link #getObjectById(Object,Class,boolean)} that
098: * allows specific initial field values to be offered to the state manager.
099: * Classes in the store package use this method to proactively offer field
100: * values in cases where they are readily available.
101: * If the instance is in a state that can benefit from newly available field
102: * values, the fields are replaced in the instance and a state change occurs
103: * as though the instance itself had read a field.
104: *
105: * @param id
106: * An object ID.
107: * @param contextClass
108: * A class to use as a class-loading context, if necessary, or
109: * <code>null</code> to use just the default class loader(s).
110: * @param fieldNumbers
111: * The field numbers being offered.
112: * @param fieldManager
113: * A field manager from which to get the offered fields.
114: *
115: * @return
116: * The PersistenceCapable instance having the specified object ID.
117: */
118: Object getObjectById(Object id, Class contextClass,
119: int[] fieldNumbers, FieldManager fieldManager);
120:
121: /**
122: * Finds the StateManager for a given object.
123: *
124: * @return
125: * The object's state manager, or <code>null</code> if obj is null or
126: * has no state manager.
127: *
128: * @exception JDOUserException
129: * If <var>obj</var> is not PersistenceCapable or is managed by a
130: * different PersistenceManager.
131: */
132: StateManager findStateManager(Object obj);
133:
134: /**
135: * Called by state managers when their getPersistenceManager() method is
136: * called.
137: * This is used by {@link #findStateManager} to quickly locate an object's
138: * state manager.
139: */
140: void hereIsStateManager(StateManager sm, Object obj);
141:
142: /**
143: * Marks the specified state manager as dirty.
144: * <p>
145: * In this case, "dirty" means having one or more fields modified that have
146: * not been updated in storage via the StoreManager.
147: * The persistence manager allows at most one state manager at a time to be
148: * considered dirty.
149: * The sole purpose of this delayed update is to coalesce multiple field
150: * changes on the same object into one SQL UPDATE.
151: */
152: void markDirty(StateManager sm);
153:
154: /**
155: * Causes any dirty state manager to be updated in storage.
156: */
157: void flushDirty();
158:
159: /**
160: * Called by state managers to indicate they have made a modification to the
161: * data store.
162: */
163: void dataStoreModified();
164:
165: /**
166: * Returns the number of data store modifications made under this
167: * persistence manager.
168: * Can be used as a version stamp on the data store.
169: * Note that it only reflects modifications made to objects from this
170: * persistence manager.
171: */
172: int dataStoreModifyCount();
173:
174: /**
175: * Prints debugging info on an object to the specified output.
176: */
177: void dump(Object obj, PrintWriter out);
178: }
|