PersistenceCapable


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  /*
25   * PersistenceCapable.java
26   *
27   * Created on February 25, 2000
28   */
29   
30  package com.sun.jdo.api.persistence.support;
31  
32  /**
33   *
34   * @author Craig Russell
35   * @version 0.1
36   */
37  
38  /**
39   * A class that can be managed by a JDO implementation.
40   *
41   * <P>Every class whose instances can be managed by a JDO PersistenceManager must 
42   * implement the PersistenceCapable interface.
43   *
44   * <P>This interface defines methods that allow the implementation to manage
45   * the instances.  It also defines methods that allow a JDO aware
46   * application to examine the runtime state of instances.  For example,
47   * an application can discover whether the instance is persistent, transactional,
48   * dirty, new, or deleted; and to get its associated
49   * PersistenceManager if it has one.
50   *
51   * <P>In the Reference Implementation, the JDO Enhancer modifies the class
52   * to implement PersistenceCapable prior to loading the class into the runtime
53   * environment.  The Reference Enhancer also adds code to implement the
54   * methods defined by PersistenceCapable.
55   *
56   * <P>The PersistenceCapable interface is designed to avoid name conflicts
57   * in the scope of user-defined classes.  All of its declared method
58   * names are prefixed with 'jdo'.
59   */
60  public interface PersistenceCapable
61  {
62      /** Return the associated PersistenceManager if there is one.
63     * Transactional and persistent instances return the associated
64     * PersistenceManager.  
65     *
66     * <P>Transient non-transactional instances return null.
67       *<P>
68     * @return the PersistenceManager associated with this instance.
69     */
70      PersistenceManager jdoGetPersistenceManager();
71      
72      /** Explicitly mark this instance and this field dirty.
73       * Normally, PersistenceCapable classes are able to detect changes made
74       * to their fields.  However, if a reference to an Array is given to a
75       * method outside the class, and the Array is modified, then the
76       * persistent instance is not aware of the change.  This API allows the
77       * application to notify the instance that a change was made to a field.
78       *
79       * <P>Transient instances ignore this method.
80       *<P>
81       * @param fieldName the name of the field to be marked dirty.
82       */
83      void jdoMakeDirty(String   fieldName);
84      
85      /** Return a copy of the JDO identity associated with this instance.
86       *
87       * <P>Persistent instances of PersistenceCapable classes have a JDO identity
88       * managed by the PersistenceManager.  This method returns a copy of the
89       * ObjectId that represents the JDO identity.  
90       * 
91       * <P>Transient instances return null.
92       *
93       * <P>The ObjectId may be serialized
94       * and later restored, and used with a PersistenceManager from the same JDO
95       * implementation to locate a persistent instance with the same data store
96       * identity.
97       *
98       * <P>If the JDO identity is managed by the application, then the ObjectId may
99       * be used with a PersistenceManager from any JDO implementation that supports
100      * the PersistenceCapable class.
101      *
102      * <P>If the JDO identity is not managed by the application or the data store,
103      * then the ObjectId returned is only valid within the current transaction.
104      *<P>
105      * @see PersistenceManager#getObjectId(Object pc)
106      * @see PersistenceManager#getObjectById(Object oid)
107      * @return a copy of the ObjectId of this instance.
108      */
109     Object   jdoGetObjectId();
110     
111     /** Tests whether this object is dirty.
112      *
113      * Instances that have been modified, deleted, or newly 
114      * made persistent in the current transaction return true.
115      *
116      *<P>Transient instances return false.
117      *<P>
118      * @see #jdoMakeDirty(String fieldName)
119      * @return true if this instance has been modified in the current transaction.
120      */
121     boolean jdoIsDirty();
122 
123     /** Tests whether this object is transactional.
124      *
125      * Instances that respect transaction boundaries return true.  These instances
126      * include transient instances made transactional as a result of being the
127      * target of a makeTransactional method call; newly made persistent or deleted
128      * persistent instances; persistent instances read in data store
129      * transactions; and persistent instances modified in optimistic transactions.
130      *
131      *<P>Transient instances return false.
132      *<P>
133      * @return true if this instance is transactional.
134      */
135     boolean jdoIsTransactional();
136 
137     /** Tests whether this object is persistent.
138      *
139      * Instances whose state is stored in the data store return true.
140      *
141      *<P>Transient instances return false.
142      *<P>
143      * @see PersistenceManager#makePersistent(Object pc)
144      * @return true if this instance is persistent.
145      */
146     boolean jdoIsPersistent();
147 
148     /** Tests whether this object has been newly made persistent.
149      *
150      * Instances that have been made persistent in the current transaction 
151      * return true.
152      *
153      *<P>Transient instances return false.
154      *<P>
155      * @see PersistenceManager#makePersistent(Object pc)
156      * @return true if this instance was made persistent
157      * in the current transaction.
158      */
159     boolean jdoIsNew();
160 
161     /** Tests whether this object has been deleted.
162      *
163      * Instances that have been deleted in the current transaction return true.
164      *
165      *<P>Transient instances return false.
166      *<P>
167      * @see PersistenceManager#deletePersistent(Object pc)
168      * @return true if this instance was deleted
169      * in the current transaction.
170      */
171     boolean jdoIsDeleted();
172     
173     
174 }
175
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags