ConnectionFactory


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.cci;
25  
26  
27  import java.io.PrintWriter  ;
28  import javax.resource.ResourceException  ;
29  import javax.resource.NotSupportedException  ;
30  
31  
32  /** <code>ConnectionFactory</code> provides an interface for getting
33   *  connection to an EIS instance. An implementation of ConnectionFactory
34   *  interface is provided by a resource adapter.
35   *
36   *  <p>Application code looks up a ConnectionFactory instance from JNDI
37   *  namespace and uses it to get EIS connections. 
38   *
39   *  <p>An implementation class for ConnectionFactory is required to 
40   *  implement <code>java.io.Serializable</code> and 
41   *  <code>javax.resource.Referenceable</code>interfaces to support 
42   *  JNDI registration.
43   *  
44   *  @author  Rahul Sharma
45   *  @version 0.8
46   *  @see     javax.resource.cci.Connection
47   *  @see     javax.resource.Referenceable
48   **/
49  public interface ConnectionFactory 
50                      extends java.io.Serializable  , 
51                              javax.resource.Referenceable   {
52    
53    /** Gets a connection to an EIS instance. This getConnection variant
54     *  should be used when a component wants the container to manage EIS 
55     *  sign-on. This case is termed container-managed sign-on. The 
56     *  component does not pass any security information.
57     *
58     *
59     *  @return   Connection instance
60     *  @throws   ResourceException   Failed to get a connection to
61     *                                the EIS instance. Examples of
62     *                                error cases are:
63     *          <UL>
64     *          <LI> Invalid configuration of ManagedConnectionFactory--
65     *               example: invalid server name
66     *          <LI> Application server-internal error--example:
67     *               connection pool related error
68     *          <LI> Communication error 
69     *          <LI> EIS-specific error--example: EIS not active
70     *          <LI> Resource adapter-internal error
71     *          <LI> Security related error; example: invalid user
72     *          <LI> Failure to allocate system resources
73     *         </UL>                        
74    **/
75    public 
76    Connection   getConnection() throws ResourceException  ;
77  
78    /** Gets a connection to an EIS instance. A component should use 
79     *  the getConnection variant with javax.resource.cci.ConnectionSpec
80     *  parameter, if it needs to pass any resource adapter specific 
81     *  security information and connection parameters. In the component-
82     *  managed sign-on case, an application component passes security 
83     *  information (example: username, password) through the 
84     *  ConnectionSpec instance.
85     * 
86     *  <p>It is important to note that the properties passed through 
87     *  the getConnection method should be client-specific (example: 
88     *  username, password, language) and not related to the 
89     *  configuration of a target EIS instance (example: port number, 
90     *  server name). The ManagedConnectionFactory instance is configured
91     *  with complete set of properties required for the creation of a 
92     *  connection to an EIS instance. 
93     *
94     *  @param  properties          Connection parameters and security
95     *                              information specified as 
96     *                              ConnectionSpec instance
97     *  @return Connection instance
98     *
99     *  @throws ResourceException   Failed to get a connection to
100    *                              the EIS instance. Examples of
101    *                              error cases are:
102    *          <UL>
103    *          <LI> Invalid specification of input parameters
104    *          <LI> Invalid configuration of ManagedConnectionFactory--
105    *               example: invalid server name
106    *          <LI> Application server-internal error--example:
107    *               connection pool related error
108    *          <LI> Communication error 
109    *          <LI> EIS-specific error--example: EIS not active
110    *          <LI> Resource adapter-internal error
111    *          <LI> Security related error; example: invalid user
112    *          <LI> Failure to allocate system resources
113    *         </UL>                        
114    *  @see     javax.resource.cci.ConnectionSpec
115   **/
116   public 
117   Connection   getConnection(ConnectionSpec   properties) 
118                        throws ResourceException  ;
119 
120   /** Gets a RecordFactory instance. The RecordFactory is used for
121    *  the creation of generic Record instances.
122    *
123    *  @return RecordFactory         RecordFactory instance
124    *
125    *  @throws ResourceException     Failed to create a RecordFactory
126    *  @throws NotSupportedException Operation not supported
127   **/
128   public
129   RecordFactory   getRecordFactory() throws ResourceException  ;
130 
131   /** Gets metadata for the Resource Adapter. Note that the metadata
132    *  information is about the ResourceAdapter and not the EIS instance.
133    *  An invocation of this method does not require that an active
134    *  connection to an EIS instance should have been established.
135    *
136    *  @return  ResourceAdapterMetaData instance
137    *  @throws   ResourceException Failed to get metadata information 
138    *                              about the resource adapter
139   **/
140   public
141   ResourceAdapterMetaData   getMetaData() throws ResourceException  ;
142 
143 }
144
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags