ManagedConnectionFactory


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 in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
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 Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package javax.resource.spi;
25  
26  import javax.security.auth.Subject  ;
27  import java.util.Set  ;
28  import javax.resource.ResourceException  ;
29  import javax.resource.NotSupportedException  ;
30  
31  /** 
32   * ManagedConnectionFactory instance is a factory of both ManagedConnection
33   *  and EIS-specific connection factory instances. This interface supports 
34   *  connection pooling by providing methods for matching and creation of
35   *  ManagedConnection instance. A ManagedConnectionFactory 
36   *  instance is required to be a JavaBean.
37   *
38   *  @version     0.6
39   *  @author      Rahul Sharma
40   *
41   *  @see         javax.resource.spi.ManagedConnection
42   */
43  
44  public interface ManagedConnectionFactory extends java.io.Serializable   {
45  
46      /**
47       * Creates a Connection Factory instance. The Connection Factory
48       *  instance gets initialized with the passed ConnectionManager. In
49       *  the managed scenario, ConnectionManager is provided by the 
50       *  application server.
51       *
52       *  @param    cxManager    ConnectionManager to be associated with
53       *                         created EIS connection factory instance
54       *  @return   EIS-specific Connection Factory instance or
55       *            javax.resource.cci.ConnectionFactory instance
56       *   
57       *  @throws   ResourceException     Generic exception
58       *  @throws   ResourceAdapterInternalException
59       *                Resource adapter related error condition
60       */
61      public Object   createConnectionFactory(ConnectionManager   cxManager)
62      throws ResourceException  ;
63  
64      /**
65       * Creates a Connection Factory instance. The Connection Factory 
66       *  instance gets initialized with a default ConnectionManager provided
67       *  by the resource adapter.
68       *
69       *  @return   EIS-specific Connection Factory instance or
70       *            javax.resource.cci.ConnectionFactory instance
71       *
72       *  @throws   ResourceException     Generic exception
73       *  @throws   ResourceAdapterInternalException
74       *                Resource adapter related error condition
75       */
76      public Object   createConnectionFactory() throws ResourceException  ;
77  
78   
79      /** 
80       * Creates a new physical connection to the underlying EIS 
81       *  resource manager.
82       *
83       *  <p>ManagedConnectionFactory uses the security information (passed as
84       *  Subject) and additional ConnectionRequestInfo (which is specific to
85       *  ResourceAdapter and opaque to application server) to create this new
86       *  connection.
87       *
88       *  @param   subject        Caller's security information
89       *  @param   cxRequestInfo  Additional resource adapter specific connection
90       *                          request information
91       *
92       *  @throws  ResourceException     generic exception
93       *  @throws  SecurityException     security related error
94       *  @throws  ResourceAllocationException
95       *                                 failed to allocate system resources for
96       *                                 connection request
97       *  @throws  ResourceAdapterInternalException
98       *                                 resource adapter related error condition
99       *  @throws  EISSystemException    internal error condition in EIS instance
100      *
101      *  @return  ManagedConnection instance
102      */
103     public ManagedConnection   createManagedConnection(
104                   Subject   subject, 
105                   ConnectionRequestInfo   cxRequestInfo) 
106     throws ResourceException  ;
107 
108     /** 
109      * Returns a matched connection from the candidate set of connections. 
110      *  
111      *  
112      *  <p>ManagedConnectionFactory uses the security info (as in Subject)
113      *  and information provided through ConnectionRequestInfo and additional
114      *  Resource Adapter specific criteria to do matching. Note that criteria
115      *  used for matching is specific to a resource adapter and is not
116      *  prescribed by the Connector specification.</p>
117      *
118      *  <p>This method returns a ManagedConnection instance that is the best 
119      *  match for handling the connection allocation request.</p>
120      *
121      *  @param   connectionSet   candidate connection set
122      *  @param   subject         caller's security information
123      *  @param   cxRequestInfo   additional resource adapter specific 
124      *                           connection request information  
125      *
126      *  @throws  ResourceException     generic exception
127      *  @throws  SecurityException     security related error
128      *  @throws  ResourceAdapterInternalException
129      *                                 resource adapter related error condition
130      *  @throws  NotSupportedException if operation is not supported
131      *
132      *  @return  ManagedConnection     if resource adapter finds an
133      *                                 acceptable match otherwise null
134      **/
135     public ManagedConnection   matchManagedConnections(
136                       Set   connectionSet,
137                       Subject   subject,
138                       ConnectionRequestInfo    cxRequestInfo) 
139     throws ResourceException  ;
140 
141     /** 
142      * Set the log writer for this ManagedConnectionFactory instance.</p>
143      *
144      *  <p>The log writer is a character output stream to which all logging and
145      *  tracing messages for this ManagedConnectionfactory instance will be 
146      *  printed.</p>
147      *
148      * <p>ApplicationServer manages the association of output stream with the
149      *  ManagedConnectionFactory. When a ManagedConnectionFactory object is 
150      *  created the log writer is initially null, in other words, logging is 
151      *  disabled. Once a log writer is associated with a
152      *  ManagedConnectionFactory, logging and tracing for 
153      *  ManagedConnectionFactory instance is enabled.
154      *
155      *  <p>The ManagedConnection instances created by ManagedConnectionFactory
156      *  "inherits" the log writer, which can be overridden by ApplicationServer
157      *  using ManagedConnection.setLogWriter to set ManagedConnection specific
158      *  logging and tracing.
159      *
160      *  @param   out                   PrintWriter - an out stream for
161      *                                 error logging and tracing
162      *  @throws  ResourceException     generic exception
163      *  @throws  ResourceAdapterInternalException
164      *                                 resource adapter related error condition
165      */
166     public void setLogWriter(java.io.PrintWriter   out) throws ResourceException  ;
167 
168     /** 
169      * Get the log writer for this ManagedConnectionFactory instance.
170      *
171      *  <p>The log writer is a character output stream to which all logging and
172      *  tracing messages for this ManagedConnectionFactory instance will be 
173      *  printed
174      *
175      *  <p>ApplicationServer manages the association of output stream with the
176      *  ManagedConnectionFactory. When a ManagedConnectionFactory object is 
177      *  created the log writer is initially null, in other words, logging is 
178      *  disabled.
179      *
180      *  @return  PrintWriter
181      *  @throws  ResourceException     generic exception
182      */
183     public java.io.PrintWriter   getLogWriter() throws ResourceException  ;
184 
185     /** 
186      * Returns the hash code for the ManagedConnectionFactory
187      * 
188      *  @return  hash code for the ManagedConnectionFactory
189      */
190     public int hashCode();
191 
192     /** 
193      * Check if this ManagedConnectionFactory is equal to another
194      * ManagedConnectionFactory.
195      *
196      *  @return  true if two instances are equal
197      */
198     public boolean equals(Object   other);
199 }
200
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags