KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cayenne > ObjectContext


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

19
20 package org.apache.cayenne;
21
22 import java.io.Serializable JavaDoc;
23 import java.util.Collection JavaDoc;
24 import java.util.List JavaDoc;
25
26 import org.apache.cayenne.graph.GraphManager;
27 import org.apache.cayenne.map.EntityResolver;
28 import org.apache.cayenne.query.Query;
29
30 /**
31  * A Cayenne object facade to a persistent store. Instances of ObjectContext are used in
32  * the application code to access Cayenne persistence features.
33  *
34  * @since 1.2
35  * @author Andrus Adamchik
36  */

37 public interface ObjectContext extends Serializable JavaDoc {
38
39     /**
40      * Returns EntityResolver that stores all mapping information accessible by this
41      * ObjectContext.
42      */

43     EntityResolver getEntityResolver();
44
45     /**
46      * Returns a collection of objects that are registered with this ObjectContext and
47      * have a state PersistenceState.NEW
48      */

49     Collection JavaDoc newObjects();
50
51     /**
52      * Returns a collection of objects that are registered with this ObjectContext and
53      * have a state PersistenceState.DELETED
54      */

55     Collection JavaDoc deletedObjects();
56
57     /**
58      * Returns a collection of objects that are registered with this ObjectContext and
59      * have a state PersistenceState.MODIFIED
60      */

61     Collection JavaDoc modifiedObjects();
62
63     /**
64      * Returns a collection of MODIFIED, DELETED or NEW objects.
65      */

66     Collection JavaDoc uncommittedObjects();
67
68     /**
69      * Returns an object local to this ObjectContext and matching the ObjectId. If
70      * <code>prototype</code> is not null, local object is refreshed with the prototype
71      * values.
72      * <p>
73      * This method can do both "mapping" (i.e. finding an object with the same id in this
74      * context) and "synchronization" (i.e. updating the state of the found object with
75      * the state of the prototype object).
76      * </p>
77      */

78     Persistent localObject(ObjectId id, Object JavaDoc prototype);
79
80     /**
81      * Creates a new persistent object scheduled to be inserted to the database on next
82      * commit.
83      */

84     Persistent newObject(Class JavaDoc persistentClass);
85
86     /**
87      * Registers a transient object with the context. The difference with
88      * {@link #newObject(Class)} is that a user creates an object herself, before
89      * attaching it to the context, instead of relying on Cayenne to do that.
90      *
91      * @param object new object that needs to be made persistent.
92      * @since 3.0
93      */

94     void registerNewObject(Object JavaDoc object);
95
96     /**
97      * Schedules a persistent object for deletion on next commit.
98      *
99      * @throws DeleteDenyException if a {@link org.apache.cayenne.map.DeleteRule#DENY}
100      * delete rule is applicable for object deletion.
101      */

102     void deleteObject(Object JavaDoc object) throws DeleteDenyException;
103
104     /**
105      * A callback method that child Persistent objects are expected to call before
106      * accessing property values. This callback allows ObjectContext to "inflate"
107      * unresolved objects on demand and also resolve properties that rely on lazy
108      * faulting.
109      *
110      * @since 3.0
111      */

112     void prepareForAccess(Persistent object, String JavaDoc property, boolean lazyFaulting);
113     
114     /**
115      * @deprecated since 3.0 use {@link #prepareForAccess(Persistent, String, boolean)}.
116      */

117     void prepareForAccess(Persistent object, String JavaDoc property);
118
119     /**
120      * A callback method that child Persistent objects are expected to call from inside
121      * the setter after modifying a value of a persistent property, including "simple" and
122      * "arc" properties.
123      */

124     void propertyChanged(
125             Persistent object,
126             String JavaDoc property,
127             Object JavaDoc oldValue,
128             Object JavaDoc newValue);
129
130     /**
131      * Flushes all changes to objects in this context to the parent DataChannel, cascading
132      * flush operation all the way through the stack, ultimately saving data in the
133      * database.
134      */

135     void commitChanges();
136
137     /**
138      * Flushes all changes to objects in this context to the parent DataChannel. Same as
139      * {@link #commitChanges()}, but no cascading flush occurs.
140      */

141     void commitChangesToParent();
142
143     /**
144      * Resets all uncommitted changes made to the objects in this ObjectContext, cascading
145      * rollback operation all the way through the stack.
146      */

147     void rollbackChanges();
148
149     /**
150      * Resets all uncommitted changes made to the objects in this ObjectContext. Same as
151      * {@link #rollbackChanges()()}, but rollback is local to this context and no
152      * cascading changes undoing occurs.
153      */

154     void rollbackChangesLocally();
155
156     /**
157      * Executes a selecting query, returning a list of persistent objects or data rows.
158      */

159     List JavaDoc performQuery(Query query);
160
161     /**
162      * Executes any kind of query providing the result in a form of QueryResponse.
163      */

164     QueryResponse performGenericQuery(Query query);
165
166     /**
167      * Returns GraphManager that manages object graph associated with this context.
168      */

169     GraphManager getGraphManager();
170
171     /**
172      * Returns an DataChannel used by this context.
173      */

174     DataChannel getChannel();
175 }
176
Popular Tags