KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > orm > toplink > SessionFactory


1 /*
2  * Copyright 2002-2005 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package org.springframework.orm.toplink;
18
19 import oracle.toplink.exceptions.TopLinkException;
20 import oracle.toplink.sessions.Session;
21
22 /**
23  * The SessionFactory interface serves as factory for TopLink Sessions,
24  * allowing for dependency injection on thread-safe TopLink-based DAOs.
25  * Used by TopLinkAccessor/Template and TopLinkTransactionManager.
26  *
27  * <p>In contrast to JDO or Hibernate (which define native PersistenceManagerFactory
28  * and SessionFactory interfaces, respectively), TopLink itself does not provide
29  * such a factory interface: hence, it is necessary to define it within Spring.
30  * Note that this interface does not depend on any other Spring interfaces or
31  * classes, to allow for keeping TopLink-based DAOs as independent as possible.
32  *
33  * @author Juergen Hoeller
34  * @since 1.2
35  * @see TopLinkAccessor#setSessionFactory
36  * @see TopLinkTransactionManager#setSessionFactory
37  */
38 public interface SessionFactory {
39
40     /**
41      * Create a plain TopLink Session for the current application context.
42      * Will usually be a new ClientSession for the current thread.
43      * <p>The returned Session will participate in JTA transactions (provided that
44      * TopLink is configured with a corresponding external transaction controller),
45      * but not in Spring-managed transactions (by TopLinkTransactionManager).
46      * <p>This is the factory method to be called by TopLink data access code,
47      * usually through the <code>SessionFactoryUtils.getSession</code> method
48      * that checks for a transactional (thread-bound) Session first.
49      * @return the new TopLink Session
50      * @throws TopLinkException in case of errors
51      * @see SessionFactoryUtils#getSession(SessionFactory, boolean)
52      */
53     Session createSession() throws TopLinkException;
54
55     /**
56      * Create a new managed TopLink client Session for the current context.
57      * Will usually be a new special ClientSession for the current thread.
58      * <p>The returned Session will be prepared to be managed within a Spring
59      * transaction (by TopLinkTransactionManager). It will carry an active
60      * UnitOfWork that expects to be committed at transaction completion,
61      * just like a plain TopLink Session does within a JTA transaction.
62      * <p>This method is only supposed to be called by Spring's
63      * TopLinkTransactionManager or similar TopLink-based transaction managers.
64      * If a SessionFactory does not support managed Sessions, it should throw
65      * an UnsupportedOperationException.
66      * @return the new TopLink Session
67      * @throws TopLinkException in case of errors
68      * @see oracle.toplink.sessions.Session#getActiveUnitOfWork()
69      */
70     Session createManagedClientSession() throws TopLinkException;
71
72     /**
73      * Create a new transaction-aware TopLink Session that exposes the currently
74      * active Session and UnitOfWork via <code>Session.getActiveSession()</code>
75      * and <code>Session.getActiveUnitOfWork()</code>, respectively.
76      * <p>Such a Session reference can be used analogously to a managed TopLink
77      * Session in a JTA environment, with Spring-managed transactions backing it.
78      * <p>It is usually preferable to let DAOs work with a full SessionFactory,
79      * accessing TopLink Sessions via <code>SessionFactoryUtils.getSession</code>.
80      * However, a transaction-aware TopLink Session reference does not impose any
81      * Spring dependency, so might be preferable if you'd like to keep your data
82      * access code tied to TopLink API only.
83      * @return the new TopLink Session
84      * @throws TopLinkException in case of errors
85      * @see oracle.toplink.sessions.Session#getActiveSession()
86      * @see oracle.toplink.sessions.Session#getActiveUnitOfWork()
87      */
88     Session createTransactionAwareSession() throws TopLinkException;
89
90     /**
91      * Close this SessionFactory, shutting down all internal resources.
92      */
93     void close();
94
95 }
96
Popular Tags