== Dynamic Web Services ==

Dynamic Web Services allow to publish and discover interfaces at deployment or run time.

Such ability to avoid pre-generated artifacts facilitates scripting-based custom software and allow rapid prototyping and iterative development.

=== Web Services Endpoint API ===

Web Service endpoints can be created and published programmatically using javax.xml.ws.Endpoint API. An endpoint consists of a Web Service Implementation object and some configuration information. The implementation hosts the web service endpoint using a light weight http server and clients can access the web service as if the endpoint is deployed in a J2EE container. This means that there is no need to have any J2EE servlet or EJB container to host the endpoint. The Endpoint API provides a way to configure the endpoint with the necessary binding, metadata(WSDL and schema documents), handlers etc.

 Endpoint and Properties:: An endpoint can be configured to match service name and port name of WSDL using properties. This overwrites implementor object's serviceName, portName from @WebService annotation. The port address for an endpoint is patched only if the corresponding port's service name, and port name in WSDL are matched. 

For example: 
{{{
  Endpoint endpoint = ...
  Map<String, Object> map = new HashMap<String, Object>();
  map.put(Endpoint.WSDL_SERVICE, new QName(...));
  map.put(Endpoint.WSDL_PORT, new QName(...));  endpoint.setProperties(map);
}}}

Endpoint and Binding 
Endpoint can be configured for different bindings using binding ids. These binding ids are defined in JAX-WS API and endpoint can be configured by specifying @BindingType annotation or using binding id in the Endpoint() constructors. The parameter in constructor overwrites binding defined by @BindingType annotation. If the binding is not specified using @BindingType or using a parameter in Endpoint() constructor, the default binding is SOAP1.1/HTTP. Binding object is used to configure MTOM, handler chain etc. SOAP binding object is used to configure SOAP binding specifics like roles. 

For example: 

The following configures the endpoint for XML/HTTP binding.  

{{{
Endpoint endpoint = Endpoint.create(HTTPBinding.HTTP_BINDING, implementor);
}}}

For example:  
// setting MTOM
  SOAPBinding binding = (SOAPBinding)endpoint.getBinding();  
  binding.setMTOMEnabled((true);
  // setting SOAP binding roles
  binding.setRoles(...);
  // setting handler chain
  binding.setHandlerChain(...);

 Endpoint and metadata:: When the service endpoint is created using existing java classes, the implementation dynamically generates and publishes WSDL and schema documents. But when the service endpoint is created using existing WSDL documents, the same WSDL documents can be used for publishing using metadata facility. When a Source object is created, set systemid always and make sure the imports are resolvable w.r.t systemids. 

For example: 
{{{
   // metadata processing for WSDL, schema files
   List <File> metadataFile = ...
   List<Source> metadata = new ArrayList<Source>();
   for(File file : metadataFile) {
       Source source = new StreamSource(new FileInputStream(file));
       source.setSystemId(file.toURL().toExternalForm());
       metadata.add(source);
   }
   endpoint.setMetadata(metadata);
}}}

 See Also::
 * [[https://jax-ws.dev.java.net/nonav/2.1.1/docs/endpoint.html|Web Services Endpoint API]]

=== Web Services Handler ===

JAX-WS 2.0 defines a Handler interface, with subinterfaces `LogicalHandler` and `SOAPHandler`. The Handler interface contains `handleMessage(C context)` and `handleFault(C context)` methods, where `C extends MessageContext`. A property in the `MessageContext` object is used to determine if the message is inbound or outbound. `SOAPHandler` objects have access to the full soap message including headers. Logical handlers are independent of protocol and have access to the payload of the message. 

The new handler types can now be written without casting the message context object that is passed to them. For instance: 

{{{
public class MyLogicalHandler implements LogicalHandler<LogicalMessageContext> {
    public boolean handleMessage(LogicalMessageContext messageContext) {
        LogicalMessage msg = messageContext.getMessage();
        return true;
    }
    // other methods
}

public class MySOAPHandler implements SOAPHandler<SOAPMessageContext> {

    public boolean handleMessage(SOAPMessageContext messageContext) {
        SOAPMessage msg = messageContext.getMessage();
        return true;
    }
    // other methods
}
}}}

A `close(C context)` method has been added that is called on the handlers at the conclusion of a message exchange pattern. This allows handlers to clean up any resources that were used for the processing of a request-only or request/response exchange. 

The `init()` and `destroy()` methods of the handler lifecycle no longer exist. Instead, a method may be annotated with the `@PostConstruct` annotation to be called after the handler is created or the `@PreDestroy` annotation to be called before the handler is destroyed.

 See Also::
 * [[https://jax-ws.dev.java.net/nonav/2.1.1/docs/handlers.html|Web Services (JAX-WS) Handler]]
