KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > oracle > toplink > essentials > sessions > DatabaseSession


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
5  * in compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * glassfish/bootstrap/legal/CDDLv1.0.txt or
9  * https://glassfish.dev.java.net/public/CDDLv1.0.html.
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 in each file and include the License file at
15  * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
16  * add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your
18  * own identifying information: Portions Copyright [yyyy]
19  * [name of copyright owner]
20  */

21 // Copyright (c) 1998, 2005, Oracle. All rights reserved.
22
package oracle.toplink.essentials.sessions;
23
24 import java.util.*;
25 import oracle.toplink.essentials.exceptions.*;
26 import oracle.toplink.essentials.descriptors.ClassDescriptor;
27 import oracle.toplink.essentials.platform.server.ServerPlatform;
28 import oracle.toplink.essentials.sequencing.SequencingControl;
29
30 /**
31  * <p>
32  * <b>Purpose</b>: Add login and configuration API to that of Session.
33  * This interface is to be used during the creation and login of the session only.
34  * The Session interface should be used after login for normal reading/writing.
35  */

36 public interface DatabaseSession extends Session {
37
38     /**
39      * PUBLIC:
40      * Add the descriptor to the session.
41      * All persistent classes must have a descriptor registered for them with the session.
42      * It is best to add the descriptors before login, if added after login the order in which
43      * descriptors are added is dependant on inheritice and references unless the addDescriptors
44      * method is used.
45      *
46      * @see #addDescriptors(Vector)
47      * @see #addDescriptors(Project)
48      */

49     public void addDescriptor(ClassDescriptor descriptor);
50
51     /**
52      * PUBLIC:
53      * Add the descriptors to the session.
54      * All persistent classes must have a descriptor registered for them with the session.
55      * This method allows for a batch of descriptors to be added at once so that TopLink
56      * can resolve the dependancies between the descriptors and perform initialization optimially.
57      */

58     public void addDescriptors(Vector descriptors);
59
60     /**
61      * PUBLIC:
62      * Add the descriptors to the session from the Project.
63      * This can be used to combine the descriptors from multiple projects into a single session.
64      * This can be called after the session has been connected as long as there are no external dependencies.
65      */

66     public void addDescriptors(oracle.toplink.essentials.sessions.Project project);
67
68     /**
69      * PUBLIC:
70      * Begin a transaction on the database.
71      * This allows a group of database modification to be commited or rolledback as a unit.
72      * All writes/deletes will be sent to the database be will not be visible to other users until commit.
73      * Although databases do not allow nested transaction,
74      * TopLink supports nesting through only committing to the database on the outer commit.
75      *
76      * @exception DatabaseException if the database connection is lost or the begin is rejected.
77      *
78      * @see #isInTransaction()
79      */

80     public void beginTransaction() throws DatabaseException;
81
82     /**
83      * PUBLIC:
84      * Commit the active database transaction.
85      * This allows a group of database modification to be commited or rolledback as a unit.
86      * All writes/deletes will be sent to the database be will not be visible to other users until commit.
87      * Although databases do not allow nested transaction,
88      * TopLink supports nesting through only committing to the database on the outer commit.
89      *
90      * @exception DatabaseException most databases validate changes as they are done,
91      * normally errors do not occur on commit unless the disk fails or the connection is lost.
92      * @exception ConcurrencyException if this session is not within a transaction.
93      */

94     public void commitTransaction() throws DatabaseException;
95
96     /**
97      * PUBLIC:
98      * delete all of the objects and all of their privately owned parts in the database.
99      * The allows for a group of objects to be deleted as a unit.
100      * The objects will be deleted through a single transactions.
101      *
102      * @exception DatabaseException if an error occurs on the database,
103      * these include constraint violations, security violations and general database erros.
104      * @exception OptimisticLockException if the object's descriptor is using optimistic locking and
105      * the object has been updated or deleted by another user since it was last read.
106      */

107     public void deleteAllObjects(Collection domainObjects);
108
109     /**
110      * PUBLIC:
111      * delete all of the objects and all of their privately owned parts in the database.
112      * The allows for a group of objects to be deleted as a unit.
113      * The objects will be deleted through a single transactions.
114      *
115      * @exception DatabaseException if an error occurs on the database,
116      * these include constraint violations, security violations and general database erros.
117      * @exception OptimisticLockException if the object's descriptor is using optimistic locking and
118      * the object has been updated or deleted by another user since it was last read.
119      */

120     public void deleteAllObjects(Vector domainObjects);
121
122     /**
123      * PUBLIC:
124      * Delete the object and all of its privately owned parts from the database.
125      * The delete operation can be customized through using a delete query.
126      *
127      * @see oracle.toplink.essentials.queryframework.DeleteObjectQuery
128      */

129     public Object JavaDoc deleteObject(Object JavaDoc domainObject) throws DatabaseException, OptimisticLockException;
130
131     /**
132      * PUBLIC:
133      * Insert the object and all of its privately owned parts into the database.
134      * Insert should only be used if the application knows that the object is new,
135      * otherwise writeObject should be used.
136      * The insert operation can be customized through using an insert query.
137      *
138      * @see oracle.toplink.essentials.queryframework.InsertObjectQuery
139      * @see #writeObject(Object)
140      */

141     public Object JavaDoc insertObject(Object JavaDoc domainObject) throws DatabaseException;
142
143     /**
144      * PUBLIC:
145      * Return if the session is currently in the progress of a database transaction.
146      * Because nested transactions are allowed check if the transaction mutex has been aquired.
147      */

148     public boolean isInTransaction();
149
150     /**
151      * PUBLIC:
152      * Set the server platform defining server-specific behaviour for the receiver (Oc4j, WLS, ... ).
153      *
154      * This is not permitted after the session is logged in.
155      *
156      * If the user wants a different external transaction controller class or
157      * to provide some different behaviour than the provided ServerPlatform(s), we recommend
158      * subclassing oracle.toplink.essentials.platform.server.ServerPlatformBase (or a subclass),
159      * and overriding:
160      *
161      * ServerPlatformBase.getExternalTransactionControllerClass()
162      * ServerPlatformBase.registerMBean()
163      * ServerPlatformBase.unregisterMBean()
164      *
165      * for the desired behaviour.
166      *
167      * @see oracle.toplink.essentials.platform.server.ServerPlatformBase
168      */

169     public void setServerPlatform(ServerPlatform newServerPlatform);
170
171     /**
172      * PUBLIC:
173      * Answer the server platform defining server-specific behaviour for the receiver (Oc4j, WLS, ...).
174      *
175       * If the user wants a different external transaction controller class or
176      * to provide some different behaviour than the provided ServerPlatform(s), we recommend
177      * subclassing oracle.toplink.essentials.platform.server.ServerPlatformBase (or a subclass),
178      * and overriding:
179      *
180      * ServerPlatformBase.getExternalTransactionControllerClass()
181      * ServerPlatformBase.registerMBean()
182      * ServerPlatformBase.unregisterMBean()
183      *
184      * for the desired behaviour.
185      *
186      * @see oracle.toplink.essentials.platform.server.ServerPlatformBase
187     */

188     public ServerPlatform getServerPlatform();
189
190     /**
191      * PUBLIC:
192      * Return SequencingControl which used for sequencing setup and
193      * customization including management of sequencing preallocation.
194      */

195     public SequencingControl getSequencingControl();
196         
197     /**
198      * PUBLIC:
199      * Connect to the database using the predefined login.
200      * The login must have been assign when or after creating the session.
201      *
202      * @see #login(Login)
203      */

204     public void login() throws DatabaseException;
205
206     /**
207      * PUBLIC:
208      * Connect to the database using the given user name and password.
209      * The additional login information must have been preset in the session's login attribute.
210      * This is the login that should be used if each user has their own id,
211      * but all users share the same database configuration.
212      * Under this login mode the password should not stay withint the login definition after login.
213      */

214     public void login(String JavaDoc userName, String JavaDoc password) throws DatabaseException;
215
216     /**
217      * PUBLIC:
218      * Connect to the database using the given login.
219      * The login may also the preset and the login() protocol called.
220      * This is the login should only be used if each user has their own database configuration.
221      * Under this login mode the password should not stay withint the login definition after login.
222      */

223     public void login(Login login) throws DatabaseException;
224
225     /**
226      * PUBLIC:
227      * Disconnect from the database.
228      *
229      * @exception TopLinkException if a transaction is active, you must rollback any active transaction before logout.
230      * @exception DatabaseException the database will also raise an error if their is an active transaction,
231      * or a general error occurs.
232      */

233     public void logout() throws DatabaseException;
234
235     /**
236      * PUBLIC:
237      * Refresh the attributes of the object and of all of its private parts from the database.
238      * The object will be pessimisticly locked on the database for the duration of the transaction.
239      * If the object is already locked this method will wait until the lock is released.
240      * A no wait option is available through setting the lock mode.
241      * @see #refreshAndLockObject(Object, lockMode)
242      */

243     public Object JavaDoc refreshAndLockObject(Object JavaDoc object);
244
245     /**
246      * PUBLIC:
247      * Refresh the attributes of the object and of all of its private parts from the database.
248      * The object will be pessimisticly locked on the database for the duration of the transaction.
249      * <p>Lock Modes: ObjectBuildingQuery.NO_LOCK, LOCK, LOCK_NOWAIT
250      */

251     public Object JavaDoc refreshAndLockObject(Object JavaDoc object, short lockMode);
252
253     /**
254      * PUBLIC:
255      * Rollback the active database transaction.
256      * This allows a group of database modification to be commited or rolledback as a unit.
257      * All writes/deletes will be sent to the database be will not be visible to other users until commit.
258      * Although databases do not allow nested transaction,
259      * TopLink supports nesting through only committing to the database on the outer commit.
260      *
261      * @exception DatabaseException if the database connection is lost or the rollback fails.
262      * @exception ConcurrencyException if this session is not within a transaction.
263      */

264     public void rollbackTransaction() throws DatabaseException;
265
266     /**
267      * PUBLIC:
268      * Used for JTS integration. If your application requires to have JTS control transactions instead of TopLink an
269      * external transaction controler must be specified. TopLink provides JTS controlers for JTS 1.0 and Weblogic's JTS.
270      * @see oracle.toplink.essentials.transaction.JTATransactionController
271      * @see oracle.toplink.essentials.platform.server.CustomServerPlatform
272      */

273     public void setExternalTransactionController(ExternalTransactionController etc);
274
275     /**
276      * PUBLIC:
277      * Set the login.
278      */

279     public void setLogin(Login login);
280
281     /**
282      * PUBLIC:
283      * Set the login.
284      */

285     public void setDatasourceLogin(Login login);
286
287     /**
288      * PUBLIC:
289      * Update the object and all of its privately owned parts in the database.
290      * Update should only be used if the application knows that the object is new,
291      * otherwise writeObject should be used.
292      * The update operation can be customized through using an update query.
293      *
294      * @see oracle.toplink.essentials.queryframework.UpdateObjectQuery
295      * @see #writeObject(Object)
296      */

297     public Object JavaDoc updateObject(Object JavaDoc domainObject) throws DatabaseException, OptimisticLockException;
298
299     /**
300      * PUBLIC:
301      * Write all of the objects and all of their privately owned parts in the database.
302      * The allows for a group of objects to be commited as a unit.
303      * The objects will be commited through a single transactions.
304      *
305      * @exception DatabaseException if an error occurs on the database,
306      * these include constraint violations, security violations and general database erros.
307      * @exception OptimisticLockException if the object's descriptor is using optimistic locking and
308      * the object has been updated or deleted by another user since it was last read.
309      */

310     public void writeAllObjects(Collection domainObjects);
311
312     /**
313      * PUBLIC:
314      * Write all of the objects and all of their privately owned parts in the database.
315      * The allows for a group of objects to be commited as a unit.
316      * The objects will be commited through a single transactions.
317      *
318      * @exception DatabaseException if an error occurs on the database,
319      * these include constraint violations, security violations and general database erros.
320      * @exception OptimisticLockException if the object's descriptor is using optimistic locking and
321      * the object has been updated or deleted by another user since it was last read.
322      */

323     public void writeAllObjects(Vector domainObjects);
324
325     /**
326      * PUBLIC:
327      * Write the object and all of its privately owned parts in the database.
328      * Write will determine if an insert or an update should be done,
329      * it may go to the database to determine this (by default will check the identity map).
330      * The write operation can be customized through using an write query.
331      *
332      * @see oracle.toplink.essentials.queryframework.WriteObjectQuery
333      * @see #insertObject(Object)
334      * @see #updateObject(Object)
335      */

336     public Object JavaDoc writeObject(Object JavaDoc domainObject) throws DatabaseException, OptimisticLockException;
337 }
338
Popular Tags