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  ;
23  import java.util.Collection  ;
24  import java.util.List  ;
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   {
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   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   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   modifiedObjects();
62  
63      /**
64       * Returns a collection of MODIFIED, DELETED or NEW objects.
65       */
66      Collection   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   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   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   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   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   property, boolean lazyFaulting);
113     
114     /**
115      * @deprecated since 3.0 use {@link #prepareForAccess(Persistent, String, boolean)}.
116      */
117     void prepareForAccess(Persistent object, String   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   property,
127             Object   oldValue,
128             Object   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags