Server


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the "License").  You may not use this file except 
5    * in compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * glassfish/bootstrap/legal/CDDLv1.0.txt or 
9    * https://glassfish.dev.java.net/public/CDDLv1.0.html. 
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * HEADER in each file and include the License file at 
15   * glassfish/bootstrap/legal/CDDLv1.0.txt.  If applicable, 
16   * add the following below this CDDL HEADER, with the 
17   * fields enclosed by brackets "[]" replaced with your 
18   * own identifying information: Portions Copyright [yyyy] 
19   * [name of copyright owner]
20   */
21  // Copyright (c) 1998, 2005, Oracle. All rights reserved.  
22  package oracle.toplink.essentials.threetier;
23  
24  import oracle.toplink.essentials.sessions.*;
25  import oracle.toplink.essentials.exceptions.*;
26  
27  /**
28   * <p>
29   * <b>Purpose</b>: A single session that supports multiple user/clients connection at the same time.
30   * <p>
31   * <b>Description</b>: This session supports a shared session that can be used by multiple users
32   * or clients in a three-tiered application.  It brokers client sessions to allow read and write access
33   * through a unified object cache.  The server session provides a shared read only database connection that
34   * is used by all of its client for reads.  All changes to objects and the database must be done through
35   * a unit of work acquired from the client session, this allows the changes to occur in a transactional object
36   * space and under a exclusive database connection.
37   * <p>
38   * <b>Responsibilities</b>:
39   *    <ul>
40   *    <li> Connecting/disconnecting the default reading login.
41   *    <li> Reading objects and maintaining the object cache.
42   *    <li> Brokering client sessions.
43   *    <li> Disabling database modification through the shared connection.
44   *    </ul>
45   * @see ClientSession
46   * @see oracle.toplink.essentials.sessions.UnitOfWork UnitOfWork
47   */
48  public interface Server extends oracle.toplink.essentials.sessions.DatabaseSession {
49  
50      /**
51       * PUBLIC:
52       * Return a client session for this server session.
53       * Each user/client connected to this server session must acquire there own client session
54       * to communicate to the server through.
55       * This method allows for a client session to be acquired sharing the same login as the server session.
56       */
57      public ClientSession acquireClientSession() throws DatabaseException;
58  
59      /**
60       * PUBLIC:
61       * Return a client session for this server session.
62       * Each user/client connected to this server session must acquire there own client session
63       * to communicate to the server through.
64       * This method allows for a client session to be acquired sharing its connection from a pool
65       * of connection allocated on the server session.
66       * By default this uses a lazy connection policy.
67       */
68      public ClientSession acquireClientSession(String   poolName);
69  
70      /**
71       * PUBLIC:
72       * Return a client session for this server session.
73       * Each user/client connected to this server session must acquire there own client session
74       * to communicate to the server through.
75       * The client must provide its own login to use, and the client session returned
76       * will have its own exclusive database connection.  This connection will be used to perform
77       * all database modification for all units of work acquired from the client session.
78       * By default this does not use a lazy connection policy.
79       */
80      public ClientSession acquireClientSession(Login login);
81  
82      /**
83       * PUBLIC:
84       * Return a client session for this server session.
85       * The connection policy specifies how the client session's connection will be acquired.
86       */
87      public ClientSession acquireClientSession(ConnectionPolicy connectionPolicy);
88  
89      /**
90       * PUBLIC:
91       * Add the connection pool.
92       * Connections are pooled to share and restrict the number of database connections.
93       */
94      public void addConnectionPool(String   poolName, Login login, int minNumberOfConnections, int maxNumberOfConnections);
95  
96      /**
97       * PUBLIC:
98       * Connection are pooled to share and restrict the number of database connections.
99       */
100     public void addConnectionPool(ConnectionPool pool);
101 
102     /**
103      * PUBLIC:
104      * Return the pool by name.
105      */
106     public ConnectionPool getConnectionPool(String   poolName);
107 
108     /**
109      * PUBLIC:
110      * The default connection policy is used by default by the acquireClientConnection() protocol.
111      * By default it is a connection pool with min 5 and max 10 lazy pooled connections.
112      */
113     public ConnectionPolicy getDefaultConnectionPolicy();
114 
115     /**
116      * PUBLIC:
117      * Return the default connection pool.
118      */
119     public ConnectionPool getDefaultConnectionPool();
120 
121     /**
122      * PUBLIC:
123      * Return the number of non-pooled database connections allowed.
124      * This can be enforced to make up for the resource limitation of most JDBC drivers and database clients.
125      * By default this is 50.
126      */
127     public int getMaxNumberOfNonPooledConnections();
128 
129     /**
130      * PUBLIC:
131      * Handles allocating connections for read queries.
132      * <p>
133      * By default a read connection pool is created and configured automatically in the
134      * constructor.  A default read connection pool is one with two connections, and
135      * does not support concurrent reads.
136      * <p> The read connection pool is not used while in transaction.
137      * @see #setReadConnectionPool(ConnectionPool)
138      * @see #useExclusiveReadConnectionPool
139      * @see #useExternalReadConnectionPool
140      * @see #useReadConnectionPool
141      */
142     public ConnectionPool getReadConnectionPool();
143 
144     /**
145      * PUBLIC:
146      * Set the login.
147      */
148     public void setDatasourceLogin(Login login);
149 
150     /**
151      * PUBLIC:
152      * The default connection policy is used by default by the acquireClientConnection() protocol.
153      * By default it is a connection pool with min 5 and max 10 lazy pooled connections.
154      */
155     public void setDefaultConnectionPolicy(ConnectionPolicy defaultConnectionPolicy);
156 
157     /**
158      * PUBLIC:
159      * Set the number of non-pooled database connections allowed.
160      * This can be enforced to make up for the resource limitation of most JDBC drivers and database clients.
161      * By default this is 50.
162      */
163     public void setMaxNumberOfNonPooledConnections(int maxNumberOfNonPooledConnections);
164 
165     /**
166      * PUBLIC:
167      * Sets the read connection pool directly.
168      * <p>
169      * Either {@link #useExclusiveReadConnectionPool} or {@link #useExternalReadConnectionPool} is
170      * called in the constructor.  For a connection pool using concurrent reading
171      * {@link #useReadConnectionPool} should be called on a new instance of <code>this</code>.
172      *
173      * @throws ValidationException if already connected
174      */
175     public void setReadConnectionPool(ConnectionPool readConnectionPool);
176 
177     /**
178      * PUBLIC:
179      * Sets the read connection pool to be a standard <code>ConnectionPool</code>.
180      * <p>
181      * Minimum and maximum number of connections is determined from the ConnectionPolicy.  The defaults are 2 for both.
182      * <p>
183      * Since the same type of connection pool is used as for writing, no
184      * two users will use the same connection for reading at the same time.
185      * <p>
186      * This read connection pool is the default as some JDBC drivers do not support
187      * concurrent reading.
188      * <p>
189      * Unless <code>this</code> {@link oracle.toplink.essentials.sessions.Session#hasExternalTransactionController hasExternalTransactionController()}
190      * a read connection pool of this type will be setup in the constructor.
191      * @see #getReadConnectionPool
192      * @see #setReadConnectionPool(ConnectionPool)
193      * @see #useReadConnectionPool
194      * @see #useExternalReadConnectionPool
195      */
196     public void useExclusiveReadConnectionPool(int minNumberOfConnections, int maxNumberOfConnections);
197 
198     /**
199      * PUBLIC:
200      * Sets the read connection pool to be an <code>ExternalConnectionPool</code>.
201      * <p>
202      * This type of connection pool will be created and configured automatically if
203      * an external transaction controller is used.
204      * @see oracle.toplink.essentials.sessions.Session#hasExternalTransactionController
205      * @see #getReadConnectionPool
206      * @see #setReadConnectionPool(ConnectionPool)
207      * @see #useReadConnectionPool
208      * @see #useExclusiveReadConnectionPool
209      */
210     public void useExternalReadConnectionPool();
211 
212     /**
213      * PUBLIC:
214      * Sets the read connection pool to be a <code>ReadConnectionPool</code>.
215      * <p>
216      * Since read connections are not used for writing, multiple users can
217      * theoretically use the same connection at the same time.  Most JDBC drivers
218      * have concurrent reading which supports this.
219      * <p>
220      * Use this read connection pool to take advantage of concurrent reading.
221      * <p>
222      * @param minNumberOfConnections
223      * @param maxNumberOfConnections As multiple readers can use the same connection
224      * concurrently fewer connections are needed.
225      * @see #getReadConnectionPool
226      * @see #setReadConnectionPool(ConnectionPool)
227      * @see #useExternalReadConnectionPool
228      * @see #useExclusiveReadConnectionPool
229      */
230     public void useReadConnectionPool(int minNumberOfConnections, int maxNumberOfConnections);
231 
232 }
233
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags