KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > jdo > api > persistence > support > 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 JavaDoc 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 JavaDoc 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
Popular Tags