11.2.  Use MTOM on the client.

11.2.1.  Use MTOMFeature with getPort() methods.

If you want to use MTOM, you should encode your binary data as xs:base64Binary content. Then enable MTOM on the client side by passing javax.xml.ws.MTOMFeature to the proxy constructor.

For each port in the service, the generated client side service class contains the following methods, two for each port defined by the WSDL service and whose binding is supported by the JAX-WS implementation:

  • get<PortName>()

    One required method that takes no parameters and returns a proxy that implements the mapped service endpoint interface. The method generated delegates to the Service.getPort(...) method passing it the port name. The value of the port name MUST be equal to the value specified in the mandatory WebEndpoint annotation on the method itself.

  • get<PortName>(WebServiceFeature... features)

    One required method that takes a variable-length array of javax.xml.ws.WebServiceFeature and returns a proxy that implements the mapped service endpoint interface. The method generated delegates to the Service.getPort(QName portName, Class<T> SEI, WebServiceFeature... features) method passing it the port name, the SEI and the features. The value of the port name MUST be equal to the value specified in the mandatory WebEndpoint annotation on the method itself.

Example of generated web service client:

@WebEndpoint(name = "CatalogPort")
public Catalog getCatalogPort() {
    return super.getPort(new QName("http://example.com", "CatalogPort"), Catalog.class);
}

@WebEndpoint(name = "CatalogPort")
public Catalog getCatalogPort(WebServiceFeature... features) {
    return super.getPort(new QName("http://example.com", "CatalogPort"), Catalog.class, features);
}
						

A WebServiceFeature is a standard manner of enabling and disabling support for a variety of useful mechanisms at runtime. Some features come built in with JAX-WS, and vendors can provide additional features. You can also write your own.

The class javax.xml.ws.soap.MTOMFeature extends WebServiceFeature. The generated client interfaces make it easy to invoke your service operations using a built-in or custom feature. To use MTOM on the client, simply retrieve the port using the factory that accepts a variable-length argument of WebServiceFeature objects, passing in an instance of the MTOMFeature. Here's how you can enable MTOM using the getCatalogPort method:

Catalog catalogPort = service.getCatalogPort(new MTOMFeature());
						

The implementation is handled for you by the runtime.

The MTOMFeature constructor also accepts an optional integer argument indicating the threshold, or the number of bytes that the binary data should be before being sent as an attachment. The default value for the threshold is 0.

11.2.2.  Use MTOM in the deployment descriptors.

blah-blah

11.2.3.  Sending any additional attachments using MessageContext properties.

javax.xml.ws.handler.MessageContext

MessageContext is the super interface for all JAX-WS message contexts. It extends Map<String,Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example, a handler may use the put method to insert a property in the message context that one or more other handlers in the handler chain may subsequently obtain via the get method.

Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers for an instance of an MEP on a particular endpoint. E.g., if a logical handler puts a property in the message context, that property will also be available to any protocol handlers in the chain during the execution of an MEP instance. APPLICATION scoped properties are also made available to client applications and service endpoint implementations. The default scope for a property is HANDLER.

Some standard message context properties:

  • javax.xml.ws.binding.attachments.inbound Type - Map<String,DataHandler>

    A map of attachments to an inbound message. The key is a unique identifier for the attachment. The value is a DataHandler for the attachment data. Bindings describe how to carry attachments with messages.

  • javax.xml.ws.binding.attachments.outbound Type - Map<String,DataHandler>

    A map of attachments to an outbound message. The key is a unique identifier for the attachment. The value is a DataHandler for the attachment data. Bindings describe how to carry attachments with messages.

Mime attachments specified by the javax.xml.ws.binding.attachments.inbound and javax.xml.ws.binding.attachments.outbound properties defined in the MessageContext (MessageContext.OUTBOUND_MESSAGE_ATTACHMENTS, MessageContext.INBOUND_MESSAGE_ATTACHMENTS)can be modified in logical handlers. A SOAP message with the attachments specified using the properties is generated before invoking the first SOAPHandler. Any changes to the two properites in consideration above in the MessageContext after invoking the first SOAPHandler are ignored. The SOAPHandler however may change the properties in the MessageContext.

Use of javax.xml.ws.binding.attachments.outbound property in Dispatch:

  • When using Dispatch in SOAP / HTTP binding in payload mode, attachments specified using the javax.xml.ws.binding.attachments.outbound property will be included as mime attachments in the message.

  • When using Dispatch in SOAP / HTTP binding in message mode, the javax.xml.ws.binding.attachments.outbound property will be ignored as the message type already provides a way to specify attachments.

For example:


// Create Dispatch for the payload
Dispatch<String> dispatch = svc.createDispatch(portName, String.class, Service.Mode.PAYLOAD);

// Get the request context
Map<String, Object> requestContext = dispatch.getRequestContext();

// Get the attachments (non-payload) that should also be sent.
Map<String, DataHandler> attachmentMap = new HashMap();
attachmentMap.put("myCID", myDataHandler);

// Attach the attachments to the request context
requestContext.put("javax.xml.ws.binding.attachments.outbound", attachmentMap);

						

Professional hosting         'Oracle Certified Expert Web Services Developer 6' Quiz     Free SCDJWS 5.0 Guide