KickJava   Java API By Example, From Geeks To Geeks.

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


1 /* ====================================================================
2  *
3  * The ObjectStyle Group Software License, version 1.1
4  * ObjectStyle Group - http://objectstyle.org/
5  *
6  * Copyright (c) 2002-2005, Andrei (Andrus) Adamchik and individual authors
7  * of the software. All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * 1. Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  *
16  * 2. Redistributions in binary form must reproduce the above copyright
17  * notice, this list of conditions and the following disclaimer in
18  * the documentation and/or other materials provided with the
19  * distribution.
20  *
21  * 3. The end-user documentation included with the redistribution, if any,
22  * must include the following acknowlegement:
23  * "This product includes software developed by independent contributors
24  * and hosted on ObjectStyle Group web site (http://objectstyle.org/)."
25  * Alternately, this acknowlegement may appear in the software itself,
26  * if and wherever such third-party acknowlegements normally appear.
27  *
28  * 4. The names "ObjectStyle Group" and "Cayenne" must not be used to endorse
29  * or promote products derived from this software without prior written
30  * permission. For written permission, email
31  * "andrus at objectstyle dot org".
32  *
33  * 5. Products derived from this software may not be called "ObjectStyle"
34  * or "Cayenne", nor may "ObjectStyle" or "Cayenne" appear in their
35  * names without prior written permission.
36  *
37  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40  * DISCLAIMED. IN NO EVENT SHALL THE OBJECTSTYLE GROUP OR
41  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48  * SUCH DAMAGE.
49  * ====================================================================
50  *
51  * This software consists of voluntary contributions made by many
52  * individuals and hosted on ObjectStyle Group web site. For more
53  * information on the ObjectStyle Group, please see
54  * <http://objectstyle.org/>.
55  */
56 package org.objectstyle.cayenne;
57
58 import java.io.Serializable JavaDoc;
59 import java.util.Collection JavaDoc;
60 import java.util.List JavaDoc;
61
62 import org.objectstyle.cayenne.graph.GraphDiff;
63 import org.objectstyle.cayenne.query.QueryExecutionPlan;
64
65 /**
66  * A Cayenne object facade to a persistent store. Instances of ObjectContext are used in
67  * the application code to access Cayenne persistence features.
68  *
69  * @since 1.2
70  * @author Andrus Adamchik
71  */
72 public interface ObjectContext extends Serializable JavaDoc {
73
74     /**
75      * Returns a collection of objects that are registered with this ObjectContext and
76      * have a state PersistenceState.NEW
77      */
78     Collection JavaDoc newObjects();
79
80     /**
81      * Returns a collection of objects that are registered with this ObjectContext and
82      * have a state PersistenceState.DELETED
83      */
84     Collection JavaDoc deletedObjects();
85
86     /**
87      * Returns a collection of objects that are registered with this ObjectContext and
88      * have a state PersistenceState.MODIFIED
89      */
90     Collection JavaDoc modifiedObjects();
91
92     /**
93      * Returns a collection of MODIFIED, DELETED or NEW objects.
94      */
95     Collection JavaDoc uncommittedObjects();
96
97     /**
98      * Creates a new persistent object scheduled to be inserted on next commit.
99      */
100     Persistent newObject(Class JavaDoc persistentClass);
101
102     /**
103      * Schedules a persistent object for deletion on next commit.
104      */
105     void deleteObject(Persistent object);
106
107     /**
108      * A callback method that is invoked whenver a persistent object property is about to
109      * be read. Allows ObjectContext to resolve faults on demand.
110      */
111     void objectWillRead(Persistent object, String JavaDoc property);
112
113     /**
114      * A callback method that is invoked whenver a persistent object property is about to
115      * be changed. Allows ObjectContext to track object changes.
116      */
117     void objectWillWrite(
118             Persistent object,
119             String JavaDoc property,
120             Object JavaDoc oldValue,
121             Object JavaDoc newValue);
122
123     /**
124      * Commits changes made to this ObjectContext persistent objects. If an ObjectContext
125      * is a part of an ObjectContext hierarchy, this method call triggers commit all the
126      * way to the external data store.
127      *
128      * @return GraphDiff that contains changes made to objects during commit. This
129      * includes things like generated ids, etc.
130      */
131     GraphDiff commit();
132
133     /**
134      * Executes a selecting query, returning a list of persistent objects or data rows.
135      */
136     List JavaDoc performSelectQuery(QueryExecutionPlan queryPlan);
137
138     /**
139      * Executes a non-selecting query returning an array of update counts.
140      */
141     int[] performUpdateQuery(QueryExecutionPlan queryPlan);
142
143     /**
144      * Executes any kind of query providing the result in a form of QueryResponse.
145      */
146     QueryResponse performGenericQuery(QueryExecutionPlan queryPlan);
147 }
Popular Tags