ServiceException | Java Web Services in a Nutshell

Service

javax.xml.rpc

JAX-RPC 1.0; JWSDP 1.0, J2EE 1.4

 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.

Returned By

ServiceFactory.createService( )