public interface Service {
// Property Accessor Methods (by property name)
public abstract javax.xml.rpc.handler.HandlerRegistry getHandlerRegistry( );
public abstract Iterator getPorts( ) throws ServiceException;
public abstract javax.xml.namespace.QName getServiceName( );
public abstract javax.xml.rpc.encoding.TypeMappingRegistry getTypeMappingRegistry( );
public abstract java.net.URL getWSDLDocumentLocation( );
// Public Instance Methods
public abstract Call createCall( ) throws ServiceException;
public abstract Call createCall(javax.xml.namespace.QName portName)
throws ServiceException;
public abstract Call createCall(javax.xml.namespace.QName portName,
javax.xml.namespace.QName operationName) throws ServiceException;
public abstract Call createCall(javax.xml.namespace.QName portName,
String operationName) throws ServiceException;
public abstract Call[ ] getCalls(javax.xml.namespace.QName portName)
throws ServiceException;
public abstract java.rmi.Remote getPort(Class serviceEndpointInterface)
throws ServiceException;
public abstract java.rmi.Remote getPort(javax.xml.namespace.QName portName,
Class serviceEndpointInterface) throws ServiceException;
}
Service is the core interface of the JAX-RPC
client-side API, representing a service element in
a WSDL definition of a web service. There are several ways to obtain
a Service object, which are discussed in the
following list.
By using a tool such as wscompile to generate
stubs from a WSDL file or an equivalent Java interface definition.
This process also creates a class that implements the
Service interface.
From a ServiceFactory, either with or without the
help of a WSDL document that describes the service. A
Service object that is created by a
ServiceFactory without the use of a WSDL document
is simply a skeleton that has no information about the service other
than its qualified name, and can be used only in conjunction with the
Dynamic Invocation Interface (DII), which is described in the
reference section for the Call interface.
I'll refer to this type of
Service as unconfigured.
For container-resident clients only, from the JNDI environment. A
Service obtained from the environment normally is
generated from a WSDL definition and is therefore fully configured
with service information. Sometimes, however, the WSDL document may
not contain a service; element. In such a case,
the Service object contains information about the
operations that the service provides, but does not contain the
service address.
The getWSDLDcoumentLocation( ) method returns the
URL for the WSDL document from which the Service
is generated, or null if it is not created from a
WSDL document. The getServiceName( ) method
returns the fully qualified name of the service in the form of a
javax.xml.namespace.QName object.
A web service is composed of one or more ports, each of which is an
access point for an instance of the service with an associated
address. A single web service might be accessible at more than one
address (and therefore have multiple ports) if it supports more than
one transport protocol, or perhaps for load-balancing or mirroring
reasons. You can use the getPorts( ) method to get
an Iterator over all of the ports of the service.
In the case of an unconfigured Service object,
this Iterator does not contain any elements.
To get an object that can be used to invoke the methods of a specific
service endpoint interface, use one of the getPort(
) methods and cast it to the service endpoint interface
type. These methods throw a ServiceException if
invoked on an unconfigured Service object. The
two-argument getPort( ) method returns an object
that can be used to invoke the methods of a port given the fully
qualified name of the port from the WSDL definition, and a
Class object that represents the Java interface
created from the port definition. The returned value can be cast to
the given class type. The one-argument variant supplies only the Java
interface, and does not specify the qualified name of the port. Use
of this method is not recommended in circumstances in which it can be
avoided because it requires a search of the WSDL definition to locate
a port whose operations match the methods defined by the Java
interface. This requires not only a comparison of method and
operation names, but also their argument types. The getPort(
) methods may return an instance of a pregenerated stub
class or a dynamic proxy, which is a class generated on-the-fly that
implements the methods of the service endpoint interface accessible
through the named port. Dynamic proxies are actually implemented
using the DII, as described in the reference section for
Call earlier in this chapter.
The createCall( ) methods return a
Call object that can be used to construct a DII
call to one of the methods provided by the service. The two-argument
variants create a Call object that is fully
configured to invoke a specific method, whereas the one-argument
variant requires you to additionally specify the operation name using
the methods of the Call interface. The
zero-argument variant of this method requires you to specify both the
port name and the operation name before attempting to make a call.
The getCalls( ) method returns an array of
Call objects, each of which is fully configured to
invoke one method of the service endpoint interface. Each time this
method is called, it generates and returns a new set of
Call objects and is therefore a relatively
expensive operation. A ServiceException is thrown
if this method is called on an unconfigured
Service object.
The getTypeMappingRegistry( ) method returns a
reference to the type mapping information relating to the service.
This information, which determines how
Java data types are mapped to and from
their corresponding XML representation in SOAP messages, is created
dynamically from the WSDL definition of the service or the equivalent
Java interface. Some implementations may also allow you to add
additional mappings, as described in Chapter 6 of
this book. The getHandlerRegistry( ) method
returns a HandlerRegistry object that contains the
configuration of SOAP handlers that will appear in the processing
pipeline for messages sent to the service. SOAP handlers can modify
or extract information from a SOAP message before it is sent or after
it is received. Refer to Chapter 6 or Chapter 15 for further
information.
