1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can obtain
10 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
11 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
12 * language governing permissions and limitations under the License.
13 *
14 * When distributing the software, include this License Header Notice in each
15 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
16 * Sun designates this particular file as subject to the "Classpath" exception
17 * as provided by Sun in the GPL Version 2 section of the License file that
18 * accompanied this code. If applicable, add the following below the License
19 * Header, with the fields enclosed by brackets [] replaced by your own
20 * identifying information: "Portions Copyrighted [year]
21 * [name of copyright owner]"
22 *
23 * Contributor(s):
24 *
25 * If you wish your version of this file to be governed by only the CDDL or
26 * only the GPL Version 2, indicate your decision by adding "[Contributor]
27 * elects to include this software in this distribution under the [CDDL or GPL
28 * Version 2] license." If you don't indicate a single choice of license, a
29 * recipient has the option to distribute your version of this file under
30 * either the CDDL, the GPL Version 2 or to extend the choice of license to
31 * its licensees as provided above. However, if you add GPL Version 2 code
32 * and therefore, elected the GPL Version 2 license, then the option applies
33 * only if the new code is made subject to such option by the copyright
34 * holder.
35 */
36
37 package javax.resource.spi;
38
39 import javax.security.auth.Subject;
40 import java.util.Set;
41 import javax.resource.ResourceException;
42 import javax.resource.NotSupportedException;
43
44 /**
45 * ManagedConnectionFactory instance is a factory of both ManagedConnection
46 * and EIS-specific connection factory instances. This interface supports
47 * connection pooling by providing methods for matching and creation of
48 * ManagedConnection instance. A ManagedConnectionFactory
49 * instance is required to be a JavaBean.
50 *
51 * @version 0.6
52 * @author Rahul Sharma
53 *
54 * @see javax.resource.spi.ManagedConnection
55 */
56
57 public interface ManagedConnectionFactory extends java.io.Serializable {
58
59 /**
60 * Creates a Connection Factory instance. The Connection Factory
61 * instance gets initialized with the passed ConnectionManager. In
62 * the managed scenario, ConnectionManager is provided by the
63 * application server.
64 *
65 * @param cxManager ConnectionManager to be associated with
66 * created EIS connection factory instance
67 * @return EIS-specific Connection Factory instance or
68 * javax.resource.cci.ConnectionFactory instance
69 *
70 * @throws ResourceException Generic exception
71 * @throws ResourceAdapterInternalException
72 * Resource adapter related error condition
73 */
74 public Object createConnectionFactory(ConnectionManager cxManager)
75 throws ResourceException;
76
77 /**
78 * Creates a Connection Factory instance. The Connection Factory
79 * instance gets initialized with a default ConnectionManager provided
80 * by the resource adapter.
81 *
82 * @return EIS-specific Connection Factory instance or
83 * javax.resource.cci.ConnectionFactory instance
84 *
85 * @throws ResourceException Generic exception
86 * @throws ResourceAdapterInternalException
87 * Resource adapter related error condition
88 */
89 public Object createConnectionFactory() throws ResourceException;
90
91
92 /**
93 * Creates a new physical connection to the underlying EIS
94 * resource manager.
95 *
96 * <p>ManagedConnectionFactory uses the security information (passed as
97 * Subject) and additional ConnectionRequestInfo (which is specific to
98 * ResourceAdapter and opaque to application server) to create this new
99 * connection.
100 *
101 * @param subject Caller's security information
102 * @param cxRequestInfo Additional resource adapter specific connection
103 * request information
104 *
105 * @throws ResourceException generic exception
106 * @throws SecurityException security related error
107 * @throws ResourceAllocationException
108 * failed to allocate system resources for
109 * connection request
110 * @throws ResourceAdapterInternalException
111 * resource adapter related error condition
112 * @throws EISSystemException internal error condition in EIS instance
113 *
114 * @return ManagedConnection instance
115 */
116 public ManagedConnection createManagedConnection(
117 Subject subject,
118 ConnectionRequestInfo cxRequestInfo)
119 throws ResourceException;
120
121 /**
122 * Returns a matched connection from the candidate set of connections.
123 *
124 *
125 * <p>ManagedConnectionFactory uses the security info (as in Subject)
126 * and information provided through ConnectionRequestInfo and additional
127 * Resource Adapter specific criteria to do matching. Note that criteria
128 * used for matching is specific to a resource adapter and is not
129 * prescribed by the Connector specification.</p>
130 *
131 * <p>This method returns a ManagedConnection instance that is the best
132 * match for handling the connection allocation request.</p>
133 *
134 * @param connectionSet candidate connection set
135 * @param subject caller's security information
136 * @param cxRequestInfo additional resource adapter specific
137 * connection request information
138 *
139 * @throws ResourceException generic exception
140 * @throws SecurityException security related error
141 * @throws ResourceAdapterInternalException
142 * resource adapter related error condition
143 * @throws NotSupportedException if operation is not supported
144 *
145 * @return ManagedConnection if resource adapter finds an
146 * acceptable match otherwise null
147 **/
148 public ManagedConnection matchManagedConnections(
149 Set connectionSet,
150 Subject subject,
151 ConnectionRequestInfo cxRequestInfo)
152 throws ResourceException;
153
154 /**
155 * Set the log writer for this ManagedConnectionFactory instance.</p>
156 *
157 * <p>The log writer is a character output stream to which all logging and
158 * tracing messages for this ManagedConnectionfactory instance will be
159 * printed.</p>
160 *
161 * <p>ApplicationServer manages the association of output stream with the
162 * ManagedConnectionFactory. When a ManagedConnectionFactory object is
163 * created the log writer is initially null, in other words, logging is
164 * disabled. Once a log writer is associated with a
165 * ManagedConnectionFactory, logging and tracing for
166 * ManagedConnectionFactory instance is enabled.
167 *
168 * <p>The ManagedConnection instances created by ManagedConnectionFactory
169 * "inherits" the log writer, which can be overridden by ApplicationServer
170 * using ManagedConnection.setLogWriter to set ManagedConnection specific
171 * logging and tracing.
172 *
173 * @param out PrintWriter - an out stream for
174 * error logging and tracing
175 * @throws ResourceException generic exception
176 * @throws ResourceAdapterInternalException
177 * resource adapter related error condition
178 */
179 public void setLogWriter(java.io.PrintWriter out) throws ResourceException;
180
181 /**
182 * Get the log writer for this ManagedConnectionFactory instance.
183 *
184 * <p>The log writer is a character output stream to which all logging and
185 * tracing messages for this ManagedConnectionFactory instance will be
186 * printed
187 *
188 * <p>ApplicationServer manages the association of output stream with the
189 * ManagedConnectionFactory. When a ManagedConnectionFactory object is
190 * created the log writer is initially null, in other words, logging is
191 * disabled.
192 *
193 * @return PrintWriter
194 * @throws ResourceException generic exception
195 */
196 public java.io.PrintWriter getLogWriter() throws ResourceException;
197
198 /**
199 * Returns the hash code for the ManagedConnectionFactory
200 *
201 * @return hash code for the ManagedConnectionFactory
202 */
203 public int hashCode();
204
205 /**
206 * Check if this ManagedConnectionFactory is equal to another
207 * ManagedConnectionFactory.
208 *
209 * @return true if two instances are equal
210 */
211 public boolean equals(Object other);
212 }
Save This Page