001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * // Copyright (c) 1998, 2007, Oracle. All rights reserved.
005: *
006: *
007: * The contents of this file are subject to the terms of either the GNU
008: * General Public License Version 2 only ("GPL") or the Common Development
009: * and Distribution License("CDDL") (collectively, the "License"). You
010: * may not use this file except in compliance with the License. You can obtain
011: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
012: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
013: * language governing permissions and limitations under the License.
014: *
015: * When distributing the software, include this License Header Notice in each
016: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
017: * Sun designates this particular file as subject to the "Classpath" exception
018: * as provided by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the License
020: * Header, with the fields enclosed by brackets [] replaced by your own
021: * identifying information: "Portions Copyrighted [year]
022: * [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * If you wish your version of this file to be governed by only the CDDL or
027: * only the GPL Version 2, indicate your decision by adding "[Contributor]
028: * elects to include this software in this distribution under the [CDDL or GPL
029: * Version 2] license." If you don't indicate a single choice of license, a
030: * recipient has the option to distribute your version of this file under
031: * either the CDDL, the GPL Version 2 or to extend the choice of license to
032: * its licensees as provided above. However, if you add GPL Version 2 code
033: * and therefore, elected the GPL Version 2 license, then the option applies
034: * only if the new code is made subject to such option by the copyright
035: * holder.
036: */
037: package oracle.toplink.essentials.sessions;
038:
039: import java.util.*;
040: import java.io.*;
041: import oracle.toplink.essentials.descriptors.ClassDescriptor;
042: import oracle.toplink.essentials.expressions.*;
043: import oracle.toplink.essentials.queryframework.*;
044: import oracle.toplink.essentials.exceptions.*;
045: import oracle.toplink.essentials.logging.SessionLog;
046: import oracle.toplink.essentials.logging.SessionLogEntry;
047: import oracle.toplink.essentials.internal.databaseaccess.DatabasePlatform;
048: import oracle.toplink.essentials.internal.databaseaccess.Platform;
049:
050: /**
051: * <p>
052: * <b>Purpose</b>: Define the TopLink session public interface.
053: * <p>
054: * <b>Description</b>: This interface is meant to clarify the public protocol into TopLink.
055: * It also allows for non-subclasses of Session to conform to the TopLink API.
056: * It should be used as the applications main interface into the TopLink API to
057: * ensure compatibility between all TopLink sessions.
058: * <p>
059: * <b>Responsibilities</b>:
060: * <ul>
061: * <li> Define the API for all reading, units of work.
062: * </ul>
063: * @see UnitOfWork
064: * @see DatabaseSession
065: * @see oracle.toplink.essentials.publicinterface.Session
066: * @see oracle.toplink.essentials.publicinterface.DatabaseSession
067: * @see oracle.toplink.essentials.threetier.ServerSession
068: * @see oracle.toplink.essentials.threetier.ClientSession
069: */
070: public interface Session {
071:
072: /**
073: * PUBLIC:
074: * Return a unit of work for this session.
075: * The unit of work is an object level transaction that allows
076: * a group of changes to be applied as a unit.
077: * The return value should be used as the oracle.toplink.essentials.sessions.UnitOfWork interface,
078: * but must currently be returned as oracle.toplink.essentials.publicinterface.UnitOfWork to maintain backward
079: * compatibility.
080: *
081: * @see UnitOfWork
082: */
083: public UnitOfWork acquireUnitOfWork();
084:
085: /**
086: * PUBLIC:
087: * Add the query to the session queries with the given name.
088: * This allows for common queries to be pre-defined, reused and executed by name.
089: */
090: public void addQuery(String name, DatabaseQuery query);
091:
092: /**
093: * ADVANCED:
094: * Add a pre-defined not yet parsed EJBQL String/query to the session to be parsed
095: * after descriptors are initialized.
096: * @see #getAllQueries()
097: */
098: public void addEjbqlPlaceHolderQuery(DatabaseQuery query);
099:
100: /**
101: * PUBLIC:
102: * clear the integrityChecker, the integrityChecker holds all the Descriptor Exceptions.
103: */
104: public void clearIntegrityChecker();
105:
106: /**
107: * PUBLIC:
108: * Clear the profiler, this will end the current profile opperation.
109: */
110: public void clearProfile();
111:
112: /**
113: * PUBLIC:
114: * Return true if the pre-defined query is defined on the session.
115: **/
116: public boolean containsQuery(String queryName);
117:
118: /**
119: * PUBLIC:
120: * Return a complete copy of the object.
121: * This can be used to obtain a scatch copy of an object,
122: * or for templatizing an existing object into another new object.
123: * The object and all of its privately owned parts will be copied, the object's primary key will be reset to null.
124: *
125: * @see #copyObject(Object, ObjectCopyingPolicy)
126: */
127: public Object copyObject(Object original);
128:
129: /**
130: * PUBLIC:
131: * Return a complete copy of the object.
132: * This can be used to obtain a scatch copy of an object,
133: * or for templatizing an existing object into another new object.
134: * The object copying policy allow for the depth, and reseting of the primary key to null, to be specified.
135: */
136: public Object copyObject(Object original, ObjectCopyingPolicy policy);
137:
138: /**
139: * PUBLIC:
140: * Return if the object exists on the database or not.
141: * This always checks existence on the database.
142: */
143: public boolean doesObjectExist(Object object)
144: throws DatabaseException;
145:
146: /**
147: * PUBLIC:
148: * Turn off logging
149: */
150: public void dontLogMessages();
151:
152: /**
153: * PUBLIC:
154: * Execute the call on the database.
155: * The row count is returned.
156: * The call can be a stored procedure call, SQL call or other type of call.
157: * <p>Example:
158: * <p>session.executeNonSelectingCall(new SQLCall("Delete from Employee");
159: *
160: * @see #executeSelectingCall(Call)
161: */
162: public int executeNonSelectingCall(Call call);
163:
164: /**
165: * PUBLIC:
166: * Execute the non-selecting (update/DML) SQL string.
167: */
168: public void executeNonSelectingSQL(String sqlString);
169:
170: /**
171: * PUBLIC:
172: * Execute the pre-defined query by name and return the result.
173: * Queries can be pre-defined and named to allow for their reuse.
174: *
175: * @see #addQuery(String, DatabaseQuery)
176: */
177: public Object executeQuery(String queryName);
178:
179: /**
180: * PUBLIC:
181: * Execute the pre-defined query by name and return the result.
182: * Queries can be pre-defined and named to allow for their reuse.
183: * The class is the descriptor in which the query was pre-defined.
184: *
185: * @see oracle.toplink.essentials.descriptors.DescriptorQueryManager#addQuery(String, DatabaseQuery)
186: */
187: public Object executeQuery(String queryName, Class domainClass);
188:
189: /**
190: * PUBLIC:
191: * Execute the pre-defined query by name and return the result.
192: * Queries can be pre-defined and named to allow for their reuse.
193: * The class is the descriptor in which the query was pre-defined.
194: *
195: * @see oracle.toplink.essentials.descriptors.DescriptorQueryManager#addQuery(String, DatabaseQuery)
196: */
197: public Object executeQuery(String queryName, Class domainClass,
198: Object arg1);
199:
200: /**
201: * PUBLIC:
202: * Execute the pre-defined query by name and return the result.
203: * Queries can be pre-defined and named to allow for their reuse.
204: * The class is the descriptor in which the query was pre-defined.
205: *
206: * @see oracle.toplink.essentials.descriptors.DescriptorQueryManager#addQuery(String, DatabaseQuery)
207: */
208: public Object executeQuery(String queryName, Class domainClass,
209: Object arg1, Object arg2);
210:
211: /**
212: * PUBLIC:
213: * Execute the pre-defined query by name and return the result.
214: * Queries can be pre-defined and named to allow for their reuse.
215: * The class is the descriptor in which the query was pre-defined.
216: *
217: * @see oracle.toplink.essentials.descriptors.DescriptorQueryManager#addQuery(String, DatabaseQuery)
218: */
219: public Object executeQuery(String queryName, Class domainClass,
220: Object arg1, Object arg2, Object arg3);
221:
222: /**
223: * PUBLIC:
224: * Execute the pre-defined query by name and return the result.
225: * Queries can be pre-defined and named to allow for their reuse.
226: * The class is the descriptor in which the query was pre-defined.
227: *
228: * @see oracle.toplink.essentials.descriptors.DescriptorQueryManager#addQuery(String, DatabaseQuery)
229: */
230: public Object executeQuery(String queryName, Class domainClass,
231: Vector argumentValues);
232:
233: /**
234: * PUBLIC:
235: * Execute the pre-defined query by name and return the result.
236: * Queries can be pre-defined and named to allow for their reuse.
237: *
238: * @see #addQuery(String, DatabaseQuery)
239: */
240: public Object executeQuery(String queryName, Object arg1);
241:
242: /**
243: * PUBLIC:
244: * Execute the pre-defined query by name and return the result.
245: * Queries can be pre-defined and named to allow for their reuse.
246: *
247: * @see #addQuery(String, DatabaseQuery)
248: */
249: public Object executeQuery(String queryName, Object arg1,
250: Object arg2);
251:
252: /**
253: * PUBLIC:
254: * Execute the pre-defined query by name and return the result.
255: * Queries can be pre-defined and named to allow for their reuse.
256: *
257: * @see #addQuery(String, DatabaseQuery)
258: */
259: public Object executeQuery(String queryName, Object arg1,
260: Object arg2, Object arg3);
261:
262: /**
263: * PUBLIC:
264: * Execute the pre-defined query by name and return the result.
265: * Queries can be pre-defined and named to allow for their reuse.
266: *
267: * @see #addQuery(String, DatabaseQuery)
268: */
269: public Object executeQuery(String queryName, Vector argumentValues);
270:
271: /**
272: * PUBLIC:
273: * Execute the database query.
274: * A query is a database operation such as reading or writting.
275: * The query allows for the operation to be customized for such things as,
276: * performance, depth, caching, etc.
277: *
278: * @see DatabaseQuery
279: */
280: public Object executeQuery(DatabaseQuery query)
281: throws TopLinkException;
282:
283: /**
284: * PUBLIC:
285: * Return the results from exeucting the database query.
286: * the arguments are passed in as a vector
287: */
288: public Object executeQuery(DatabaseQuery query,
289: Vector argumentValues);
290:
291: /**
292: * PUBLIC:
293: * Execute the call on the database and return the result.
294: * The call must return a value, if no value is return executeNonSelectCall must be used.
295: * The call can be a stored procedure call, SQL call or other type of call.
296: * A vector of database rows is returned, database row implements Java 2 Map which should be used to access the data.
297: * <p>Example:
298: * <p>session.executeSelectingCall(new SQLCall("Select * from Employee");
299: *
300: * @see #executeNonSelectingCall(Call)
301: */
302: public Vector executeSelectingCall(Call call);
303:
304: /**
305: * PUBLIC:
306: * Execute the selecting SQL string.
307: * A Vector of DatabaseRecords are returned.
308: */
309: public Vector executeSQL(String sqlString);
310:
311: /**
312: * PUBLIC:
313: * Return the active session for the current active external (JTS) transaction.
314: * This should only be used with JTS and will return the session if no external transaction exists.
315: */
316: public Session getActiveSession();
317:
318: /**
319: * PUBLIC:
320: * Return the active unit of work for the current active external (JTS) transaction.
321: * This should only be used with JTS and will return null if no external transaction exists.
322: */
323: public UnitOfWork getActiveUnitOfWork();
324:
325: /**
326: * ADVANCED:
327: * Return the descriptor specified for the class.
328: * If the class does not have a descriptor but implements an interface that is also implemented
329: * by one of the classes stored in the hashtable, that descriptor will be stored under the
330: * new class.
331: */
332: public ClassDescriptor getClassDescriptor(Class theClass);
333:
334: /**
335: * ADVANCED:
336: * Return the descriptor specified for the object's class.
337: */
338: public ClassDescriptor getClassDescriptor(Object domainObject);
339:
340: /**
341: * PUBLIC:
342: * Return the descriptor for the alias.
343: */
344: public ClassDescriptor getClassDescriptorForAlias(String alias);
345:
346: /**
347: * ADVANCED:
348: * Return the descriptor specified for the object's class.
349: */
350: public ClassDescriptor getDescriptor(Class theClass);
351:
352: /**
353: * ADVANCED:
354: * Return the descriptor specified for the object's class.
355: */
356: public ClassDescriptor getDescriptor(Object domainObject);
357:
358: /**
359: * PUBLIC:
360: * Return the descriptor for the alias.
361: */
362: public ClassDescriptor getDescriptorForAlias(String alias);
363:
364: /**
365: * ADVANCED:
366: * Return all registered descriptors.
367: */
368: public Map getDescriptors();
369:
370: /**
371: * ADVANCED:
372: * Return all pre-defined not yet parsed EJBQL queries.
373: * @see #getAllQueries()
374: */
375: public List getEjbqlPlaceHolderQueries();
376:
377: /**
378: * PUBLIC:
379: * Return the event manager.
380: * The event manager can be used to register for various session events.
381: */
382: public SessionEventManager getEventManager();
383:
384: /**
385: * PUBLIC:
386: * Return the ExceptionHandler.Exception handler can catch errors that occur on queries or during database access.
387: */
388: public ExceptionHandler getExceptionHandler();
389:
390: /**
391: * PUBLIC:
392: * Used for JTS integration. If your application requires to have JTS control transactions instead of TopLink an
393: * external transaction controler must be specified. TopLink provides JTS controlers for JTS 1.0 and Weblogic's JTS.
394: * @see oracle.toplink.essentials.transaction.JTATransactionController
395: */
396: public ExternalTransactionController getExternalTransactionController();
397:
398: /**
399: * PUBLIC:
400: * The IdentityMapAccessor is the preferred way of accessing IdentityMap funcitons
401: * This will return an object which implements an interface which exposes all public
402: * IdentityMap functions.
403: */
404: public IdentityMapAccessor getIdentityMapAccessor();
405:
406: /**
407: * PUBLIC:
408: * Returns the integrityChecker,the integrityChecker holds all the Descriptor Exceptions.
409: */
410: public IntegrityChecker getIntegrityChecker();
411:
412: /**
413: * PUBLIC:
414: * Return the writer to which an accessor writes logged messages and SQL.
415: * If not set, this reference defaults to a writer on System.out.
416: */
417: public Writer getLog();
418:
419: /**
420: * PUBLIC:
421: * Return the database platform currently connected to.
422: * The platform is used for database specific behavoir.
423: * NOTE: this must only be used for relational specific usage,
424: * it will fail for non-relational datasources.
425: */
426: public DatabasePlatform getPlatform();
427:
428: /**
429: * PUBLIC:
430: * Return the database platform currently connected to.
431: * The platform is used for database specific behavoir.
432: */
433: public Platform getDatasourcePlatform();
434:
435: /**
436: * PUBLIC:
437: * Return the login, the login holds any database connection information given.
438: * This has been replaced by getDatasourceLogin to make use of the Login interface
439: * to support non-relational datasources,
440: * if DatabaseLogin API is required it will need to be cast.
441: */
442: public DatabaseLogin getLogin();
443:
444: /**
445: * PUBLIC:
446: * Return the login, the login holds any database connection information given.
447: * This return the Login interface and may need to be cast to the datasource specific implementation.
448: */
449: public Login getDatasourceLogin();
450:
451: /**
452: * PUBLIC:
453: * Return the name of the session.
454: * This is used with the session broker, or to give the session a more meaningful name.
455: */
456: public String getName();
457:
458: /**
459: * ADVANCED:
460: * Return the sequnce number from the database
461: */
462: public Number getNextSequenceNumberValue(Class domainClass);
463:
464: /**
465: * PUBLIC:
466: * Return the profiler.
467: * The profiler is a tool that can be used to determine performance bottlenecks.
468: * The profiler can be queries to print summaries and configure for logging purposes.
469: */
470: public SessionProfiler getProfiler();
471:
472: /**
473: * PUBLIC:
474: * Return the project.
475: * The project includes the login and descriptor and other configuration information.
476: */
477: public oracle.toplink.essentials.sessions.Project getProject();
478:
479: /**
480: * ADVANCED:
481: * Allow for user defined properties.
482: */
483: public Map getProperties();
484:
485: /**
486: * ADVANCED:
487: * Returns the user defined property.
488: */
489: public Object getProperty(String name);
490:
491: /**
492: * ADVANCED:
493: * Return all pre-defined queries.
494: */
495: public Map getQueries();
496:
497: /**
498: * PUBLIC:
499: * Return the query from the session pre-defined queries with the given name.
500: * This allows for common queries to be pre-defined, reused and executed by name.
501: */
502: public DatabaseQuery getQuery(String name);
503:
504: /**
505: * PUBLIC:
506: * Return the query from the session pre-defined queries with the given name.
507: * This allows for common queries to be pre-defined, reused and executed by name.
508: */
509: public DatabaseQuery getQuery(String name, Vector arguments);
510:
511: /**
512: * PUBLIC:
513: * Return the session log to which an accessor logs messages and SQL.
514: * If not set, this will default to a session log on a writer on System.out.
515: */
516: public SessionLog getSessionLog();
517:
518: /**
519: * PUBLIC:
520: * Allow any WARNING level exceptions that occur within TopLink to be logged and handled by the exception handler.
521: */
522: public Object handleException(RuntimeException exception)
523: throws RuntimeException;
524:
525: /**
526: * ADVANCED:
527: * Return true if a descriptor exists for the given class.
528: */
529: public boolean hasDescriptor(Class theClass);
530:
531: /**
532: * PUBLIC:
533: * Return if an exception handler is present.
534: */
535: public boolean hasExceptionHandler();
536:
537: /**
538: * PUBLIC:
539: * Used for JTS integration. If your application requires to have JTS control transactions instead of TopLink an
540: * external transaction controler must be specified. TopLink provides JTS controlers for JTS 1.0 and Weblogic's JTS.
541: * @see oracle.toplink.essentials.transaction.JTATransactionController
542: */
543: public boolean hasExternalTransactionController();
544:
545: /**
546: * PUBLIC:
547: * Return if this session is a client session.
548: */
549: public boolean isClientSession();
550:
551: /**
552: * PUBLIC:
553: * Return if this session is connected to the database.
554: */
555: public boolean isConnected();
556:
557: /**
558: * PUBLIC:
559: * Return if this session is a database session.
560: */
561: public boolean isDatabaseSession();
562:
563: /**
564: * PUBLIC:
565: * Return if this session is a distributed session.
566: */
567: public boolean isDistributedSession();
568:
569: /**
570: * PUBLIC:
571: * Return if a profiler is being used.
572: */
573: public boolean isInProfile();
574:
575: /**
576: * PUBLIC:
577: * Return if this session is a remote session.
578: */
579: public boolean isRemoteSession();
580:
581: /**
582: * PUBLIC:
583: * Return if this session is a server session.
584: */
585: public boolean isServerSession();
586:
587: /**
588: * PUBLIC:
589: * Return if this session is a session broker.
590: */
591: public boolean isSessionBroker();
592:
593: /**
594: * PUBLIC:
595: * Return if this session is a unit of work.
596: */
597: public boolean isUnitOfWork();
598:
599: /**
600: * PUBLIC:
601: * Return if this session is a remote unit of work.
602: */
603: public boolean isRemoteUnitOfWork();
604:
605: /**
606: * ADVANCED:
607: * Extract and return the primary key from the object.
608: */
609: public Vector keyFromObject(Object domainObject)
610: throws ValidationException;
611:
612: /**
613: * PUBLIC:
614: * Log the log entry.
615: */
616: public void log(SessionLogEntry entry);
617:
618: /**
619: * Log a untranslated message to the TopLink log at FINER level.
620: */
621: public void logMessage(String message);
622:
623: /**
624: * PUBLIC:
625: * <p>
626: * Log a message with level and category.
627: * </p><p>
628: *
629: * @param level, the log request level value
630: * </p><p>
631: * @param message, the string message
632: * </p><p>
633: * @param category, the string representation of a TopLink category.
634: * </p>
635: */
636: public void log(int level, String category, String message);
637:
638: /**
639: * PUBLIC:
640: * <p>
641: * Log a throwable with level and category.
642: * </p><p>
643: *
644: * @param level, the log request level value
645: * </p><p>
646: * @param category, the string representation of a TopLink category.
647: * </p><p>
648: * @param throwable, a Throwable
649: * </p>
650: */
651: public void logThrowable(int level, String category,
652: Throwable throwable);
653:
654: /**
655: * PUBLIC:
656: * Read all of the instances of the class from the database.
657: * This operation can be customized through using a ReadAllQuery,
658: * or through also passing in a selection criteria.
659: *
660: * @see ReadAllQuery
661: * @see #readAllObjects(Class, Expression)
662: */
663: public Vector readAllObjects(Class domainClass)
664: throws DatabaseException;
665:
666: /**
667: * PUBLIC:
668: * Read all the instances of the class from the database returned through execution the Call string.
669: * The Call can be an SQLCall or EJBQLCall.
670: *
671: * example: session.readAllObjects(Employee.class, new SQLCall("SELECT * FROM EMPLOYEE"));
672: * @see SQLCall
673: * @see EJBQLCall
674: */
675: public Vector readAllObjects(Class domainClass, Call aCall)
676: throws DatabaseException;
677:
678: /**
679: * PUBLIC:
680: * Read all of the instances of the class from the database matching the given expression.
681: * This operation can be customized through using a ReadAllQuery.
682: *
683: * @see ReadAllQuery
684: */
685: public Vector readAllObjects(Class domainClass,
686: Expression selectionCriteria) throws DatabaseException;
687:
688: /**
689: * PUBLIC:
690: * Read the first instance of the class from the database.
691: * This operation can be customized through using a ReadObjectQuery,
692: * or through also passing in a selection criteria.
693: * By default, this method executes a query without selection criteria and
694: * consequently it will always result in a database access even if an instance
695: * of the specified Class exists in the cache. Executing a query with
696: * selection criteria allows you to avoid a database access if the selected
697: * instance is in the cache.
698: * Because of this, you may whish to consider a readObject method that takes selection criteria, such as: {@link #readObject(Class, Call)}, {@link #readObject(Class, Expression)}, or {@link #readObject(Object)}.
699: * @see ReadObjectQuery
700: * @see #readAllObjects(Class, Expression)
701: */
702: public Object readObject(Class domainClass)
703: throws DatabaseException;
704:
705: /**
706: * PUBLIC:
707: * Read the first instance of the class from the database returned through execution the Call string.
708: * The Call can be an SQLCall or EJBQLCall.
709: *
710: * example: session.readObject(Employee.class, new SQLCall("SELECT * FROM EMPLOYEE"));
711: * @see SQLCall
712: * @see EJBQLCall
713: */
714: public Object readObject(Class domainClass, Call aCall)
715: throws DatabaseException;
716:
717: /**
718: * PUBLIC:
719: * Read the first instance of the class from the database matching the given expression.
720: * This operation can be customized through using a ReadObjectQuery.
721: *
722: * @see ReadObjectQuery
723: */
724: public Object readObject(Class domainClass,
725: Expression selectionCriteria) throws DatabaseException;
726:
727: /**
728: * PUBLIC:
729: * Use the example object to consruct a read object query by the objects primary key.
730: * This will read the object from the database with the same primary key as the object
731: * or null if no object is found.
732: */
733: public Object readObject(Object object) throws DatabaseException;
734:
735: /**
736: * PUBLIC:
737: * Refresh the attributes of the object and of all of its private parts from the database.
738: * This can be used to ensure the object is up to date with the database.
739: * Caution should be used when using this to make sure the application has no un commited
740: * changes to the object.
741: */
742: public Object refreshObject(Object object);
743:
744: /**
745: * PUBLIC:
746: * Release the session.
747: * This does nothing by default, but allows for other sessions such as the ClientSession to do something.
748: */
749: public void release();
750:
751: /**
752: * PUBLIC:
753: * Remove the user defined property.
754: */
755: public void removeProperty(String property);
756:
757: /**
758: * PUBLIC:
759: * Remove the query name from the set of pre-defined queries
760: */
761: public void removeQuery(String queryName);
762:
763: /**
764: * PUBLIC:
765: * Set the exceptionHandler.
766: * Exception handler can catch errors that occur on queries or during database access.
767: */
768: public void setExceptionHandler(ExceptionHandler exceptionHandler);
769:
770: /**
771: * Set the transaction controller, allow integration with JTA.
772: */
773: public void setExternalTransactionController(
774: ExternalTransactionController externalTransactionController);
775:
776: /**
777: * PUBLIC:
778: * Set the integrityChecker, the integrityChecker holds all the Descriptor Exceptions.
779: */
780: public void setIntegrityChecker(IntegrityChecker integrityChecker);
781:
782: /**
783: * PUBLIC:
784: * Set the writer to which an accessor writes logged messages and SQL.
785: * If not set, this reference defaults to a writer on System.out.
786: */
787: public void setLog(Writer log);
788:
789: /**
790: * PUBLIC:
791: * Set the name of the session.
792: * This is used with the session broker, or to give the session a more meaningful name.
793: */
794: public void setName(String name);
795:
796: /**
797: * PUBLIC:
798: * Set the profiler for the session.
799: * This allows for performance operations to be profiled.
800: */
801: public void setProfiler(SessionProfiler profiler);
802:
803: /**
804: * PUBLIC:
805: * Allow for user defined properties.
806: */
807: public void setProperty(String propertyName, Object propertyValue);
808:
809: /**
810: * PUBLIC:
811: * Set the session log to which an accessor logs messages and SQL.
812: * If not set, this will default to a session log on a writer on System.out.
813: * To enable logging, logMessages must be turned on.
814: */
815: public void setSessionLog(SessionLog sessionLog);
816:
817: /**
818: * PUBLIC:
819: * Return if logging is enabled (false if log level is OFF)
820: */
821: public boolean shouldLogMessages();
822:
823: /**
824: * PUBLIC:
825: * Return the log level
826: */
827: public int getLogLevel(String category);
828:
829: /**
830: * PUBLIC:
831: * Return the log level
832: */
833: public int getLogLevel();
834:
835: /**
836: * PUBLIC:
837: * Set the log level
838: */
839: public void setLogLevel(int level);
840:
841: /**
842: * PUBLIC:
843: * Check if a message of the given level would actually be logged.
844: */
845: public boolean shouldLog(int Level, String category);
846:
847: /**
848: * PUBLIC:
849: * Allow any SEVERE level exceptions that occur within TopLink to be logged and handled by the exception handler.
850: */
851: public Object handleSevere(RuntimeException exception)
852: throws RuntimeException;
853: }
|