oracle.toplink.essentials.threetier.Server Maven / Gradle / Ivy
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the "License"). You may not use this file except
* in compliance with the License.
*
* You can obtain a copy of the license at
* glassfish/bootstrap/legal/CDDLv1.0.txt or
* https://glassfish.dev.java.net/public/CDDLv1.0.html.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* HEADER in each file and include the License file at
* glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
* add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your
* own identifying information: Portions Copyright [yyyy]
* [name of copyright owner]
*/
// Copyright (c) 1998, 2005, Oracle. All rights reserved.
package oracle.toplink.essentials.threetier;
import oracle.toplink.essentials.sessions.*;
import oracle.toplink.essentials.exceptions.*;
/**
*
* Purpose: A single session that supports multiple user/clients connection at the same time.
*
* Description: This session supports a shared session that can be used by multiple users
* or clients in a three-tiered application. It brokers client sessions to allow read and write access
* through a unified object cache. The server session provides a shared read only database connection that
* is used by all of its client for reads. All changes to objects and the database must be done through
* a unit of work acquired from the client session, this allows the changes to occur in a transactional object
* space and under a exclusive database connection.
*
* Responsibilities:
*
* - Connecting/disconnecting the default reading login.
*
- Reading objects and maintaining the object cache.
*
- Brokering client sessions.
*
- Disabling database modification through the shared connection.
*
* @see ClientSession
* @see oracle.toplink.essentials.sessions.UnitOfWork UnitOfWork
*/
public interface Server extends oracle.toplink.essentials.sessions.DatabaseSession {
/**
* PUBLIC:
* Return a client session for this server session.
* Each user/client connected to this server session must acquire there own client session
* to communicate to the server through.
* This method allows for a client session to be acquired sharing the same login as the server session.
*/
public ClientSession acquireClientSession() throws DatabaseException;
/**
* PUBLIC:
* Return a client session for this server session.
* Each user/client connected to this server session must acquire there own client session
* to communicate to the server through.
* This method allows for a client session to be acquired sharing its connection from a pool
* of connection allocated on the server session.
* By default this uses a lazy connection policy.
*/
public ClientSession acquireClientSession(String poolName);
/**
* PUBLIC:
* Return a client session for this server session.
* Each user/client connected to this server session must acquire there own client session
* to communicate to the server through.
* The client must provide its own login to use, and the client session returned
* will have its own exclusive database connection. This connection will be used to perform
* all database modification for all units of work acquired from the client session.
* By default this does not use a lazy connection policy.
*/
public ClientSession acquireClientSession(Login login);
/**
* PUBLIC:
* Return a client session for this server session.
* The connection policy specifies how the client session's connection will be acquired.
*/
public ClientSession acquireClientSession(ConnectionPolicy connectionPolicy);
/**
* PUBLIC:
* Add the connection pool.
* Connections are pooled to share and restrict the number of database connections.
*/
public void addConnectionPool(String poolName, Login login, int minNumberOfConnections, int maxNumberOfConnections);
/**
* PUBLIC:
* Connection are pooled to share and restrict the number of database connections.
*/
public void addConnectionPool(ConnectionPool pool);
/**
* PUBLIC:
* Return the pool by name.
*/
public ConnectionPool getConnectionPool(String poolName);
/**
* PUBLIC:
* The default connection policy is used by default by the acquireClientConnection() protocol.
* By default it is a connection pool with min 5 and max 10 lazy pooled connections.
*/
public ConnectionPolicy getDefaultConnectionPolicy();
/**
* PUBLIC:
* Return the default connection pool.
*/
public ConnectionPool getDefaultConnectionPool();
/**
* PUBLIC:
* Return the number of non-pooled database connections allowed.
* This can be enforced to make up for the resource limitation of most JDBC drivers and database clients.
* By default this is 50.
*/
public int getMaxNumberOfNonPooledConnections();
/**
* PUBLIC:
* Handles allocating connections for read queries.
*
* By default a read connection pool is created and configured automatically in the
* constructor. A default read connection pool is one with two connections, and
* does not support concurrent reads.
*
The read connection pool is not used while in transaction.
* @see #setReadConnectionPool(ConnectionPool)
* @see #useExclusiveReadConnectionPool
* @see #useExternalReadConnectionPool
* @see #useReadConnectionPool
*/
public ConnectionPool getReadConnectionPool();
/**
* PUBLIC:
* Set the login.
*/
public void setDatasourceLogin(Login login);
/**
* PUBLIC:
* The default connection policy is used by default by the acquireClientConnection() protocol.
* By default it is a connection pool with min 5 and max 10 lazy pooled connections.
*/
public void setDefaultConnectionPolicy(ConnectionPolicy defaultConnectionPolicy);
/**
* PUBLIC:
* Set the number of non-pooled database connections allowed.
* This can be enforced to make up for the resource limitation of most JDBC drivers and database clients.
* By default this is 50.
*/
public void setMaxNumberOfNonPooledConnections(int maxNumberOfNonPooledConnections);
/**
* PUBLIC:
* Sets the read connection pool directly.
*
* Either {@link #useExclusiveReadConnectionPool} or {@link #useExternalReadConnectionPool} is
* called in the constructor. For a connection pool using concurrent reading
* {@link #useReadConnectionPool} should be called on a new instance of this
.
*
* @throws ValidationException if already connected
*/
public void setReadConnectionPool(ConnectionPool readConnectionPool);
/**
* PUBLIC:
* Sets the read connection pool to be a standard ConnectionPool
.
*
* Minimum and maximum number of connections is determined from the ConnectionPolicy. The defaults are 2 for both.
*
* Since the same type of connection pool is used as for writing, no
* two users will use the same connection for reading at the same time.
*
* This read connection pool is the default as some JDBC drivers do not support
* concurrent reading.
*
* Unless this
{@link oracle.toplink.essentials.sessions.Session#hasExternalTransactionController hasExternalTransactionController()}
* a read connection pool of this type will be setup in the constructor.
* @see #getReadConnectionPool
* @see #setReadConnectionPool(ConnectionPool)
* @see #useReadConnectionPool
* @see #useExternalReadConnectionPool
*/
public void useExclusiveReadConnectionPool(int minNumberOfConnections, int maxNumberOfConnections);
/**
* PUBLIC:
* Sets the read connection pool to be an ExternalConnectionPool
.
*
* This type of connection pool will be created and configured automatically if
* an external transaction controller is used.
* @see oracle.toplink.essentials.sessions.Session#hasExternalTransactionController
* @see #getReadConnectionPool
* @see #setReadConnectionPool(ConnectionPool)
* @see #useReadConnectionPool
* @see #useExclusiveReadConnectionPool
*/
public void useExternalReadConnectionPool();
/**
* PUBLIC:
* Sets the read connection pool to be a ReadConnectionPool
.
*
* Since read connections are not used for writing, multiple users can
* theoretically use the same connection at the same time. Most JDBC drivers
* have concurrent reading which supports this.
*
* Use this read connection pool to take advantage of concurrent reading.
*
* @param minNumberOfConnections
* @param maxNumberOfConnections As multiple readers can use the same connection
* concurrently fewer connections are needed.
* @see #getReadConnectionPool
* @see #setReadConnectionPool(ConnectionPool)
* @see #useExternalReadConnectionPool
* @see #useExclusiveReadConnectionPool
*/
public void useReadConnectionPool(int minNumberOfConnections, int maxNumberOfConnections);
}