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