The Spring Framework

## org.springframework.orm.toplink
Class LocalSessionFactory

    java.lang.Object
      org.springframework.orm.toplink.LocalSessionFactory

Direct Known Subclasses:
  LocalSessionFactoryBean

    public class LocalSessionFactory

extends Object

Convenient JavaBean-style factory for a TopLink SessionFactory instance. Loads a TopLink `sessions.xml` file from the class path, exposing a specific TopLink Session defined there (usually a ServerSession).

TopLink Session configuration is done using a `sessions.xml` file. The most convenient way to create the `sessions.xml` file is to use the Oracle TopLink SessionsEditor workbench. The `sessions.xml` file contains all runtime configuration and points to a second XML or Class resource from which to load the actual TopLink project metadata (which defines mappings).

LocalSessionFactory loads the `sessions.xml` file during initialization in order to bootstrap the specified TopLink (Server)Session. The name of the actual config resource and the name of the Session to be loaded, if different from `sessions.xml` and "Session", respectively, can be configured through bean properties.

All resources (`sessions.xml` and Mapping Workbench metadata) are loaded using `ClassLoader.getResourceAsStream` calls by TopLink, so users may need to configure a ClassLoader with appropriate visibility. This is particularly important in J2EE environments where the TopLink metadata might be deployed to a different location than the Spring configuration. The ClassLoader used to search for the TopLink metadata and to load the persistent classes defined there will default to the the context ClassLoader for the current Thread.

TopLink's debug logging can be redirected to Commons Logging by passing a CommonsLoggingSessionLog to the "sessionLog" bean property. Otherwise, TopLink uses it's own DefaultSessionLog, whose levels are configured in the `sessions.xml` file.

This class has been tested against both TopLink 9.0.4 and TopLink 10.1.3. It will automatically adapt to the TopLink version encountered: for example, using an XMLSessionConfigLoader on 10.1.3, but an XMLLoader on 9.0.4.

NOTE: When defining a TopLink SessionFactory in a Spring application context, you will usually define a bean of type LocalSessionFactoryBean. LocalSessionFactoryBean is a subclass of this factory, which will automatically expose the created TopLink SessionFactory instance as bean reference.

Since:
  1.2
Author:
  Juergen Hoeller, James Clark
See Also:
  `LocalSessionFactoryBean`, `TopLinkAccessor.setSessionFactory(org.springframework.orm.toplink.SessionFactory)`, `TopLinkTransactionManager.setSessionFactory(org.springframework.orm.toplink.SessionFactory)`, `SingleSessionFactory`, `ServerSessionFactory`, `ServerSession`, `XMLLoader`, `XMLSessionConfigLoader`

Field Summary
`static String` `DEFAULT_SESSION_NAME` The default session name to look for in the sessions.xml: "Session".
`static String` `DEFAULT_SESSIONS_XML` The default location of the `sessions.xml` TopLink configuration file: "sessions.xml" in the class path.
`protected Log` `logger`

Constructor Summary
`LocalSessionFactory()`

Method Summary
`SessionFactory` `createSessionFactory()` Create a TopLink SessionFactory according to the configuration settings.
`Map` `getLoginPropertyMap()` Allow Map access to the TopLink login properties to be passed to the DatabaseLogin instance, with the option to add or override specific entries.
`protected oracle.toplink.tools.sessionmanagement.SessionManager` `getSessionManager()` Return the TopLink SessionManager to use for loading DatabaseSessions.
`protected oracle.toplink.sessions.DatabaseSession` `loadDatabaseSession(String configLocation, String sessionName, ClassLoader sessionClassLoader)` Load the specified DatabaseSession from the TopLink `sessions.xml` configuration file.
`protected SessionFactory` `newSessionFactory(oracle.toplink.sessions.DatabaseSession session)` Create a new SessionFactory for the given TopLink DatabaseSession.
`void` `setConfigLocation(String configLocation)` Set the TopLink `sessions.xml` configuration file that defines TopLink Sessions, as class path resource location.
`void` `setDatabaseLogin(oracle.toplink.sessions.DatabaseLogin databaseLogin)` Specify the DatabaseLogin instance that carries the TopLink database configuration to use.
`protected void` `setDatabaseLogin(oracle.toplink.sessions.DatabaseSession session, oracle.toplink.sessions.DatabaseLogin login)` Handle differences between the `Session.setLogin` interface between TopLink 9.0.4 to 10.1.3.
`void` `setDatabasePlatform(oracle.toplink.internal.databaseaccess.DatabasePlatform databasePlatform)` Specify the TopLink DatabasePlatform instance that the Session should use: for example, HSQLPlatform.
`void` `setDataSource(DataSource dataSource)` Specify a standard JDBC DataSource that TopLink should use as connection pool.
`void` `setLoginProperties(Properties loginProperties)` Specify TopLink login properties, to be passed to the `DatabaseLogin` instance.
`void` `setLoginPropertyMap(Map loginProperties)` Specify TopLink login properties as a Map, to be passed to the `DatabaseLogin` instance.
`void` `setSessionClassLoader(ClassLoader sessionClassLoader)` Set the ClassLoader that should be used to lookup the config resources.

