01: /*
02: * Copyright 2002-2005 the original author or authors.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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: }
|