KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > resource > cci > Interaction


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 import javax.resource.ResourceException JavaDoc;
27 import javax.resource.NotSupportedException JavaDoc;
28
29
30 /** The <code>javax.resource.cci.Interaction</code> enables a component to
31  * execute EIS functions. An Interaction instance supports the following ways
32  * of interacting with an EIS instance:
33  * <UL>
34  * <LI><code>execute</code> method that takes an input Record, output
35  * Record and an InteractionSpec. This method executes the EIS
36  * function represented by the InteractionSpec and updates the
37  * output Record
38  * <LI><code>execute</code> method that takes an input Record and an
39  * InteractionSpec. This method implementation executes the EIS
40  * function represented by the InteractionSpec and produces the
41  * output Record as a return value.
42  * </UL>
43  * <p>An Interaction instance is created from a Connection and is required
44  * to maintain its association with the Connection instance. The close method
45  * releases all resources maintained by the resource adapter for the
46  * Interaction. The close of an Interaction instance should not close the
47  * associated Connection instance.
48  *
49  * @author Rahul Sharma
50  * @version 0.8
51  * @since 0.8
52  * @see java.sql.ResultSet
53 **/

54
55 public interface Interaction {
56   
57   /** Closes the current Interaction and release all the resources
58    * held for this instance by the resource adapter. The close of an
59    * Interaction instance does not close the associated Connection
60    * instance. It is recommended that Interaction instances be
61    * closed explicitly to free any held resources.
62    *
63    * @throws ResourceException Failed to close the Interaction
64    * instance. Invoking close on an
65    * already closed Interaction should
66    * also throw this exception.
67   **/

68   public
69   void close() throws ResourceException JavaDoc;
70
71
72   /** Gets the Connection associated with the Interaction.
73    *
74    * @return Connection instance associated with the Interaction
75   **/

76   public
77   Connection JavaDoc getConnection();
78
79   /** Executes an interaction represented by the InteractionSpec.
80    * This form of invocation takes an input Record and updates
81    * the output Record.
82    *
83    * @param ispec InteractionSpec representing a target EIS
84    * data/function module
85    * @param input Input Record
86    * @param output Output Record
87    *
88    * @return true if execution of the EIS function has been
89    * successful and output Record has been updated; false
90    * otherwise
91    *
92    * @throws ResourceException Exception if execute operation
93    * fails. Examples of error cases
94    * are:
95    * <UL>
96    * <LI> Resource adapter internal, EIS-specific or
97    * communication error
98    * <LI> Invalid specification of an InteractionSpec,
99    * input or output record structure
100    * <LI> Errors in use of input or output Record
101    * <LI> Invalid connection associated with this
102    * Interaction
103    * </UL>
104    * @throws NotSupportedException Operation not supported
105    *
106   **/

107   public
108   boolean execute(InteractionSpec JavaDoc ispec,
109           Record JavaDoc input,
110           Record JavaDoc output) throws ResourceException JavaDoc;
111
112   /** Executes an interaction represented by the InteractionSpec.
113    * This form of invocation takes an input Record and returns an
114    * output Record if the execution of the Interaction has been
115    * successfull.
116    *
117    * @param ispec InteractionSpec representing a target EIS
118    * data/function module
119    * @param input Input Record
120
121    * @return output Record if execution of the EIS function has been
122    * successful; null otherwise
123    *
124    * @throws ResourceException Exception if execute operation
125    * fails. Examples of error cases
126    * are:
127    * <UL>
128    * <LI> Resource adapter internal, EIS-specific or
129    * communication error
130    * <LI> Invalid specification of an InteractionSpec
131    * or input record structure
132    * <LI> Errors in use of input Record or creation
133    * of an output Record
134    * <LI> Invalid connection associated with this
135    * Interaction
136    * </UL>
137    * @throws NotSupportedException Operation not supported
138   **/

139   public
140   Record JavaDoc execute(InteractionSpec JavaDoc ispec,
141          Record JavaDoc input) throws ResourceException JavaDoc;
142
143   /** Gets the first ResourceWarning from the chain of warnings
144    * associated with this Interaction instance.
145    *
146    * @return ResourceWarning at top of the warning chain
147    * @throws ResourceException Failed to get ResourceWarnings
148    * associated with Interaction
149    **/

150   public
151   ResourceWarning JavaDoc getWarnings() throws ResourceException JavaDoc;
152
153   /** Clears all the warning reported by this Interaction instance. After
154    * a call to this method, the method getWarnings will return null
155    * until a new warning is reported for this Interaction.
156    *
157    * @throws ResourceException Failed to clear ResourceWarnings
158    * associated with Interaction
159  **/

160   public
161   void clearWarnings() throws ResourceException JavaDoc;
162
163 }
164
Popular Tags