1 /*
2 * JBoss, Home of Professional Open Source.
3 * Copyright 2006, Red Hat Middleware LLC, and individual contributors
4 * as indicated by the @author tags. See the copyright.txt file in the
5 * distribution for a full listing of individual contributors.
6 *
7 * This is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU Lesser General Public License as
9 * published by the Free Software Foundation; either version 2.1 of
10 * the License, or (at your option) any later version.
11 *
12 * This software is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this software; if not, write to the Free
19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21 */
22 package javax.xml.rpc;
23
24 import java.rmi.RemoteException;
25 import java.util.Iterator;
26 import java.util.List;
27 import java.util.Map;
28
29 import javax.xml.namespace.QName;
30
31 /** The javax.xml.rpc.Call interface provides support for the dynamic invocation of a service endpoint.
32 * The javax.xml.rpc.Service interface acts as a factory for the creation of Call instances.
33 *
34 * Once a Call instance is created, various setter and getter methods may be used to configure this Call instance.
35 *
36 * @author Scott.Stark@jboss.org
37 */
38 public interface Call
39 {
40 /** Standard property: User name for authentication Type: java.lang.String */
41 public static final String USERNAME_PROPERTY = "javax.xml.rpc.security.auth.username";
42 /** Standard property: Password for authentication Type: java.lang.String */
43 public static final String PASSWORD_PROPERTY = "javax.xml.rpc.security.auth.password";
44 /** Standard property for operation style. */
45 public static final String OPERATION_STYLE_PROPERTY = "javax.xml.rpc.soap.operation.style";
46 /** Standard property for SOAPAction. */
47 public static final String SOAPACTION_USE_PROPERTY = "javax.xml.rpc.soap.http.soapaction.use";
48 /** Standard property for SOAPAction. */
49 public static final String SOAPACTION_URI_PROPERTY = "javax.xml.rpc.soap.http.soapaction.uri";
50 /** Standard property for encoding Style: Encoding style specified as a namespace URI. */
51 public static final String ENCODINGSTYLE_URI_PROPERTY = "javax.xml.rpc.encodingstyle.namespace.uri";
52 /** Standard property: This boolean property is used by a service client to indicate whether or not it wants to participate in a session with a service endpoint. */
53 public static final String SESSION_MAINTAIN_PROPERTY = "javax.xml.rpc.session.maintain";
54
55 /** Indicates whether addParameter and setReturnType methods are to be invoked to specify the parameter and return
56 * type specification for a specific operation.
57 * @param operationName Qualified name of the operation
58 * @return Returns true if the Call implementation class requires addParameter and setReturnType to be invoked in the client code for the specified operation. This method returns false otherwise.
59 * @throws IllegalArgumentException If invalid operation name is specified
60 */
61 public boolean isParameterAndReturnSpecRequired(QName operationName);
62
63 /** Adds a parameter type and mode for a specific operation.
64 * Note that the client code may not call any addParameter and setReturnType methods before calling the invoke method.
65 * In this case, the Call implementation class determines the parameter types by using reflection on parameters,
66 * using the WSDL description and configured type mapping registry.
67 *
68 * @param paramName Name of the parameter
69 * @param xmlType XML type of the parameter
70 * @param parameterMode Mode of the parameter-whether ParameterMode.IN, ParameterMode.OUT, or ParameterMode.INOUT
71 * @throws JAXRPCException This exception may be thrown if the method isParameterAndReturnSpecRequired returns false for this operation.
72 * @throws IllegalArgumentException If any illegal parameter name or XML type is specified
73 */
74 public void addParameter(String paramName, QName xmlType, ParameterMode parameterMode);
75
76 /** Adds a parameter type and mode for a specific operation.
77 * This method is used to specify the Java type for either OUT or INOUT parameters.
78 *
79 * @param paramName Name of the parameter
80 * @param xmlType XML type of the parameter
81 * @param javaType Java class of the parameter
82 * @param parameterMode Mode of the parameter-whether ParameterMode.IN, ParameterMode.OUT, or ParameterMode.INOUT
83 * @throws JAXRPCException
84 * <ul>
85 * <li>This exception may be thrown if the method isParameterAndReturnSpecRequired returns false for this operation.
86 * <li>If specified XML type and Java type mapping is not valid. For example, TypeMappingRegistry has no serializers for this mapping.
87 * </ul>
88 * @throws IllegalArgumentException If any illegal parameter name or XML type is specified
89 * @throws UnsupportedOperationException If this method is not supported
90 */
91 public void addParameter(String paramName, QName xmlType, Class javaType, ParameterMode parameterMode);
92
93 /** Gets the XML type of a parameter by name.
94 *
95 * @param paramName - Name of the parameter
96 * @return Returns XML type for the specified parameter
97 */
98 public QName getParameterTypeByName(String paramName);
99
100 /** Sets the return type for a specific operation. Invoking setReturnType(null) removes the return type for this Call object.
101 *
102 * @param xmlType XML data type of the return value
103 * @throws JAXRPCException This exception may be thrown when the method isParameterAndReturnSpecRequired returns false.
104 * @throws IllegalArgumentException If an illegal XML type is specified
105 */
106 public void setReturnType(QName xmlType);
107
108 /** Sets the return type for a specific operation.
109 *
110 * @param xmlType XML data type of the return value
111 * @param javaType Java Class of the return value
112 * @throws JAXRPCException
113 * <ul>
114 * <li>This exception may be thrown if this method is invoked when the method isParameterAndReturnSpecRequired returns false.
115 * <li>If XML type and Java type cannot be mapped using the standard type mapping or TypeMapping registry
116 * </ul>
117 * @throws UnsupportedOperationException If this method is not supported
118 * @throws IllegalArgumentException If an illegal XML type is specified
119 */
120 public void setReturnType(QName xmlType, Class javaType);
121
122 /** Gets the return type for a specific operation
123 *
124 * @return Returns the XML type for the return value
125 */
126 public QName getReturnType();
127
128 /** Removes all specified parameters from this Call instance. Note that this method removes only the parameters and
129 * not the return type. The setReturnType(null) is used to remove the return type.
130 * @throws JAXRPCException This exception may be thrown If this method is called when the method isParameterAndReturnSpecRequired returns false for this Call's operation.
131 */
132 public void removeAllParameters();
133
134 /** Gets the name of the operation to be invoked using this Call instance.
135 * @return Qualified name of the operation
136 */
137 public QName getOperationName();
138
139 /** Sets the name of the operation to be invoked using this Call instance.
140 *
141 * @param operationName QName of the operation to be invoked using the Call instance
142 */
143 public void setOperationName(QName operationName);
144
145 /** Gets the qualified name of the port type.
146 * @return Qualified name of the port type
147 */
148 public QName getPortTypeName();
149
150 /** Sets the qualified name of the port type.
151 *
152 * @param portType - Qualified name of the port type
153 */
154 public void setPortTypeName(QName portType);
155
156 /** Sets the address of the target service endpoint. This address must correspond to the transport
157 * specified in the binding for this Call instance.
158 *
159 * @param address Address of the target service endpoint; specified as an URI
160 */
161 public void setTargetEndpointAddress(String address);
162
163 /** Gets the address of a target service endpoint.
164 * @return Address of the target service endpoint as an URI
165 */
166 public String getTargetEndpointAddress();
167
168 /** Sets the value for a named property.
169 * JAX-RPC specification specifies a standard set of properties that may be passed to the Call.setProperty method.
170 *
171 * @param name Name of the property
172 * @param value Value of the property
173 * @throws JAXRPCException
174 * <ul>
175 * <li> If an optional standard property name is specified, however this Call implementation class does not support the configuration of this property.
176 * <li> If an invalid (or unsupported) property name is specified or if a value of mismatched property type is passed.
177 * <li> If there is any error in the configuration of a valid property.
178 * </ul>
179 */
180 public void setProperty(String name, Object value);
181
182 /** Gets the value of a named property.
183 *
184 * @param name Name of the property
185 * @return Value of the named property
186 * @throws JAXRPCException if an invalid or unsupported property name is passed.
187 */
188 public Object getProperty(String name);
189
190 /** Removes a named property.
191 * @param name Name of the property
192 * @throws JAXRPCException if an invalid or unsupported property name is passed.
193 */
194 public void removeProperty(String name);
195
196 /** Gets the names of configurable properties supported by this Call object.
197 * @return Iterator for the property names
198 */
199 public Iterator getPropertyNames();
200
201 /** Invokes a specific operation using a synchronous request-response interaction mode.
202 *
203 * @param inputParams Object[]--Parameters for this invocation. This includes only the input params
204 * @return Returns the return value or null
205 * @throws RemoteException if there is any error in the remote method invocation
206 * @throws javax.xml.rpc.soap.SOAPFaultException Indicates a SOAP fault
207 * @throws JAXRPCException
208 * <ul>
209 * <li>If there is an error in the configuration of the Call object
210 * <li> If inputParams do not match the required parameter set (as specified through the addParameter invocations or in the corresponding WSDL)
211 * <li> If parameters and return type are incorrectly specified
212 * </ul>
213 */
214 public Object invoke(Object[] inputParams) throws RemoteException;
215
216 /** Invokes a specific operation using a synchronous request-response interaction mode.
217 *
218 * @param operationName QName of the operation
219 * @param inputParams Object[]--Parameters for this invocation. This includes only the input params.
220 * @return Return value or null
221 * @throws RemoteException if there is any error in the remote method invocation.
222 * @throws javax.xml.rpc.soap.SOAPFaultException - Indicates a SOAP fault
223 * @throws JAXRPCException
224 * <ul>
225 * <li> If there is an error in the configuration of the Call object
226 * <li> If inputParams do not match the required parameter set (as specified through the addParameter invocations or in the corresponding WSDL)
227 * <li> If parameters and return type are incorrectly specified
228 * </ul>
229 */
230 public Object invoke(QName operationName, Object[] inputParams) throws RemoteException;
231
232 /** Invokes a remote method using the one-way interaction mode.
233 * The client thread does not normally block waiting for the completion of the server processing for this
234 * remote method invocation. When the protocol in use is SOAP/HTTP, this method should block until an HTTP response
235 * code has been received or an error occurs. This method must not throw any remote exceptions.
236 * This method may throw a JAXRPCException during the processing of the one-way remote call.
237 *
238 * @param inputParams Object[]--Parameters for this invocation. This includes only the input params.
239 * @throws JAXRPCException if there is an error in the configuration of the Call object
240 * (example: a non-void return type has been incorrectly specified for the one-way call) or
241 * if there is any error during the invocation of the one-way remote call
242 */
243 public void invokeOneWay(Object[] inputParams);
244
245 /** Returns a Map of {name, value} for the output parameters of the last invoked operation.
246 * The parameter names in the returned Map are of type java.lang.String.
247 *
248 * @return Map Output parameters for the last Call.invoke(). Empty Map is returned if there are no output parameters.
249 * @throws JAXRPCException If this method is invoked for a one-way operation or is invoked before any invoke method has been called.
250 */
251 public Map getOutputParams();
252
253 /** Returns a List values for the output parameters of the last invoked operation.
254 *
255 * @return java.util.List Values for the output parameters. An empty List is returned if there are no output values.
256 * @throws JAXRPCException If this method is invoked for a one-way operation or is invoked before any invoke method has been called.
257 */
258 public List getOutputValues();
259 }