JAXRPCException | Java Web Services in a Nutshell

Call

javax.xml.rpc

JAX-RPC 1.0; JWSDP 1.0, J2EE 1.4

 public interface Call {  // Public Constants  public static final String ENCODINGSTYLE_URI_PROPERTY;  // ="javax.xml.rpc.encodingstyle.namespace.uri"  public static final String OPERATION_STYLE_PROPERTY;  // ="javax.xml.rpc.soap.operation.style"  public static final String PASSWORD_PROPERTY;  // ="javax.xml.rpc.security.auth.password"  public static final String SESSION_MAINTAIN_PROPERTY;  // ="javax.xml.rpc.session.maintain"  public static final String SOAPACTION_URI_PROPERTY;  // ="javax.xml.rpc.soap.http.soapaction.uri"  public static final String SOAPACTION_USE_PROPERTY;  // ="javax.xml.rpc.soap.http.soapaction.use"  public static final String USERNAME_PROPERTY;  // ="javax.xml.rpc.security.auth.username"   // Property Accessor Methods (by property name)  public abstract javax.xml.namespace.QName getOperationName(  );     public abstract void setOperationName(javax.xml.namespace.QName   operationName   );     public abstract Map getOutputParams( );      public abstract java.util.List getOutputValues( );      public abstract javax.xml.namespace.QName getPortTypeName(  );     public abstract void setPortTypeName(javax.xml.namespace.QName   portType   );      public abstract Iterator getPropertyNames(  );      public abstract javax.xml.namespace.QName getReturnType(  );      public abstract void setReturnType(javax.xml.namespace.QName   xmlType   );      public abstract void setReturnType(javax.xml.namespace.QName   xmlType   ,  Class   javaType   );      public abstract String getTargetEndpointAddress(  );      public abstract void setTargetEndpointAddress(  // Public Instance Methods  public abstract void addParameter(String   paramName   ,          javax.xml.namespace.QName   xmlType   , ParameterMode   parameterMode   );      public abstract void addParameter(String   paramName   , javax.xml.namespace.QName   xmlType   ,          Class   javaType   , ParameterMode   parameterMode   );     public abstract javax.xml.namespace.QName getParameterTypeByName(String   paramName   );      public abstract Object getProperty( String   name   );      public abstract Object invoke(Object[ ]   inputParams   ) throws java.rmi.RemoteException;      public abstract Object invoke(javax.xml.namespace.QName   operationName   , Object[ ]   inputParams   )          throws java.rmi.RemoteException;      public abstract void invokeOneWay(Object[ ]   inputParams   );     public abstract boolean isParameterAndReturnSpecRequired(javax.xml.namespace.QName   operationName   );     public abstract void removeAllParameters(  );      public abstract void removeProperty( String   name   );      public abstract void setProperty(String   name   , Object   value   );  }

The Call interface allows you to construct and make a call to a method in a web service endpoint interface without using a generated stub class or a dynamic proxy. In order to make a call, you need to obtain a Call object and configure the names of the port and operation that you want to invoke, together with the types of the input and output arguments and the return value, if there is one. Once the Call object is properly initialized , set the address of the service using the setTargetEndpointAddress( ) method, and use the invoke( ) or invokeOneWay( ) methods to make the method call. Depending on exactly how the Call object is obtained, some or all of the required information may already be set up, leaving you with less to do. The Call interface provides the JAX-RPC Dynamic Invocation Interface (DII). This is primarily intended as an internal implementation mechanism for dynamic proxies and for service brokers , which dynamically discover services and construct method calls given suitable parameters obtained from a human or from other software. It is not the preferred mechanism for creating web service clients .

An instance of Call is obtained from a Service object and is therefore already associated with a specific web service. Depending on how it was created, it may already be configured for a specific port and even a particular method within that port. If the port is not configured, the setPortTypeName( ) method must be used to set it, using its fully qualified name from the WSDL definition, before a call can be made. If the operation name is not configured, you may choose to set (or change) it using the setOperationName( ) method (which also requires a fully qualified name), or you can supply the operation name when you make the method call.

If the Call object is obtained from a Service object that was built from a WSDL definition (perhaps by passing a WSDL document URL to the ServiceFactory createService( ) method), then it is already fully initialized with information regarding the input and output arguments and the return value of the target method, and you may not change them. You can use the isParameterAndReturnSpecRequired( ) to determine whether this is the caseif false is returned, the Call object is fully initialized and you cannot use the calls described in the following two paragraphs. Otherwise, you are required to initialize the Call object as described next .

If the method requires input or output parameters, you must use one of the addParameter( ) methods to declare at least the name, XML type, and mode of each parameter. This information can, of course, be obtained directly from the WSDL definition of the operation. The XML type is an XML schema or SOAP data type, and is declared using one of the constants defined by the javax.xml.rpc.encoding.XMLType interface. In most cases, an XML type implies a corresponding Java type, but, where there are ambiguities , you may supply an explicit Java class in addition to the XML type. An example of such is XSD_DATETIME , which could be mapped to either java.util.Date or java.util.Calendar . Note that if you supply both the XML type and the Java class, then they must be compatible. The parameter modes are defined by the ParameterMode interface and may be IN , OUT , or INOUT . You do not set the argument values using these methodsthese are supplied at invocation time. Note also that once you have built and used a Call object, you can reuse it either unchanged to make another call to the same method, or to make a call to a different method by resetting it by using removeAllParameters( ) .

The type of the value returned by the method is set using setReturnType( ) , which has two variants that specify either just the XML type (again using a value defined by the javax.xml.rpc.encoding.XMLType interface) or both the type and the corresponding Java class. If the method does not return anything (i.e., the Java return type is void ), use setReturnType(null) .

To call the web service method, use either invoke( ) or invokeOneWay( ) . There are two variants of invoke( ) , one of which requires the fully qualified name of the operation and the argument values, while the other requires only the arguments and relies on the operation already configured in the Call object. invoke( ) is a synchronous operation that blocks until the server sends a reply. The value returned from the remote operation is also the return value of the invoke( ) call. By contrast, invokeOneWay( ) simply calls the web service method and does not return anything. This is not necessarily the same as an asynchronous operation, since the caller may still be blocked until the server completes the operation, even though there is no return value from the method call.

The order of argument values in the list passed to both invoke( ) and invokeOneWay( ) must match the order in which the corresponding method parameters are declared and, of course, the data type of each argument must be compatible with that of its matching method parameter. Values should not be supplied for method parameters that are declared to have mode OUT . The values returned for output and input/output parameters can be obtained using the getOutputValues( ) and getOutputParams( ) methods. The first of these methods returns a java.util.List containing the output values in the order in which they appear in the WSDL definition of the operation (and the same order as that used with the addParameter( ) method). The second method returns a java.util.Map in which the key to each entry is the fully qualified name ( QName ) of an argument, and the value is its returned value.

The Call interface defines a small number of properties, the values of which can be set and read using the setProperty( ) and getProperty( ) methods. Only property names defined in the JAX-RPC specification can be used with these methods, and not all properties need be supported by all implementations . The getPropertyNames( ) method can be used to get the complete set of supported names. To unset a property, use the removeProperty() method. The properties defined by the specification are as follows :

USERNAME_PROPERTY: Holds the username associated with the caller. This property need only be set if the service being called is protected by HTTP basic authentication. All implementations must support this property.
PASSWORD_PROPERTY: The caller's password. This property, which must be supported by all implementations, is used together with USERNAME_PROPERTY .
SESSION_MAINTAIN_PROPERTY: A value of type Boolean that specifies whether the client will allow the service to maintain HTTP session information for the client between calls. A service implementation that implements the javax.xml.rpc.server.ServiceLifecycle interface can make use of sessions to store state between method calls if this property is set to true. Support for this property is mandatory.
OPERATION_STYLE_PROPERTY: Indicates whether the operation is rpc- or document-style using the values rpc and document , respectively. Support for this property is optional.
SOAPACTION_USE_PROPERTY: A Boolean value that indicates whether a SOAPAction header should be included in the message. Defaults to Boolean.FALSE . Support for this property is optional.
SOAPACTION_URI_PROPERTY: The URI to be included as the value of the SOAPAction header if the SOAPACTION_USE_PROPERTY has the value Boolean.TRUE . Support for this property is optional.
ENCODINGSTYLE_URI_PROPERTY: The encoding style to be used for elements in the generated SOAP message that do not have an explicitly specified style. Defaults to the standard SOAP encoding rules. Support for this property is optional.

Returned By

javax.xml.rpc.Service.{createCall( ) , getCalls( )}