`void`

`setSessionLog(oracle.toplink.sessions.SessionLog sessionLog)`
Specify a TopLink SessionLog instance to use for detailed logging of the Session's activities: for example, DefaultSessionLog (which logs to the console), JavaLog (which logs through JDK 1.4'S `java.util.logging`, available as of TopLink 10.1.3), or CommonsLoggingSessionLog / CommonsLoggingSessionLog904 (which logs through Commons Logging, on TopLink 10.1.3 and 9.0.4, respectively).

`void` `setSessionName(String sessionName)` Set the name of the TopLink Session, as defined in TopLink's `sessions.xml` configuration file.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT_SESSIONS_XML

    public static final String DEFAULT_SESSIONS_XML

  The default location of the `sessions.xml` TopLink configuration file: "sessions.xml" in the class path.

  See Also:
    Constant Field Values

### DEFAULT_SESSION_NAME

    public static final String DEFAULT_SESSION_NAME

  The default session name to look for in the sessions.xml: "Session".

  See Also:
    Constant Field Values

### logger

    protected final Log logger

Constructor Detail

### LocalSessionFactory

    public LocalSessionFactory()

Method Detail

### setConfigLocation

    public void setConfigLocation(String configLocation)

  Set the TopLink `sessions.xml` configuration file that defines TopLink Sessions, as class path resource location.

  The `sessions.xml` file will usually be placed in the META-INF directory or root path of a JAR file, or the `WEB-INF/classes` directory of a WAR file (specifying "META-INF/toplink-sessions.xml" or simply "toplink-sessions.xml" as config location, respectively).

  The default config location is "sessions.xml" in the root of the class path.

  Parameters:
    `configLocation` - the class path location of the `sessions.xml` file

### setSessionName

    public void setSessionName(String sessionName)

  Set the name of the TopLink Session, as defined in TopLink's `sessions.xml` configuration file. The default session name is "Session".

### setSessionClassLoader

    public void setSessionClassLoader(ClassLoader sessionClassLoader)

  Set the ClassLoader that should be used to lookup the config resources. If nothing is set here, then we will try to use the Thread context ClassLoader and the ClassLoader that loaded this factory class, in that order.

  This ClassLoader will be used to load the TopLink configuration files and the project metadata. Furthermore, the TopLink ConversionManager will use this ClassLoader to load all TopLink entity classes. If the latter is not appropriate, users can configure a pre-login SessionEvent to alter the ConversionManager ClassLoader that TopLink will use at runtime.

