StateInterrogation


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   * An instance that implements this interface is registered with the
31   * {@link JDOImplHelper}.
32   * @version 2.0
33   * @since 2.0
34   */
35  public interface StateInterrogation {
36  
37  
38      /** Tests whether the parameter instance is persistent.
39       *
40       * Instances that represent persistent objects in the data store 
41       * return <code>true</code>. 
42       *
43       *<P>Transient instances and instances of classes 
44       * that do not implement <code>PersistenceCapable</code> return <code>false</code>.
45       *<P>
46       * @see PersistenceManager#makePersistent(Object pc)
47       * @see PersistenceCapable#jdoIsPersistent()
48       * @param pc the <code>PersistenceCapable</code> instance.
49       * @return <code>true</code> if the parameter instance is persistent.
50       */
51      Boolean   isPersistent (Object   pc);
52  
53      /** Tests whether the parameter instance is transactional.
54       *
55       * Instances whose state is associated with the current transaction 
56       * return true. 
57       *
58       *<P>Transient instances and instances of classes 
59       * that do not implement <code>PersistenceCapable</code> return <code>false</code>.
60       * @see PersistenceCapable#jdoIsTransactional()
61       * @param pc the <code>PersistenceCapable</code> instance.
62       * @return <code>true</code> if the parameter instance is transactional.
63       */
64      Boolean   isTransactional (Object   pc);
65      
66      /** Tests whether the parameter instance is dirty.
67       *
68       * Instances that have been modified, deleted, or newly 
69       * made persistent in the current transaction return <code>true</code>.
70       *
71       *<P>Transient instances and instances of classes 
72       * that do not implement <code>PersistenceCapable</code> return <code>false</code>.
73       *<P>
74       * @see StateManager#makeDirty(PersistenceCapable pc, String fieldName)
75       * @see PersistenceCapable#jdoIsDirty()
76       * @param pc the <code>PersistenceCapable</code> instance.
77       * @return <code>true</code> if the parameter instance has been modified in the current transaction.
78       */
79      Boolean   isDirty (Object   pc);
80  
81      /** Tests whether the parameter instance has been newly made persistent.
82       *
83       * Instances that have been made persistent in the current transaction 
84       * return <code>true</code>.
85       *
86       *<P>Transient instances and instances of classes 
87       * that do not implement <code>PersistenceCapable</code> return <code>false</code>.
88       *<P>
89       * @see PersistenceManager#makePersistent(Object pc)
90       * @see PersistenceCapable#jdoIsNew()
91       * @param pc the <code>PersistenceCapable</code> instance.
92       * @return <code>true</code> if the parameter instance was made persistent
93       * in the current transaction.
94       */
95      Boolean   isNew (Object   pc);
96  
97      /** Tests whether the parameter instance has been deleted.
98       *
99       * Instances that have been deleted in the current transaction return <code>true</code>.
100      *
101      *<P>Transient instances and instances of classes 
102      * that do not implement <code>PersistenceCapable</code> return <code>false</code>.
103      *<P>
104      * @see PersistenceManager#deletePersistent(Object pc)
105      * @see PersistenceCapable#jdoIsDeleted()
106      * @param pc the <code>PersistenceCapable</code> instance.
107      * @return <code>true</code> if the parameter instance was deleted
108      * in the current transaction.
109      */
110     Boolean   isDeleted (Object   pc);
111         
112     /** Return the associated <code>PersistenceManager</code> if there is one.
113      * Transactional and persistent instances return the associated
114      * <code>PersistenceManager</code>.  
115      *
116      * <P>Transient non-transactional instances and instances of classes 
117      * that do not implement <code>PersistenceCapable</code> return <code>null</code>.
118      * @see PersistenceCapable#jdoGetPersistenceManager()
119      * @param pc the <code>PersistenceCapable</code> instance.
120      * @return the <code>PersistenceManager</code> associated with the parameter instance.
121      */
122     PersistenceManager getPersistenceManager (Object   pc);
123     
124     /** Return a copy of the JDO identity associated with the parameter instance.
125      *
126      * <P>Persistent instances of <code>PersistenceCapable</code> classes have a JDO identity
127      * managed by the <code>PersistenceManager</code>.  This method returns a copy of the
128      * ObjectId that represents the JDO identity.  
129      * 
130      * <P>Transient instances and instances of classes 
131      * that do not implement <code>PersistenceCapable</code> return <code>null</code>.
132      *
133      * <P>The ObjectId may be serialized
134      * and later restored, and used with a <code>PersistenceManager</code> from the same JDO
135      * implementation to locate a persistent instance with the same data store
136      * identity.
137      *
138      * <P>If the JDO identity is managed by the application, then the ObjectId may
139      * be used with a <code>PersistenceManager</code> from any JDO implementation that supports
140      * the <code>PersistenceCapable</code> class.
141      *
142      * <P>If the JDO identity is not managed by the application or the data store,
143      * then the ObjectId returned is only valid within the current transaction.
144      *<P>
145      * @see PersistenceManager#getObjectId(Object pc)
146      * @see PersistenceCapable#jdoGetObjectId()
147      * @see PersistenceManager#getObjectById(Object oid, boolean validate)
148      * @param pc the PersistenceCapable instance.
149      * @return a copy of the ObjectId of the parameter instance as of the beginning of the transaction.
150      */
151     Object   getObjectId (Object   pc);
152 
153     /** Return a copy of the JDO identity associated with the parameter instance.
154      *
155      * @see PersistenceCapable#jdoGetTransactionalObjectId()
156      * @see PersistenceManager#getObjectById(Object oid, boolean validate)
157      * @param pc the <code>PersistenceCapable</code> instance.
158      * @return a copy of the ObjectId of the parameter instance as modified in this transaction.
159      */
160     Object   getTransactionalObjectId (Object   pc);
161     
162     /** Explicitly mark the parameter instance and field dirty.
163      * Normally, <code>PersistenceCapable</code> classes are able to detect changes made
164      * to their fields.  However, if a reference to an array is given to a
165      * method outside the class, and the array is modified, then the
166      * persistent instance is not aware of the change.  This API allows the
167      * application to notify the instance that a change was made to a field.
168      *
169      * <P>Transient instances and instances of classes 
170      * that do not implement <code>PersistenceCapable</code> ignore this method.
171      * @see PersistenceCapable#jdoMakeDirty(String fieldName)
172      * @param pc the <code>PersistenceCapable</code> instance.
173      * @param fieldName the name of the field to be marked dirty.
174      */
175     boolean makeDirty (Object   pc, String   fieldName);
176 
177 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags