View Javadoc

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