### setDatabaseLogin

    public void setDatabaseLogin(oracle.toplink.sessions.DatabaseLogin databaseLogin)

  Specify the DatabaseLogin instance that carries the TopLink database configuration to use. This is an alternative to specifying that information in a <login> tag in the `sessions.xml` configuration file, allowing for configuring a DatabaseLogin instance as standard Spring bean definition (being able to leverage Spring's placeholder mechanism, etc).

  The DatabaseLogin instance can either carry traditional JDBC config properties or hold a nested TopLink Connector instance, pointing to the connection pool to use. DatabaseLogin also holds the TopLink DatabasePlatform instance that defines the database product that TopLink is talking to (for example, HSQLPlatform).

  WARNING: Overriding the Login instance has been reported to not work on TopLink 10.1.3.0 and 10.1.3.1. Specify `"loginProperties"` or `"loginPropertyMap[...]"` entries instead, if you prefer to have the login configuration defined on the Spring LocalSessionFactory.

### setLoginProperties

    public void setLoginProperties(Properties loginProperties)

  Specify TopLink login properties, to be passed to the `DatabaseLogin` instance.

  Can be populated with a String "value" (parsed via PropertiesEditor) or a "props" element in XML bean definitions.

  See Also:
    `DatabaseLogin`

### setLoginPropertyMap

    public void setLoginPropertyMap(Map loginProperties)

  Specify TopLink login properties as a Map, to be passed to the `DatabaseLogin` instance.

  Can be populated with a "map" or "props" element in XML bean definitions.

  See Also:
    `DatabaseLogin`

### getLoginPropertyMap

    public Map getLoginPropertyMap()

  Allow Map access to the TopLink login properties to be passed to the DatabaseLogin instance, with the option to add or override specific entries.

  Useful for specifying entries directly, for example via "loginPropertyMap[tableQualifier]".

  See Also:
    `DatabaseLogin`

### setDataSource

    public void setDataSource(DataSource dataSource)

  Specify a standard JDBC DataSource that TopLink should use as connection pool. This allows for using a shared DataSource definition instead of TopLink's own connection pool.

  A passed-in DataSource will be wrapped in an appropriate TopLink Connector and registered with the TopLink DatabaseLogin instance (either the default instance or one passed in through the "databaseLogin" property). The "usesExternalConnectionPooling" flag will automatically be set to "true".

  See Also:
    `DatabaseLogin.setConnector(oracle.toplink.sessions.Connector)`, `DatabaseLogin.setUsesExternalConnectionPooling(boolean)`, `setDatabaseLogin(oracle.toplink.sessions.DatabaseLogin)`

### setDatabasePlatform

    public void setDatabasePlatform(oracle.toplink.internal.databaseaccess.DatabasePlatform databasePlatform)

  Specify the TopLink DatabasePlatform instance that the Session should use: for example, HSQLPlatform. This is an alternative to specifying the platform in a <login> tag in the `sessions.xml` configuration file.

  A passed-in DatabasePlatform will be registered with the TopLink DatabaseLogin instance (either the default instance or one passed in through the "databaseLogin" property).

  See Also:
    `HSQLPlatform`, `oracle.toplink.platform.database.HSQLPlatform`

### setSessionLog

    public void setSessionLog(oracle.toplink.sessions.SessionLog sessionLog)

  Specify a TopLink SessionLog instance to use for detailed logging of the Session's activities: for example, DefaultSessionLog (which logs to the console), JavaLog (which logs through JDK 1.4'S `java.util.logging`, available as of TopLink 10.1.3), or CommonsLoggingSessionLog / CommonsLoggingSessionLog904 (which logs through Commons Logging, on TopLink 10.1.3 and 9.0.4, respectively).

  Note that detailed Session logging is usually only useful for debug logging, with adjustable detail level. As of TopLink 10.1.3, TopLink also uses different log categories, which allows for fine-grained filtering of log messages. For standard execution, no SessionLog needs to be specified.

  See Also:
    `DefaultSessionLog`, `oracle.toplink.logging.DefaultSessionLog`, `oracle.toplink.logging.JavaLog`, `CommonsLoggingSessionLog`, `CommonsLoggingSessionLog904`

### createSessionFactory

    public SessionFactory createSessionFactory()
                                        throws oracle.toplink.exceptions.TopLinkException

  Create a TopLink SessionFactory according to the configuration settings.

  Returns:
    the new TopLink SessionFactory
  Throws:
    `oracle.toplink.exceptions.TopLinkException` - in case of errors

### setDatabaseLogin

    protected void setDatabaseLogin(oracle.toplink.sessions.DatabaseSession session,
                                    oracle.toplink.sessions.DatabaseLogin login)

  Handle differences between the `Session.setLogin` interface between TopLink 9.0.4 to 10.1.3.

  The Login interface was introduced in TopLink 10.1.3.

  Parameters:
    `session` - the DatabaseSession being logged in
    `login` - the DatabaseLogin injected by Spring
  See Also:
    `DatabaseSession.setLogin(oracle.toplink.sessions.DatabaseLogin)`

### loadDatabaseSession

    protected oracle.toplink.sessions.DatabaseSession loadDatabaseSession(String configLocation,
                                                                          String sessionName,
                                                                          ClassLoader sessionClassLoader)
                                                                   throws oracle.toplink.exceptions.TopLinkException

  Load the specified DatabaseSession from the TopLink `sessions.xml` configuration file.

  Parameters:
    `configLocation` - the class path location of the `sessions.xml` file
    `sessionName` - the name of the TopLink Session in the configuration file
    `sessionClassLoader` - the class loader to use
  Returns:
    the DatabaseSession instance
  Throws:
    `oracle.toplink.exceptions.TopLinkException` - in case of errors

### getSessionManager

    protected oracle.toplink.tools.sessionmanagement.SessionManager getSessionManager()

  Return the TopLink SessionManager to use for loading DatabaseSessions.

  The default implementation creates a new plain SessionManager instance, leading to completely independent TopLink Session instances. Could be overridden to return a shared or pre-configured SessionManager.

  Returns:
    the TopLink SessionManager instance

### newSessionFactory

    protected SessionFactory newSessionFactory(oracle.toplink.sessions.DatabaseSession session)

  Create a new SessionFactory for the given TopLink DatabaseSession.

  The default implementation creates a ServerSessionFactory for a ServerSession and a SingleSessionFactory for a plain DatabaseSession.

  Parameters:
    `session` - the TopLink DatabaseSession to create a SessionFactory for
  Returns:
    the SessionFactory
  Throws:
    `oracle.toplink.exceptions.TopLinkException` - in case of errors
  See Also:
    `ServerSessionFactory`, `SingleSessionFactory`, `ServerSession`, `DatabaseSession`

The Spring Framework

Copyright © 2002-2008 The Spring Framework.