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 case�if 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 methods�these 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.
