1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 package javax.jdo.spi;
23
24 import javax.jdo.PersistenceManager;
25
26 /***
27 * This interface is implemented by a non-binary-compatible JDO implementation
28 * to provide state interrogation for non-enhanced persistent classes.
29 *
30 * <P>A call to JDOHelper to get the status of an instance is handled
31 * internally if the parameter instance implements PersistenceCapable.
32 * For non-binary-compatible implementations, there is no requirement
33 * that persistent instances implement PersistenceCapable. Therefore,
34 * if the parameter does not implement PersistenceCapable, JDOHelper
35 * delegates to all registered instances of StateInterrogation until
36 * an instance can handle the request.
37 * <P>For JDOHelper isXXX methods, which return boolean, the
38 * corresponding method in StateInterrogation returns Boolean. If the
39 * return value is <code>null</code> then the StateInterrogation does
40 * not recognize the parameter as being handled by it. A non-null return
41 * value indicates that the implementation has determined the answer.
42 * <P>For JDOHelper getXXX methods, which return an Object, each
43 * registered StateInterrogation is given the parameter until one of
44 * them returns a non-null value, which is passed to the caller.
45 * <P>For JDOHelper makeDirty, each
46 * registered StateInterrogation is given the parameter until one of
47 * them returns true, indicating that it has handled the call.
48 * An instance that implements this interface must be registered with the
49 * {@link JDOImplHelper}.
50 * @version 2.0
51 * @since 2.0
52 */
53 public interface StateInterrogation {
54
55
56 /*** Tests whether the parameter instance is persistent.
57 *
58 * Instances that represent persistent objects in the data store
59 * return <code>Boolean.TRUE</code>.
60 *
61 * <P>Instances known by the implementation to be non-persistent
62 * return <code>Boolean.FALSE</code>.
63 *
64 * <P>Instances not recognized by the implementation return
65 * <code>null</code>.
66 *
67 * @see PersistenceManager#makePersistent(Object pc)
68 * @see PersistenceCapable#jdoIsPersistent()
69 * @param pc the instance.
70 * @return <code>Boolean.TRUE</code> if the parameter instance is persistent.
71 */
72 Boolean isPersistent (Object pc);
73
74 /*** Tests whether the parameter instance is transactional.
75 *
76 * Instances whose state is associated with the current transaction
77 * return <code>Boolean.TRUE</code>.
78 *
79 * <P>Instances known by the implementation to be non-transactional
80 * return <code>Boolean.FALSE</code>.
81 *
82 * <P>Instances not recognized by the implementation return
83 * <code>null</code>.
84 *
85 * @see PersistenceCapable#jdoIsTransactional()
86 * @param pc the instance.
87 * @return <code>Boolean.TRUE</code> if the parameter instance is transactional.
88 */
89 Boolean isTransactional (Object pc);
90
91 /*** Tests whether the parameter instance is dirty.
92 *
93 * Instances that have been modified, deleted, newly
94 * made persistent in the current transaction,
95 * or modified while detached return <code>Boolean.TRUE</code>.
96 *
97 * <P>Instances known by the implementation to be non-dirty
98 * return <code>Boolean.FALSE</code>.
99 *
100 * <P>Instances not recognized by the implementation return
101 * <code>null</code>.
102 *
103 * @see StateManager#makeDirty(PersistenceCapable pc, String fieldName)
104 * @see PersistenceCapable#jdoIsDirty()
105 * @param pc the instance.
106 * @return <code>Boolean.TRUE</code> if the parameter instance has been modified
107 * in the current transaction, or while detached.
108 */
109 Boolean isDirty (Object pc);
110
111 /*** Tests whether the parameter instance has been newly made persistent.
112 *
113 * Instances that have been made persistent in the current transaction
114 * return <code>Boolean.TRUE</code>.
115 *
116 * <P>Instances known by the implementation to be non-new
117 * return <code>Boolean.FALSE</code>.
118 *
119 * <P>Instances not recognized by the implementation return
120 * <code>null</code>.
121 *
122 * @see PersistenceManager#makePersistent(Object pc)
123 * @see PersistenceCapable#jdoIsNew()
124 * @param pc the instance.
125 * @return <code>Boolean.TRUE</code> if the parameter instance was made persistent
126 * in the current transaction.
127 */
128 Boolean isNew (Object pc);
129
130 /*** Tests whether the parameter instance has been deleted.
131 *
132 * Instances that have been deleted in the current transaction
133 * return <code>Boolean.TRUE</code>.
134 *
135 * <P>Instances known by the implementation to be non-deleted
136 * return <code>Boolean.FALSE</code>.
137 *
138 * <P>Instances not recognized by the implementation return
139 * <code>null</code>.
140 *
141 * @see PersistenceManager#deletePersistent(Object pc)
142 * @see PersistenceCapable#jdoIsDeleted()
143 * @param pc the instance.
144 * @return <code>Boolean.TRUE</code> if the parameter instance was deleted
145 * in the current transaction.
146 */
147 Boolean isDeleted (Object pc);
148
149 /*** Tests whether the parameter instance is detached.
150 *
151 * Instances that are detached return <code>Boolean.TRUE</code>.
152 *
153 * <P>Instances known by the implementation to be non-detached
154 * return <code>Boolean.FALSE</code>.
155 *
156 * <P>Instances not recognized by the implementation return
157 * <code>null</code>.
158 *
159 * @see PersistenceManager#detachCopy(Object pc)
160 * @see PersistenceCapable#jdoIsDeleted()
161 * @param pc the instance.
162 * @return <code>Boolean.TRUE</code> if the parameter instance is detached.
163 */
164 Boolean isDetached (Object pc);
165
166 /*** Return the associated <code>PersistenceManager</code> if there is one.
167 * Transactional and persistent instances return the associated
168 * <code>PersistenceManager</code>.
169 *
170 * <P>Transient non-transactional instances return <code>null</code>.
171 * <P>Instances unknown by the implementation return <code>null</code>.
172 * @see PersistenceCapable#jdoGetPersistenceManager()
173 * @param pc the instance.
174 * @return the <code>PersistenceManager</code> associated with the
175 * parameter instance.
176 */
177 PersistenceManager getPersistenceManager (Object pc);
178
179 /*** Return a copy of the JDO identity associated with the parameter
180 * instance.
181 *
182 * <P>Persistent instances of <code>PersistenceCapable</code> classes
183 * have a JDO identity
184 * managed by the <code>PersistenceManager</code>. This method returns
185 * a copy of the
186 * ObjectId that represents the JDO identity.
187 *
188 * <P>Instances unknown by the implementation return <code>null</code>.
189 * <P>The ObjectId may be serialized
190 * and later restored, and used with a <code>PersistenceManager</code>
191 * from the same JDO
192 * implementation to locate a persistent instance with the same data store
193 * identity.
194 *
195 * <P>If the JDO identity is managed by the application, then the ObjectId
196 * may be used with a <code>PersistenceManager</code> from any JDO
197 * implementation that supports
198 * the <code>PersistenceCapable</code> class.
199 *
200 * <P>If the JDO identity is not managed by the application or the data
201 * store, then the ObjectId returned is only valid within the current
202 * transaction.
203 *<P>
204 * @see PersistenceManager#getObjectId(Object pc)
205 * @see PersistenceCapable#jdoGetObjectId()
206 * @see PersistenceManager#getObjectById(Object oid, boolean validate)
207 * @param pc the instance.
208 * @return a copy of the ObjectId of the parameter instance as of the
209 * beginning of the transaction.
210 */
211 Object getObjectId (Object pc);
212
213 /*** Return a copy of the JDO identity associated with the parameter
214 * instance.
215 *
216 * <P>Instances unknown by the implementation return <code>null</code>.
217 * @see PersistenceCapable#jdoGetTransactionalObjectId()
218 * @see PersistenceManager#getObjectById(Object oid, boolean validate)
219 * @param pc the instance.
220 * @return a copy of the ObjectId of the parameter instance as modified
221 * in this transaction.
222 */
223 Object getTransactionalObjectId (Object pc);
224
225 /*** Return the version of the parameter instance.
226 *
227 * <P>Instances unknown by the implementation return <code>null</code>.
228 * @see PersistenceCapable#jdoGetVersion()
229 * @param pc the instance.
230 * @return a copy of the ObjectId of the parameter instance as modified
231 * in this transaction.
232 */
233 Object getVersion (Object pc);
234
235 /*** Explicitly mark the parameter instance and field dirty.
236 * Normally, <code>PersistenceCapable</code> classes are able to detect
237 * changes made
238 * to their fields. However, if a reference to an array is given to a
239 * method outside the class, and the array is modified, then the
240 * persistent instance is not aware of the change. This API allows the
241 * application to notify the instance that a change was made to a field.
242 *
243 * <P>Instances unknown by the implementation are unaffected.
244 * @see PersistenceCapable#jdoMakeDirty(String fieldName)
245 * @param pc the instance.
246 * @param fieldName the name of the field to be marked dirty.
247 */
248 boolean makeDirty (Object pc, String fieldName);
249
250 }