Understanding the Session API

The session API is defined by the following interfaces:

• oracle.toplink.sessions.Session

• oracle.toplink.sessions.DatabaseSession

• oracle.toplink.sessions.UnitOfWork

• oracle.toplink.threetier.Server

These APIs are used at run time to access objects and the data source. Always use the session public interfaces, not the corresponding implementation classes.You should use the Session interface when reading and querying with any of client sessions, session brokers, isolated client sessions, historical client sessions, remote sessions, and database sessions.You should use the UnitOfWork interface for all units of work acquired from any type of session.You should use the Server interface to configure and acquire a client session from a Server session.The DatabaseSession interface can be used for a database session.Typically, you define server sessions, database sessions, and session broker sessions in a sessions.xml file and acquire them at run time using the SessionManager. You can also acquire a server session or database session from a Project. The only session that should ever be instantiated directly is the SessionBroker, and only when not using the SessionManager.

You acquire a client session from a server session.

You can also acquire a client session broker from a session broker composed of server sessions.

You acquire a unit of work from any session instance, client session broker, or session broker which contains DatabaseSession instances.

Example 75-5 illustrates the session interfaces that derive from abstract class oracle.toplink.sessions.Session interface.

Example 75-5 Session Interface Inheritance Hierarchy

oracle.toplink.sessions.Session
    oracle.toplink.sessions.DatabaseSession
        oracle.toplink.threetier.Server
    oracle.toplink.sessions.UnitOfWork