View Javadoc

1   /*
2    * Copyright 2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at 
7    * 
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software 
11   * distributed under the License is distributed on an "AS IS" BASIS, 
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
13   * See the License for the specific language governing permissions and 
14   * limitations under the License.
15   */
16  
17  /*
18   * StateInterrogation.java
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 }