001 /*
002 * Copyright 2001-2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package javax.xml.rpc;
017
018 import javax.xml.namespace.QName;
019 import java.util.Iterator;
020 import java.util.List;
021 import java.util.Map;
022
023 /**
024 * The <code>javax.xml.rpc.Call</code> interface provides support
025 * for the dynamic invocation of a service endpoint. The
026 * <code>javax.xml.rpc.Service</code> interface acts as a factory
027 * for the creation of <code>Call</code> instances.
028 * <p>
029 * Once a <code>Call</code> instance is created, various setter
030 * and getter methods may be used to configure this <code>Call</code>
031 * instance.
032 *
033 * @version 1.0
034 */
035 public interface Call {
036
037 /**
038 * Standard property: User name for authentication
039 * <p>Type: <code>java.lang.String
040 */
041 public static final String USERNAME_PROPERTY =
042 "javax.xml.rpc.security.auth.username";
043
044 /**
045 * Standard property: Password for authentication
046 * <p>Type: <code>java.lang.String</code>
047 */
048 public static final String PASSWORD_PROPERTY =
049 "javax.xml.rpc.security.auth.password";
050
051 /**
052 * Standard property for operation style. This property is
053 * set to "rpc" if the operation style is rpc; "document"
054 * if the operation style is document.
055 * <p>Type: <code>java.lang.String</code>
056 */
057 public static final String OPERATION_STYLE_PROPERTY =
058 "javax.xml.rpc.soap.operation.style";
059
060 /**
061 * Standard property for SOAPAction. This boolean property
062 * indicates whether or not SOAPAction is to be used. The
063 * default value of this property is false indicating that
064 * the SOAPAction is not used.
065 * <p>Type: <code>java.lang.Boolean</code>
066 */
067 public static final String SOAPACTION_USE_PROPERTY =
068 "javax.xml.rpc.soap.http.soapaction.use";
069
070 /**
071 * Standard property for SOAPAction. Indicates the SOAPAction
072 * URI if the <code>javax.xml.rpc.soap.http.soapaction.use</code>
073 * property is set to <code>true</code>.
074 * <p>Type: <code>java.lang.String</code>
075 */
076 public static final String SOAPACTION_URI_PROPERTY =
077 "javax.xml.rpc.soap.http.soapaction.uri";
078
079 /**
080 * Standard property for encoding Style: Encoding style specified
081 * as a namespace URI. The default value is the SOAP 1.1 encoding
082 * <code>http://schemas.xmlsoap.org/soap/encoding/</code>
083 * <p>Type: <code>java.lang.String</code>
084 */
085 public static final String ENCODINGSTYLE_URI_PROPERTY =
086 "javax.xml.rpc.encodingstyle.namespace.uri";
087
088 /**
089 * Standard property: This boolean property is used by a service
090 * client to indicate whether or not it wants to participate in
091 * a session with a service endpoint. If this property is set to
092 * true, the service client indicates that it wants the session
093 * to be maintained. If set to false, the session is not maintained.
094 * The default value for this property is <code>false</code>.
095 * <p>Type: <code>java.lang.Boolean</code>
096 */
097 public static final String SESSION_MAINTAIN_PROPERTY =
098 "javax.xml.rpc.session.maintain";
099
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