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   deleteObject(Object   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   insertObject(Object   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   userName, String   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   refreshAndLockObject(Object   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   refreshAndLockObject(Object   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   updateObject(Object   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   writeObject(Object   domainObject) throws DatabaseException, OptimisticLockException;
337 }
338
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags