KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > versant > core > storagemanager > StorageManager


1
2 /*
3  * Copyright (c) 1998 - 2005 Versant Corporation
4  * All rights reserved. This program and the accompanying materials
5  * are made available under the terms of the Eclipse Public License v1.0
6  * which accompanies this distribution, and is available at
7  * http://www.eclipse.org/legal/epl-v10.html
8  *
9  * Contributors:
10  * Versant Corporation - initial API and implementation
11  */
12 package com.versant.core.storagemanager;
13
14 import com.versant.core.common.State;
15 import com.versant.core.server.CompiledQuery;
16 import com.versant.core.jdo.QueryDetails;
17 import com.versant.core.jdo.VersantQueryPlan;
18 import com.versant.core.metadata.ClassMetaData;
19 import com.versant.core.metadata.FetchGroup;
20 import com.versant.core.metadata.FieldMetaData;
21 import com.versant.core.common.OID;
22 import com.versant.core.common.OIDArray;
23 import com.versant.core.common.*;
24
25 import java.util.Map JavaDoc;
26
27 /**
28  * This keeps track of server side transaction and other information for a
29  * application level session (e.g. a PersistenceManager for JDO) and provides
30  * persistence services for {@link State} instances.
31  *
32  * These methods are designed to be used from an application API layer
33  * (e.g. JDO PersistenceManager) that may be in a different tier.
34  *
35  * All calls from the application API layer go through this interface. For
36  * example there are methods to return results from queries that could have
37  * been implemented via a separate "server side query result" interface.
38  *
39  * The query related methods need a lot more refactoring but one thing at
40  * a time ...
41  */
42 public interface StorageManager {
43
44     /** Release the datastore connection as quickly as possible. */
45     public static final int CON_POLICY_RELEASE = 1;
46     /** Pin the datastore connection for the duration of the tx. */
47     public static final int CON_POLICY_PIN_FOR_TX = 2;
48     /** Pin the datastore connection indefinitely (even between tx's). */
49     public static final int CON_POLICY_PIN = 3;
50
51     /** Do not lock any objects in datastore tx. */
52     public static final int LOCK_POLICY_NONE = 1;
53     /** Lock only the first object navigated or fetched in datastore tx. */
54     public static final int LOCK_POLICY_FIRST = 2;
55     /** Lock all objects in datastore tx. */
56     public static final int LOCK_POLICY_ALL = 3;
57
58     /** Send changes to the datastore and do not commit. */
59     public static final int STORE_OPTION_FLUSH = 1;
60     /** Call prepareForCommit after store. */
61     public static final int STORE_OPTION_PREPARE = 2;
62     /** Call commit after store. */
63     public static final int STORE_OPTION_COMMIT = 3;
64
65     public static final int EVENT_ERRORS = 1;
66     public static final int EVENT_NORMAL = 2;
67     public static final int EVENT_VERBOSE = 3;
68     public static final int EVENT_ALL = 4;
69
70     /**
71      * Begin a tx using the optimistic or datastore transation model.
72      */
73     public void begin(boolean optimistic);
74
75     /**
76      * Commit the tx. Note that non-XA transactions can call {@link #store}
77      * with {@link #STORE_OPTION_COMMIT} to commit instead of having to
78      * also call this method. XA transactions should use the
79      * {@link #STORE_OPTION_PREPARE} and call this method later. Normal
80      * transactions might still call this method if they have no changes or
81      * have already used {@link #STORE_OPTION_FLUSH} to flush changes.
82      */
83     public void commit();
84
85     /**
86      * Rollback a tx.
87      */
88     public void rollback();
89
90     /**
91      * Control pinning of datastore connections. Note that the datastore
92      * may ignore these options.
93      *
94      * @see #CON_POLICY_RELEASE
95      * @see #CON_POLICY_PIN_FOR_TX
96      * @see #CON_POLICY_PIN
97      */
98     public void setConnectionPolicy(int policy);
99
100     /**
101      * Control locking of objects in datastore transactions. Note that the
102      * datastore may ignore this options.
103      *
104      * @see #LOCK_POLICY_NONE
105      * @see #LOCK_POLICY_FIRST
106      * @see #LOCK_POLICY_ALL
107      */
108     public void setLockingPolicy(int policy);
109
110     /**
111      * Get the locking policy.
112      */
113     public int getLockingPolicy();
114
115     /**
116      * Get the State for an OID.
117      *
118      * @param triggerField The field that triggered the fetch or null if
119      */
120     public StatesReturned fetch(ApplicationContext context, OID oid, State current,
121             FetchGroup fetchGroup, FieldMetaData triggerField);
122
123     /**
124      * Get the States for a batch of OIDs. The default fetch group is fetched
125      * for each OID.
126      *
127      * @param triggerField The field that triggered the fetch or null if
128      */
129     public StatesReturned fetch(ApplicationContext context, OIDArray oids,
130             FieldMetaData triggerField);
131
132     /**
133      * Persist a graph of State's (insert, update and delete). For some states
134      * persisting them will change some of their fields (e.g. autoset fields)
135      * and the new values of these fields must be returned if
136      * returnFieldsUpdatedBySM is true.
137      *
138      * @param returnFieldsUpdatedBySM Return States containing any fields
139      * updated by us (i.e. instead of using the value in the incoming
140      * State, if any) in returned.
141      * @param storeOption Option to prepare or commit the tx after the store
142      * operation ({@link #STORE_OPTION_PREPARE},
143      * {@link #STORE_OPTION_COMMIT}, {@link #STORE_OPTION_FLUSH}).
144      * @param evictClasses If this is true then classes with instances
145      * modified in the transaction are evicted instead of the instances
146      */
147     public StatesReturned store(StatesToStore toStore, DeletePacket toDelete,
148             boolean returnFieldsUpdatedBySM, int storeOption,
149             boolean evictClasses);
150
151     /**
152      * Create a real OID for a new instance. This is called prior to commit
153      * when the real OID is required. If it is not possible to create the
154      * OID (e.g. an IDENTITY column in JDBC) then an exception must be
155      * thrown. For these classes a flush must be done instead.
156      */
157     public OID createOID(ClassMetaData cmd);
158
159     /**
160      * Compile a query into a form for the datastore (e.g. generate the SQL
161      * for JDBC).
162      */
163     public CompiledQuery compileQuery(QueryDetails query);
164
165     /**
166      * Execute a query. If compiledQuery is not null then query is ignored
167      * and may be null. If compiledQuery is null then query is used to compile
168      * the query. The compiledQuery is accessable through the returned
169      * ExecuteQueryReturn instance for reuse in future calls.
170      */
171     public ExecuteQueryReturn executeQuery(ApplicationContext context,
172             QueryDetails query, CompiledQuery compiledQuery, Object JavaDoc[] params);
173
174     /**
175      * Prepare and execute the query, returning all results in the supplied
176      * container.
177      */
178     public QueryResultContainer executeQueryAll(ApplicationContext context,
179             QueryDetails query, CompiledQuery compiledQuery, Object JavaDoc[] params);
180
181     /**
182      * Prepare and execute the query and return the number of results
183      * using count(*) or something similar.
184      */
185     public int executeQueryCount(QueryDetails query,
186             CompiledQuery compiledQuery, Object JavaDoc[] params);
187
188     /**
189      * Get the datastore specific query plan for the query (e.g. the SQL
190      * and database plan for JDBC).
191      */
192     public VersantQueryPlan getQueryPlan(QueryDetails query,
193             CompiledQuery compiledQuery, Object JavaDoc[] params);
194
195     /**
196      * Return the next batch of results for the query.
197      */
198     public QueryResultContainer fetchNextQueryResult(ApplicationContext context,
199             RunningQuery runningQuery, int skipAmount);
200
201     /**
202      * This is used by random access queries to return absolute results.
203      */
204     public QueryResultContainer fetchRandomAccessQueryResult(
205             ApplicationContext context, RunningQuery runningQuery, int index,
206             int fetchAmount);
207
208     /**
209      * This is used by random access queries to return the number of results.
210      */
211     public int getRandomAccessQueryCount(ApplicationContext context,
212             RunningQuery runningQuery);
213
214     /**
215      * Close the query.
216      */
217     public void closeQuery(RunningQuery runningQuery);
218
219     /**
220      * Get the underlying datastore connection. If no connection is associated
221      * with this StorageManager then one is allocated and pinned. The returned
222      * object must be a proxy for the real connection that is returned when
223      * its "close" method is called.
224      */
225     public Object JavaDoc getDatastoreConnection();
226
227     /**
228      * Does the datastore require notification before an object becomes dirty
229      * or deleted for the first time in the tx?
230      *
231      * @see #notifyDirty(com.versant.core.common.OID)
232      */
233     public boolean isNotifyDirty();
234
235     /**
236      * The object for the oid is about to become dirty or deleted.
237      *
238      * @see #isNotifyDirty()
239      */
240     public void notifyDirty(OID oid);
241
242     /**
243      * Restore to an initial inactive state.
244      */
245     public void reset();
246
247     /**
248      * Destroy cleaning up all resources. No methods should be invoked on a
249      * destroyed StorageManager but the StorageManager is not required to
250      * enforce this.
251      */
252     public void destroy();
253
254     /**
255      * Log an event to our event log.
256      */
257     public void logEvent(int level, String JavaDoc description, int ms);
258
259     /**
260      * If we are decorating another SM then return it. Otherwise return null.
261      */
262     public StorageManager getInnerStorageManager();
263
264     /**
265      * Are we holding a datastore connection?
266      */
267     public boolean hasDatastoreConnection();
268
269     /**
270      * Get internal status information in the form of property -> value pairs.
271      */
272     public Map JavaDoc getStatus();
273
274     /**
275      * Set a userObject on this SM.
276      */
277     public void setUserObject(Object JavaDoc o);
278 }
279
280
281
Popular Tags