PersistenceManager


1   /*
2    * Copyright 2004 (C) TJDO.
3    * All rights reserved.
4    *
5    * This software is distributed under the terms of the TJDO License version 1.0.
6    * See the terms of the TJDO License in the documentation provided with this software.
7    *
8    * $Id: PersistenceManager.java,v 1.6 2004/01/18 03:01:05 jackknifebarber Exp $
9    */
10  
11  package com.triactive.jdo;
12  
13  import com.triactive.jdo.StateManager;
14  import com.triactive.jdo.store.StoreManager;
15  import java.io.PrintWriter  ;
16  import java.sql.Connection  ;
17  import java.sql.SQLException  ;
18  
19  
20  /**
21   * An extension to the standard persistence manager interface including methods
22   * specific to TriActive JDO.
23   * <p>
24   * Applications should <em>not</em> use these methods.
25   *
26   * @author <a HREF="mailto:mmartin5@austin.rr.com">Mike Martin</a>
27   * @version $Revision: 1.6 $
28   */
29  
30  public interface PersistenceManager extends javax.jdo.PersistenceManager
31  {
32      /**
33       * Returns the store manager used for storage by this persistence manager.
34       */
35      StoreManager getStoreManager();
36  
37      /**
38       * Obtains a JDBC connection to the data store.
39       * If a JDO transaction is active, this is the connection on which the
40       * corresponding JDBC transaction is active.
41       * Otherwise a new connection is obtained from the underlying data source.
42       * <p>
43       *
44       * @param forWriting
45       *      <code>true</code> if the connection will be used for updates.
46       *
47       * @return
48       *      A JDBC connection.
49       */
50      Connection   getConnection(boolean forWriting) throws SQLException  ;
51  
52      /**
53       * Release a previously-obtained data store connection.
54       * Must be called once for every connection obtained with
55       * {@link #getConnection} (use try/finally).
56       */
57      void releaseConnection(Connection   conn) throws SQLException  ;
58  
59      /**
60       * Called by state managers to enlist in the transaction cache.
61       */
62      void enlistInTransaction(StateManager sm);
63  
64      /**
65       * Called by state managers to evict themselves from the transaction cache.
66       */
67      void evictFromTransaction(StateManager sm);
68  
69      /**
70       * Called by state managers when disconnecting from the managed object.
71       * Also evicts from the transaction cache.
72       */
73      void removeStateManager(StateManager sm);
74  
75      /**
76       * Locates a persistent instance in the cache of instances managed by this
77       * PersistenceManager.
78       * This is a variation of getObjectById(Object, boolean) that allows a
79       * context class to be specified for class loading purposes.
80       *
81       * @param id
82       *      An object ID.
83       * @param contextClass
84       *      A class to use as a class-loading context, if necessary, or
85       *      <code>null</code> to use just the default class loader(s).
86       * @param validate
87       *      <code>true</code> if the existence of the instance is to be
88       *      validated.
89       *
90       * @return
91       *      The PersistenceCapable instance having the specified object ID.
92       */
93      Object   getObjectById(Object   id, Class   contextClass, boolean validate);
94  
95      /**
96       * Locates a persistent instance in the cache of instances managed by this
97       * PersistenceManager.
98       * This is a variation of {@link #getObjectById(Object,Class,boolean)} that
99       * allows specific initial field values to be offered to the state manager.
100      * Classes in the store package use this method to proactively offer field
101      * values in cases where they are readily available.
102      * If the instance is in a state that can benefit from newly available field
103      * values, the fields are replaced in the instance and a state change occurs
104      * as though the instance itself had read a field.
105      *
106      * @param id
107      *      An object ID.
108      * @param contextClass
109      *      A class to use as a class-loading context, if necessary, or
110      *      <code>null</code> to use just the default class loader(s).
111      * @param fieldNumbers
112      *      The field numbers being offered.
113      * @param fieldManager
114      *      A field manager from which to get the offered fields.
115      *
116      * @return
117      *      The PersistenceCapable instance having the specified object ID.
118      */
119     Object   getObjectById(Object   id, Class   contextClass, 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 }
179
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags