KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > resource > spi > 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 JavaDoc;
27 import java.util.Set JavaDoc;
28 import javax.resource.ResourceException JavaDoc;
29 import javax.resource.NotSupportedException JavaDoc;
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 JavaDoc {
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 JavaDoc createConnectionFactory(ConnectionManager JavaDoc cxManager)
62     throws ResourceException JavaDoc;
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 JavaDoc createConnectionFactory() throws ResourceException JavaDoc;
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 JavaDoc createManagedConnection(
104                   Subject JavaDoc subject,
105                   ConnectionRequestInfo JavaDoc cxRequestInfo)
106     throws ResourceException JavaDoc;
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 JavaDoc matchManagedConnections(
136                       Set JavaDoc connectionSet,
137                       Subject JavaDoc subject,
138                       ConnectionRequestInfo JavaDoc cxRequestInfo)
139     throws ResourceException JavaDoc;
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 JavaDoc out) throws ResourceException JavaDoc;
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 JavaDoc getLogWriter() throws ResourceException JavaDoc;
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 JavaDoc other);
199 }
200
Popular Tags