org.systinet.wasp.attachments
Class UnreferencedAttachmentsHandler

java.lang.Object
  javax.xml.rpc.handler.GenericHandler
      org.systinet.wasp.handler.WaspGenericHandler
          org.systinet.wasp.attachments.UnreferencedAttachmentsHandler

All Implemented Interfaces:

Handler

public class UnreferencedAttachmentsHandler

extends WaspGenericHandler

JAX-RPC handler and static helper functions to handle unreferenced attachments. By unreferenced attachments mean attachments that are not described in WSDL (no MIME or DIME part, no standard reference in body). Such attachments are sent for example by .NET in its default configuration.

This JAX-RPC handler reads attachments from call context on the sending side and attaches them to the message; on the receiver side all SOAP message attachments are made accessible by putting them to the call context. To put/get attachments to/from context use helper functions provided in this class.

Example (client sending and receiving unreferenced attachments):

 // prepare (for communication with .NET SSJ must be set to use DIME; either for this processing or globally)
 ServiceClient serviceClient = ServiceClient.create("http://servicehost/path/service?wsdl);
 UnreferencedAttachmentsHandler.registerUnreferencedAttachmentsHandler(serviceClient);
 ServiceIface service = (ServiceIface) serviceClient.createProxy(ServiceIface.class);
 // invoke
 InputStream attachment = ...;
 UnreferencedAttachmentsHandler.addAttachment(serviceClient.getCallContext(), attachment);
 service.method();
 // read received attachments
 List attachments = UnreferencedAttachmentsHandler.getInputStreams(serviceClient.getCallContext());
 for (Iterator attachmentIterator = attachments.iterator(); attachmentIterator.hasNext(); ) {
     InputStream attachmentStream = (InputStream) attachmentIterator.next();
     // use attachmentStream
     attachmentStream.close();
 }
 UnreferencedAttachmentsHandler.releaseUnreferencedAttachments(serviceClient);
 

Since:

6.0

Component:

Core

Field Summary

static java.lang.String

CONTEXT_DATA_KEY A key for unreferenced attachment data in the call context.

Fields inherited from class org.systinet.wasp.handler.WaspGenericHandler

headers

Constructor Summary

protected

UnreferencedAttachmentsHandler(java.lang.String messageAttachmentType) Creates a new instance of the handler.

Method Summary

static void	addAttachment(CallContext callContext, javax.activation.DataHandler attachment) Adds a new attachment to the outgoing message.
static void	addAttachment(CallContext callContext, java.io.InputStream attachment) Adds a new attachment to the outgoing message.
static void	addAttachments(CallContext callContext, java.util.Collection attachments) Adds a collection of attachment to the outgoing message.
static java.util.List	getAttachmentParts(CallContext callContext) Returns all input message's attachments as SAAJ attachment parts.
static java.util.List	getInputStreams(CallContext callContext) Returns all input message's attachments as input streams.
static java.util.List	getMessageAttachments(CallContext callContext) Returns all input message's attachments as message attachments.
boolean	handleInput(MessageContext context) Reads all message's attachments and puts the structure in the context.
boolean	handleOutput(MessageContext context) Puts all attachments from the context into the message.
static void	registerUnreferencedAttachmentsHandler(Processing processing) A helper method; registers a new instance of this handler to a processing.
static void	registerUnreferencedAttachmentsHandler(Processing processing, java.lang.String attachmentType) See registerUnreferencedAttachmentsHandler(org.systinet.wasp.webservice.Processing); this method in addition sets up the handler to always set the attachment type of the message to the specified one.
static void	releaseUnreferencedAttachments(ServiceClient serviceClient) Releases all unreferenced attachments.

Methods inherited from class org.systinet.wasp.handler.WaspGenericHandler

getHeaders, handleRequest, handleResponse, init

Methods inherited from class javax.xml.rpc.handler.GenericHandler

destroy, handleFault

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONTEXT_DATA_KEY

public static final java.lang.String CONTEXT_DATA_KEY

A key for unreferenced attachment data in the call context. It is highly recommended to use helper methods provided in this class.

Constructor Detail

UnreferencedAttachmentsHandler

protected UnreferencedAttachmentsHandler(java.lang.String messageAttachmentType)

Creates a new instance of the handler.

Parameters:

messageAttachmentType - null (= use SSJ default), Message.CT_MULTIPART_RELATED or Message.CT_APPLICATION_DIME

Throws:

java.lang.IllegalArgumentException - if messageAttachmentType is wrong

Method Detail

handleOutput

public boolean handleOutput(MessageContext context)

Puts all attachments from the context into the message.

Overrides:

handleOutput in class WaspGenericHandler

Parameters:

context - SOAPMessageContext

Returns:

invocation result, true means process next handler, false means stop processing and return response to client(on server) or stop processing and deserialize response(on client)

handleInput

public boolean handleInput(MessageContext context)

Reads all message's attachments and puts the structure in the context.

Overrides:

handleInput in class WaspGenericHandler

Parameters:

context - SOAPMessageContext

Returns:

invocation result, true means process next handler, false means stop processing and return response to client(on server) or stop processing and deserialize response(on client)

registerUnreferencedAttachmentsHandler

public static void registerUnreferencedAttachmentsHandler(Processing processing)

A helper method; registers a new instance of this handler to a processing. When this is done, attachments from context will be attached to the output message and all attachments from the input message will be available in the context.

Parameters:

processing - a processing (ServiceClient or ServiceEndpoint) that should send/receive unreferenced attachments

Throws:

java.lang.NullPointerException - if processing is null

registerUnreferencedAttachmentsHandler

public static void registerUnreferencedAttachmentsHandler(Processing processing,
                                                          java.lang.String attachmentType)

See registerUnreferencedAttachmentsHandler(org.systinet.wasp.webservice.Processing); this method in addition sets up the handler to always set the attachment type of the message to the specified one. This is useful only when WSDL says nothing about the type and you do not want to use SSJ's default.

Parameters:

processing - a processing to set

attachmentType - null, Message.CT_MULTIPART_RELATED or Message.CT_APPLICATION_DIME

Throws:

java.lang.IllegalArgumentException - if messageAttachmentType is wrong

java.lang.NullPointerException - if processing is null

getAttachmentParts

public static java.util.List getAttachmentParts(CallContext callContext)

Returns all input message's attachments as SAAJ attachment parts.

Parameters:

callContext - get attachments from this call context

Returns:

an unmodifiable list of AttachmentParts; never null; for better perfomance it is recommend to access it sequentially via iterator

getMessageAttachments

public static java.util.List getMessageAttachments(CallContext callContext)

Returns all input message's attachments as message attachments.

Parameters:

callContext - get attachments from this call context

Returns:

an unmodifiable list of MessageAttachments; never null; for better perfomance it is recommend to access it sequentially via iterator

getInputStreams

public static java.util.List getInputStreams(CallContext callContext)

Returns all input message's attachments as input streams.

Parameters:

callContext - get attachments from this call context

Returns:

an unmodifiable list of InputStreams; never null; for better perfomance it is recommend to access it sequentially via iterator

releaseUnreferencedAttachments

public static void releaseUnreferencedAttachments(ServiceClient serviceClient)

Releases all unreferenced attachments.

This method must be called on the client side for every call when work with unreferenced attachments is done.

Parameters:

serviceClient - service client that holds the attachments

Throws:

java.lang.NullPointerException - if serviceClient is null

addAttachments

public static void addAttachments(CallContext callContext,
                                  java.util.Collection attachments)
                           throws java.io.IOException

Adds a collection of attachment to the outgoing message.

Parameters:

callContext - add into this call context

attachments - a collection (possibly unmodifiable) of InputStream, DataHandler or MessageAttachment

Throws:

java.io.IOException - I/O problem with some MessageAttachment

java.lang.NullPointerException - if some parameter is null

java.lang.IllegalArgumentException - if collection contains null or an instance of unexpected class

java.lang.IllegalStateException - if there are unreleased unreferenced attachments

addAttachment

public static void addAttachment(CallContext callContext,
                                 java.io.InputStream attachment)

Adds a new attachment to the outgoing message.

Parameters:

callContext - add into this call context

attachment - attachment represented as input stream; content type "application/octet-stream" will be used for it

Throws:

java.lang.NullPointerException - some parameter is null

java.lang.IllegalStateException - if there are unreleased unreferenced attachments

addAttachment

public static void addAttachment(CallContext callContext,
                                 javax.activation.DataHandler attachment)

Adds a new attachment to the outgoing message.

Parameters:

callContext - add into this call context

attachment - attachment represented by data handler; remember to set up DataContentHandlerFactory properly for attachment type

Throws:

java.lang.NullPointerException - some parameter is null

java.lang.IllegalStateException - if there are unreleased unreferenced attachments