Java > Open Source Codes > javax > xml > rpc > Call


1 /*
2  * Copyright 2001-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package javax.xml.rpc;
17
18 import javax.xml.namespace.QName ;
19 import java.util.Iterator ;
20 import java.util.List ;
21 import java.util.Map ;
22
23 /**
24  * The <code>javax.xml.rpc.Call</code> interface provides support
25  * for the dynamic invocation of a service endpoint. The
26  * <code>javax.xml.rpc.Service</code> interface acts as a factory
27  * for the creation of <code>Call</code> instances.
28  * <p>
29  * Once a <code>Call</code> instance is created, various setter
30  * and getter methods may be used to configure this <code>Call</code>
31  * instance.
32  *
33  * @version 1.0
34  */
35 public interface Call {
36
37     /**
38      * Standard property: User name for authentication
39      * <p>Type: <code>java.lang.String
40      */
41     public static final String USERNAME_PROPERTY =
42         "javax.xml.rpc.security.auth.username";
43
44     /**
45      * Standard property: Password for authentication
46      * <p>Type: <code>java.lang.String</code>
47      */
48     public static final String PASSWORD_PROPERTY =
49         "javax.xml.rpc.security.auth.password";
50
51     /**
52      * Standard property for operation style. This property is
53      * set to "rpc" if the operation style is rpc; "document"
54      * if the operation style is document.
55      * <p>Type: <code>java.lang.String</code>
56      */
57     public static final String OPERATION_STYLE_PROPERTY =
58         "javax.xml.rpc.soap.operation.style";
59
60     /**
61      * Standard property for SOAPAction. This boolean property
62      * indicates whether or not SOAPAction is to be used. The
63      * default value of this property is false indicating that
64      * the SOAPAction is not used.
65      * <p>Type: <code>java.lang.Boolean</code>
66      */
67     public static final String SOAPACTION_USE_PROPERTY =
68         "javax.xml.rpc.soap.http.soapaction.use";
69
70     /**
71      * Standard property for SOAPAction. Indicates the SOAPAction
72      * URI if the <code>javax.xml.rpc.soap.http.soapaction.use</code>
73      * property is set to <code>true</code>.
74      * <p>Type: <code>java.lang.String</code>
75      */
76     public static final String SOAPACTION_URI_PROPERTY =
77         "javax.xml.rpc.soap.http.soapaction.uri";
78
79     /**
80      * Standard property for encoding Style: Encoding style specified
81      * as a namespace URI. The default value is the SOAP 1.1 encoding
82      * <code>http://schemas.xmlsoap.org/soap/encoding/</code>
83      * <p>Type: <code>java.lang.String</code>
84      */
85     public static final String ENCODINGSTYLE_URI_PROPERTY =
86         "javax.xml.rpc.encodingstyle.namespace.uri";
87
88     /**
89      * Standard property: This boolean property is used by a service
90      * client to indicate whether or not it wants to participate in
91      * a session with a service endpoint. If this property is set to
92      * true, the service client indicates that it wants the session
93      * to be maintained. If set to false, the session is not maintained.
94      * The default value for this property is <code>false</code>.
95      * <p>Type: <code>java.lang.Boolean</code>
96      */
97     public static final String SESSION_MAINTAIN_PROPERTY =
98         "javax.xml.rpc.session.maintain";
99
100     /**
101      * Indicates whether <code>addParameter</code> and
102      * <code>setReturnType</code> methods
103      * are to be invoked to specify the parameter and return type
104      * specification for a specific operation.
105      *
106      * @param operationName Qualified name of the operation
107      *
108      * @return Returns true if the Call implementation class
109      * requires addParameter and setReturnType to be
110      * invoked in the client code for the specified
111      * operation. This method returns false otherwise.
112      */
113     public boolean isParameterAndReturnSpecRequired(QName operationName);
114
115     /**
116      * Adds a parameter type and mode for a specific operation.
117      * Note that the client code may not call any
118      * <code>addParameter</code> and <code>setReturnType</code>
119      * methods before calling the <code>invoke</code> method. In
120      * this case, the Call implementation class determines the
121      * parameter types by using reflection on parameters, using
122      * the WSDL description and configured type mapping registry.
123      *
124      * @param paramName Name of the parameter
125      * @param xmlType XML datatype of the parameter
126      * @param parameterMode Mode of the parameter-whether
127      * <code>ParameterMode.IN</code>,
128      * <code>ParameterMode.OUT</code>,
129      * or <code>ParameterMode.INOUT
130      * @throws JAXRPCException This exception may
131      * be thrown if the method <code>isParameterAndReturnSpecRequired</code>
132      * returns <code>false</code> for this operation.
133      * @throws java.lang.IllegalArgumentException If any illegal
134      * parameter name or XML type is specified
135      */
136     public void addParameter(String paramName, QName xmlType,
137                              ParameterMode parameterMode);
138
139     /**
140      * Adds a parameter type and mode for a specific operation.
141      * This method is used to specify the Java type for either
142      * OUT or INOUT parameters.
143      *
144      * @param paramName Name of the parameter
145      * @param xmlType XML datatype of the parameter
146      * @param javaType The Java class of the parameter
147      * @param parameterMode Mode of the parameter-whether
148      * ParameterMode.IN, OUT or INOUT
149      * @throws JAXRPCException <ul>
150      *
151      * <li>This exception may be thrown if this method is
152      * invoked when the method <code>isParameterAndReturnSpecRequired</code>
153      * returns <code>false</code>.
154      * <li>If specified XML type and Java type mapping
155      * is not valid. For example, <code>TypeMappingRegistry</code>
156      * has no serializers for this mapping.
157      * </ul>
158      * @throws java.lang.IllegalArgumentException If any illegal
159      * parameter name or XML type is specified
160      * @throws java.lang.UnsupportedOperationException If this
161      * method is not supported
162      */
163     public void addParameter(String paramName, QName xmlType, Class javaType,
164                              ParameterMode parameterMode);
165
166     /**
167      * Gets the XML type of a parameter by name.
168      *
169      * @param paramName name of the parameter
170      *
171      * @return Returns XML type for the specified parameter
172      */
173     public QName getParameterTypeByName(String paramName);
174
175     /**
176      * Sets the return type for a specific operation. Invoking
177      * <code>setReturnType(null)</code> removes the return
178      * type for this Call object.
179      *
180      * @param xmlType XML data type of the return value
181      * @throws JAXRPCException This exception
182      * may be thrown when the method
183      * <code>isParameterAndReturnSpecRequired</code> returns
184      * <code>false</code>.
185      * @throws java.lang.IllegalArgumentException If an illegal
186      * XML type is specified
187      */
188     public void setReturnType(QName xmlType);
189
190     /**
191      * Sets the return type for a specific operation.
192      *
193      * @param xmlType XML data type of the return value
194      * @param javaType Java class of the return value
195      * @throws JAXRPCException <ul>
196      * <li>This exception may be thrown if this method is
197      * invoked when the method <code>isParameterAndReturnSpecRequired</code>
198      * returns <code>false</code>.
199      * <li>If XML type and Java type cannot be mapped
200      * using the standard type mapping or TypeMapping
201      * registry
202      * </ul>
203      * @throws java.lang.UnsupportedOperationException If this
204      * method is not supported
205      * @throws java.lang.IllegalArgumentException If an illegal
206      * XML type is specified
207      */
208     public void setReturnType(QName xmlType, Class javaType);
209
210     /**
211      * Gets the return type for a specific operation.
212      *
213      * @return the XML type for the return value
214      */
215     public QName getReturnType();
216
217     /**
218      * Removes all specified parameters from this <code>Call</code> instance.
219      * Note that this method removes only the parameters and not
220      * the return type. The <code>setReturnType(null)</code> is
221      * used to remove the return type.
222      *
223      * @throws JAXRPCException This exception may be
224      * thrown If this method is called when the method
225      * <code>isParameterAndReturnSpecRequired</code>
226      * returns <code>false</code> for this Call's operation.
227      */
228     public void removeAllParameters();
229
230     /**
231      * Gets the name of the operation to be invoked using this Call instance.
232      *
233      * @return Qualified name of the operation
234      */
235     public QName getOperationName();
236
237     /**
238      * Sets the name of the operation to be invoked using this
239      * <code>Call</code> instance.
240      *
241      * @param operationName QName of the operation to be
242      * invoked using the Call instance
243      */
244     public void setOperationName(QName operationName);
245
246     /**
247      * Gets the qualified name of the port type.
248      *
249      * @return Qualified name of the port type
250      */
251     public QName getPortTypeName();
252
253     /**
254      * Sets the qualified name of the port type.
255      *
256      * @param portType Qualified name of the port type
257      */
258     public void setPortTypeName(QName portType);
259
260     /**
261      * Sets the address of the target service endpoint.
262      * This address must correspond to the transport specified
263      * in the binding for this <code>Call</code> instance.
264      *
265      * @param address Address of the target service endpoint;
266      * specified as an URI
267      */
268     public void setTargetEndpointAddress(String address);
269
270     /**
271      * Gets the address of a target service endpoint.
272      *
273      * @return Endpoint address of the target service port as an URI
274      */
275     public String getTargetEndpointAddress();
276
277     /**
278      * Sets the value for a named property. JAX-RPC specification
279      * specifies a standard set of properties that may be passed
280      * to the <code>Call.setProperty</code> method.
281      *
282      * @param name Name of the property
283      * @param value Value of the property
284      * @throws JAXRPCException <ul>
285      * <li>If an optional standard property name is
286      * specified, however this <code>Call</code> implementation
287      * class does not support the configuration of
288      * this property.
289      * <li>If an invalid (or unsupported) property name is
290      * specified or if a value of mismatched property
291      * type is passed.
292      * <li>If there is any error in the configuration of
293      * a valid property.
294      * </ul>
295      */
296     public void setProperty(String name, Object value);
297
298     /**
299      * Gets the value of a named property.
300      *
301      * @param name Name of the property
302      *
303      * @return Value of the named property
304      * @throws JAXRPCException if an invalid or
305      * unsupported property name is passed.
306      */
307     public Object getProperty(String name);
308
309     /**
310      * Removes a named property.
311      *
312      * @param name Name of the property
313      * @throws JAXRPCException if an invalid or
314      * unsupported property name is passed.
315      */
316     public void removeProperty(String name);
317
318     /**
319      * Gets the names of configurable properties supported by
320      * this <code>Call</code> object.
321      *
322      * @return Iterator for the property names
323      */
324     public Iterator getPropertyNames();
325
326     // Remote Method Invocation methods
327
328     /**
329      * Invokes a specific operation using a synchronous request-response
330      * interaction mode.
331      *
332      * @param inputParams Object[]--Parameters for this invocation. This
333      * includes only the input params
334      *
335      * @return Returns the return value or <code>null</code>
336      *
337      * @throws java.rmi.RemoteException if there is any error in the remote
338      * method invocation or if the Call
339      * object is not configured properly.
340      * @throws javax.xml.rpc.soap.SOAPFaultException Indicates a SOAP fault
341      * @throws JAXRPCException <ul>
342      *
343      * <li>If there is an error in the configuration of the
344      * <code>Call</code> object
345      * <li>If <code>inputParams</code> do not match the required parameter
346      * set (as specified through the <code>addParameter</code>
347      * invocations or in the corresponding WSDL)
348      * <li>If parameters and return type are incorrectly
349      * specified
350      * </ul>
351      */
352     public Object invoke(Object [] inputParams) throws java.rmi.RemoteException ;
353
354     /**
355      * Invokes a specific operation using a synchronous request-response
356      * interaction mode.
357      *
358      * @param operationName QName of the operation
359      * @param inputParams Object[]--Parameters for this invocation. This
360      * includes only the input params.
361      *
362      * @return Return value or null
363      *
364      * @throws java.rmi.RemoteException if there is any error in the
365      * remote method invocation.
366      * @throws javax.xml.rpc.soap.SOAPFaultException Indicates a SOAP fault
367      * @throws JAXRPCException <ul>
368      * <li>If there is an error in the configuration of the
369      * <code>Cal</code>l object
370      * <li>If <code>inputParam</code>s do not match the required parameter
371      * set (as specified through the <code>addParameter</code>
372      * invocations or in the corresponding WSDL)
373      * <li>If parameters and return type are incorrectly
374      * specified
375      * </ul>
376      */
377     public Object invoke(QName operationName, Object [] inputParams)
378         throws java.rmi.RemoteException ;
379
380     /**
381      * Invokes a remote method using the one-way interaction mode. The
382      * client thread does not block waiting for the completion of the
383      * server processing for this remote method invocation. This method
384      * must not throw any remote exceptions. This method may throw a
385      * <code>JAXRPCException</code> during the processing of the one-way
386      * remote call.
387      *
388      * @param params Object[]--Parameters for this invocation. This
389      * includes only the input params.
390      *
391      * @throws JAXRPCException if there is an error in the
392      * configuration of the <code>Call</code> object (example: a
393      * non-void return type has been incorrectly specified for the
394      * one-way call) or if there is any error during the
395      * invocation of the one-way remote call
396      */
397     public void invokeOneWay(Object [] params);
398
399     /**
400      * Returns a <code>Map</code> of {name, value} for the output parameters of
401      * the last invoked operation. The parameter names in the
402      * returned Map are of type <code>java.lang.String</code>.
403      *
404      * @return Map Output parameters for the last <code>Call.invoke()</code>.
405      * Empty <code>Map</code> is returned if there are no output
406      * parameters.
407      * @throws javax.xml.rpc.JAXRPCException If this method is invoked for a
408      * one-way operation or is invoked before any
409      * <code>invoke</code> method has been called.
410      */
411     public Map getOutputParams();
412
413     /**
414      * Returns a <code>List</code> values for the output parameters
415      * of the last invoked operation.
416      *
417      * @return java.util.List Values for the output parameters. An
418      * empty <code>List</code> is returned if there are
419      * no output values.
420      *
421      * @throws JAXRPCException If this method is invoked for a
422      * one-way operation or is invoked before any
423      * <code>invoke</code> method has been called.
424      */
425     public List getOutputValues();
426 }
427
428

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags