001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020 package javax.xml.rpc;
021
022 import javax.xml.namespace.QName;
023 import java.util.Iterator;
024 import java.util.List;
025 import java.util.Map;
026
027 /**
028 * The <code>javax.xml.rpc.Call</code> interface provides support
029 * for the dynamic invocation of a service endpoint. The
030 * <code>javax.xml.rpc.Service</code> interface acts as a factory
031 * for the creation of <code>Call</code> instances.
032 * <p>
033 * Once a <code>Call</code> instance is created, various setter
034 * and getter methods may be used to configure this <code>Call</code>
035 * instance.
036 *
037 * @version $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $
038 */
039 public interface Call {
040
041 /**
042 * Standard property: User name for authentication
043 * <p>Type: <code>java.lang.String
044 */
045 public static final String USERNAME_PROPERTY =
046 "javax.xml.rpc.security.auth.username";
047
048 /**
049 * Standard property: Password for authentication
050 * <p>Type: <code>java.lang.String</code>
051 */
052 public static final String PASSWORD_PROPERTY =
053 "javax.xml.rpc.security.auth.password";
054
055 /**
056 * Standard property for operation style. This property is
057 * set to "rpc" if the operation style is rpc; "document"
058 * if the operation style is document.
059 * <p>Type: <code>java.lang.String</code>
060 */
061 public static final String OPERATION_STYLE_PROPERTY =
062 "javax.xml.rpc.soap.operation.style";
063
064 /**
065 * Standard property for SOAPAction. This boolean property
066 * indicates whether or not SOAPAction is to be used. The
067 * default value of this property is false indicating that
068 * the SOAPAction is not used.
069 * <p>Type: <code>java.lang.Boolean</code>
070 */
071 public static final String SOAPACTION_USE_PROPERTY =
072 "javax.xml.rpc.soap.http.soapaction.use";
073
074 /**
075 * Standard property for SOAPAction. Indicates the SOAPAction
076 * URI if the <code>javax.xml.rpc.soap.http.soapaction.use</code>
077 * property is set to <code>true</code>.
078 * <p>Type: <code>java.lang.String</code>
079 */
080 public static final String SOAPACTION_URI_PROPERTY =
081 "javax.xml.rpc.soap.http.soapaction.uri";
082
083 /**
084 * Standard property for encoding Style: Encoding style specified
085 * as a namespace URI. The default value is the SOAP 1.1 encoding
086 * <code>http://schemas.xmlsoap.org/soap/encoding/</code>
087 * <p>Type: <code>java.lang.String</code>
088 */
089 public static final String ENCODINGSTYLE_URI_PROPERTY =
090 "javax.xml.rpc.encodingstyle.namespace.uri";
091
092 /**
093 * Standard property: This boolean property is used by a service
094 * client to indicate whether or not it wants to participate in
095 * a session with a service endpoint. If this property is set to
096 * true, the service client indicates that it wants the session
097 * to be maintained. If set to false, the session is not maintained.
098 * The default value for this property is <code>false</code>.
099 * <p>Type: <code>java.lang.Boolean</code>
100 */
101 public static final String SESSION_MAINTAIN_PROPERTY =
102 "javax.xml.rpc.session.maintain";
103
104 /**
105 * Indicates whether <code>addParameter</code> and
106 * <code>setReturnType</code> methods
107 * are to be invoked to specify the parameter and return type
108 * specification for a specific operation.
109 *
110 * @param operationName Qualified name of the operation
111 *
112 * @return Returns true if the Call implementation class
113 * requires addParameter and setReturnType to be
114 * invoked in the client code for the specified
115 * operation. This method returns false otherwise.
116 */
117 public boolean isParameterAndReturnSpecRequired(QName operationName);
118
119 /**
120 * Adds a parameter type and mode for a specific operation.
121 * Note that the client code may not call any
122 * <code>addParameter</code> and <code>setReturnType</code>
123 * methods before calling the <code>invoke</code> method. In
124 * this case, the Call implementation class determines the
125 * parameter types by using reflection on parameters, using
126 * the WSDL description and configured type mapping registry.
127 *
128 * @param paramName Name of the parameter
129 * @param xmlType XML datatype of the parameter
130 * @param parameterMode Mode of the parameter-whether
131 * <code>ParameterMode.IN</code>,
132 * <code>ParameterMode.OUT</code>,
133 * or <code>ParameterMode.INOUT
134 * @throws JAXRPCException This exception may
135 * be thrown if the method <code>isParameterAndReturnSpecRequired</code>
136 * returns <code>false</code> for this operation.
137 * @throws java.lang.IllegalArgumentException If any illegal
138 * parameter name or XML type is specified
139 */
140 public void addParameter(String paramName, QName xmlType,
141 ParameterMode parameterMode);
142
143 /**
144 * Adds a parameter type and mode for a specific operation.
145 * This method is used to specify the Java type for either
146 * OUT or INOUT parameters.
147 *
148 * @param paramName Name of the parameter
149 * @param xmlType XML datatype of the parameter
150 * @param javaType The Java class of the parameter
151 * @param parameterMode Mode of the parameter-whether
152 * ParameterMode.IN, OUT or INOUT
153 * @throws JAXRPCException <ul>
154 *
155 * <li>This exception may be thrown if this method is
156 * invoked when the method <code>isParameterAndReturnSpecRequired</code>
157 * returns <code>false</code>.
158 * <li>If specified XML type and Java type mapping
159 * is not valid. For example, <code>TypeMappingRegistry</code>
160 * has no serializers for this mapping.
161 * </ul>
162 * @throws java.lang.IllegalArgumentException If any illegal
163 * parameter name or XML type is specified
164 * @throws java.lang.UnsupportedOperationException If this
165 * method is not supported
166 */
167 public void addParameter(String paramName, QName xmlType, Class javaType,
168 ParameterMode parameterMode);
169
170 /**
171 * Gets the XML type of a parameter by name.
172 *
173 * @param paramName name of the parameter
174 *
175 * @return Returns XML type for the specified parameter
176 */
177 public QName getParameterTypeByName(String paramName);
178
179 /**
180 * Sets the return type for a specific operation. Invoking
181 * <code>setReturnType(null)</code> removes the return
182 * type for this Call object.
183 *
184 * @param xmlType XML data type of the return value
185 * @throws JAXRPCException This exception
186 * may be thrown when the method
187 * <code>isParameterAndReturnSpecRequired</code> returns
188 * <code>false</code>.
189 * @throws java.lang.IllegalArgumentException If an illegal
190 * XML type is specified
191 */
192 public void setReturnType(QName xmlType);
193
194 /**
195 * Sets the return type for a specific operation.
196 *
197 * @param xmlType XML data type of the return value
198 * @param javaType Java class of the return value
199 * @throws JAXRPCException <ul>
200 * <li>This exception may be thrown if this method is
201 * invoked when the method <code>isParameterAndReturnSpecRequired</code>
202 * returns <code>false</code>.
203 * <li>If XML type and Java type cannot be mapped
204 * using the standard type mapping or TypeMapping
205 * registry
206 * </ul>
207 * @throws java.lang.UnsupportedOperationException If this
208 * method is not supported
209 * @throws java.lang.IllegalArgumentException If an illegal
210 * XML type is specified
211 */
212 public void setReturnType(QName xmlType, Class javaType);
213
214 /**
215 * Gets the return type for a specific operation.
216 *
217 * @return the XML type for the return value
218 */
219 public QName getReturnType();
220
221 /**
222 * Removes all specified parameters from this <code>Call</code> instance.
223 * Note that this method removes only the parameters and not
224 * the return type. The <code>setReturnType(null)</code> is
225 * used to remove the return type.
226 *
227 * @throws JAXRPCException This exception may be
228 * thrown If this method is called when the method
229 * <code>isParameterAndReturnSpecRequired</code>
230 * returns <code>false</code> for this Call's operation.
231 */
232 public void removeAllParameters();
233
234 /**
235 * Gets the name of the operation to be invoked using this Call instance.
236 *
237 * @return Qualified name of the operation
238 */
239 public QName getOperationName();
240
241 /**
242 * Sets the name of the operation to be invoked using this
243 * <code>Call</code> instance.
244 *
245 * @param operationName QName of the operation to be
246 * invoked using the Call instance
247 */
248 public void setOperationName(QName operationName);
249
250 /**
251 * Gets the qualified name of the port type.
252 *
253 * @return Qualified name of the port type
254 */
255 public QName getPortTypeName();
256
257 /**
258 * Sets the qualified name of the port type.
259 *
260 * @param portType Qualified name of the port type
261 */
262 public void setPortTypeName(QName portType);
263
264 /**
265 * Sets the address of the target service endpoint.
266 * This address must correspond to the transport specified
267 * in the binding for this <code>Call</code> instance.
268 *
269 * @param address Address of the target service endpoint;
270 * specified as an URI
271 */
272 public void setTargetEndpointAddress(String address);
273
274 /**
275 * Gets the address of a target service endpoint.
276 *
277 * @return Endpoint address of the target service port as an URI
278 */
279 public String getTargetEndpointAddress();
280
281 /**
282 * Sets the value for a named property. JAX-RPC specification
283 * specifies a standard set of properties that may be passed
284 * to the <code>Call.setProperty</code> method.
285 *
286 * @param name Name of the property
287 * @param value Value of the property
288 * @throws JAXRPCException <ul>
289 * <li>If an optional standard property name is
290 * specified, however this <code>Call</code> implementation
291 * class does not support the configuration of
292 * this property.
293 * <li>If an invalid (or unsupported) property name is
294 * specified or if a value of mismatched property
295 * type is passed.
296 * <li>If there is any error in the configuration of
297 * a valid property.
298 * </ul>
299 */
300 public void setProperty(String name, Object value);
301
302 /**
303 * Gets the value of a named property.
304 *
305 * @param name Name of the property
306 *
307 * @return Value of the named property
308 * @throws JAXRPCException if an invalid or
309 * unsupported property name is passed.
310 */
311 public Object getProperty(String name);
312
313 /**
314 * Removes a named property.
315 *
316 * @param name Name of the property
317 * @throws JAXRPCException if an invalid or
318 * unsupported property name is passed.
319 */
320 public void removeProperty(String name);
321
322 /**
323 * Gets the names of configurable properties supported by
324 * this <code>Call</code> object.
325 *
326 * @return Iterator for the property names
327 */
328 public Iterator getPropertyNames();
329
330 // Remote Method Invocation methods
331
332 /**
333 * Invokes a specific operation using a synchronous request-response
334 * interaction mode.
335 *
336 * @param inputParams Object[]--Parameters for this invocation. This
337 * includes only the input params
338 *
339 * @return Returns the return value or <code>null</code>
340 *
341 * @throws java.rmi.RemoteException if there is any error in the remote
342 * method invocation or if the Call
343 * object is not configured properly.
344 * @throws javax.xml.rpc.soap.SOAPFaultException Indicates a SOAP fault
345 * @throws JAXRPCException <ul>
346 *
347 * <li>If there is an error in the configuration of the
348 * <code>Call</code> object
349 * <li>If <code>inputParams</code> do not match the required parameter
350 * set (as specified through the <code>addParameter</code>
351 * invocations or in the corresponding WSDL)
352 * <li>If parameters and return type are incorrectly
353 * specified
354 * </ul>
355 */
356 public Object invoke(Object[] inputParams) throws java.rmi.RemoteException;
357
358 /**
359 * Invokes a specific operation using a synchronous request-response
360 * interaction mode.
361 *
362 * @param operationName QName of the operation
363 * @param inputParams Object[]--Parameters for this invocation. This
364 * includes only the input params.
365 *
366 * @return Return value or null
367 *
368 * @throws java.rmi.RemoteException if there is any error in the
369 * remote method invocation.
370 * @throws javax.xml.rpc.soap.SOAPFaultException Indicates a SOAP fault
371 * @throws JAXRPCException <ul>
372 * <li>If there is an error in the configuration of the
373 * <code>Cal</code>l object
374 * <li>If <code>inputParam</code>s do not match the required parameter
375 * set (as specified through the <code>addParameter</code>
376 * invocations or in the corresponding WSDL)
377 * <li>If parameters and return type are incorrectly
378 * specified
379 * </ul>
380 */
381 public Object invoke(QName operationName, Object[] inputParams)
382 throws java.rmi.RemoteException;
383
384 /**
385 * Invokes a remote method using the one-way interaction mode. The
386 * client thread does not block waiting for the completion of the
387 * server processing for this remote method invocation. This method
388 * must not throw any remote exceptions. This method may throw a
389 * <code>JAXRPCException</code> during the processing of the one-way
390 * remote call.
391 *
392 * @param params Object[]--Parameters for this invocation. This
393 * includes only the input params.
394 *
395 * @throws JAXRPCException if there is an error in the
396 * configuration of the <code>Call</code> object (example: a
397 * non-void return type has been incorrectly specified for the
398 * one-way call) or if there is any error during the
399 * invocation of the one-way remote call
400 */
401 public void invokeOneWay(Object[] params);
402
403 /**
404 * Returns a <code>Map</code> of {name, value} for the output parameters of
405 * the last invoked operation. The parameter names in the
406 * returned Map are of type <code>java.lang.String</code>.
407 *
408 * @return Map Output parameters for the last <code>Call.invoke()</code>.
409 * Empty <code>Map</code> is returned if there are no output
410 * parameters.
411 * @throws javax.xml.rpc.JAXRPCException If this method is invoked for a
412 * one-way operation or is invoked before any
413 * <code>invoke</code> method has been called.
414 */
415 public Map getOutputParams();
416
417 /**
418 * Returns a <code>List</code> values for the output parameters
419 * of the last invoked operation.
420 *
421 * @return java.util.List Values for the output parameters. An
422 * empty <code>List</code> is returned if there are
423 * no output values.
424 *
425 * @throws JAXRPCException If this method is invoked for a
426 * one-way operation or is invoked before any
427 * <code>invoke</code> method has been called.
428 */
429 public List getOutputValues();
430 }
431