org.osesb.connectors.jaxrpc.attachments
Class JAXRPCServerAttachmentHandler

java.lang.Object
  javax.xml.rpc.handler.GenericHandler
      org.osesb.connectors.jaxrpc.JAXRPCHandlerBase
          org.osesb.connectors.jaxrpc.attachments.JAXRPCServerAttachmentHandler

All Implemented Interfaces:

javax.xml.rpc.handler.Handler

public class JAXRPCServerAttachmentHandler
extends JAXRPCHandlerBase

JAXRPCServerAttachmentHandler is a jax-rpc, server-side handler with a handleRequest() method that detaches attachments from the incoming SOAPMessage and makes the attachments available to the service end point and a handleResponse() method that puts attachments in the response SOAPMessage that were added by the service end point.

The handleRequest() method detaches attachments from the SOAPMessage and sets a static ThreadLocal variable named JAXRPCServerAttachmentHandler.requestAttachmentList to a List of AttachmentDescriptor Objects, one for each attachment. Then, the service end point can call the static method JAXRPCServerAttachmentHandler.getRequestAttachmentList() to retrieve the AttachmentDescriptor(s).

The List of AttachmentDescriptor(s) is meant to be processed by the service end point, which "know" how to dispose of the attachments. In other words, handleRequest() takes care of the mechanics of detachment but not the application-specific disposition of the attachments.

The handleResponse() Method adds attachments to the response SOAPMessage and, optionally, add attachment header entries to the SOAPHeader.

Programmer-defined, server-side attachment handlers should be descendants of this Class that override handleRequest().

jax-rpc handlers implement the javax.xml.rpc.handler.Handler interface. The handleRequest() and handleResponse() methods of that interface are invoked by the SOAP server engine as follows:

• handleRequest() is invoked before a RPC request is dispatched to the target service endpoint.
• handleResponse() is invoked before the RPC response is communicated back to the service client from the target service endpoint.

jax-rpc, server-side handlers are configured in a vendor-specific way. For example, in WLS 8.1.x, server-side handlers are configured using the web-services.xml file.

Since:

Version .9

Nested Class Summary

static class

JAXRPCServerAttachmentHandler.AttachmentListWrapper requestAttachmentList and responseAttachmentList are ThreadLocal variables that hold the attachments that were processed by this handler's handleRequest() and handleResponse() methods, respectively.

Field Summary

protected static java.lang.String

thisClassName The full name of this class.

Fields inherited from class org.osesb.connectors.jaxrpc.JAXRPCHandlerBase

handlerConfig, log

Constructor Summary

JAXRPCServerAttachmentHandler()

Method Summary

static void	addResponseAttachment(byte[] bytes) Add a byte[] as an attachment to the to the responseAttachmentList, which contains the attachments that should be added to the response SOAPMessage by this handler's handleResponse() method.
static void	addResponseAttachments(AttachmentDescriptor[] attachmentDescriptors) Add attachments to the to the responseAttachmentList, where attachment properties and contents are specified as org.osesb.connectors.jaxrpc.attachments.AttachmentDescriptor(s).
static void	addResponseAttachments(java.io.File[] fileAttachments) Add the contents of Files to the responseAttachmentList, which contains the attachments that should be added to the response SOAPMessage by this handler's handleResponse() method.
static void	addResponseAttachments(java.io.InputStream[] streamAttachments) Add the contents of InputStreams to the responseAttachmentList, which contains the attachments that should be added to the response SOAPMessage by this handler's handleResponse() method.
static java.util.List	getRequestAttachmentList() Return requestAttachmentList, which is a ThreadLocal variable that is set to to a List of AttachmentDescriptor Objects, one for each attachment that was detached from the SOAPMessage by this handler's handleRequest() method.
static java.util.List	getResponseAttachmentList() responseAttachmentList is a ThreadLocal variable that holds a List of AttachmentDescriptor Objects, one for each attachment that should be added to the response SOAPMessage by this handler's handleResponse() method.
boolean	handleRequest(javax.xml.rpc.handler.MessageContext mc) The handleRequest() method detaches attachments from the SOAPMessage and sets a static ThreadLocal variable named JAXRPCServerAttachmentHandler.requestAttachmentList to a List of AttachmentDescriptor Objects, one for each attachment.
boolean	handleResponse(javax.xml.rpc.handler.MessageContext mc) Add attachments to the response SOAPMessage and, optionally, add attachment header entries to the SOAPHeader.

Methods inherited from class org.osesb.connectors.jaxrpc.JAXRPCHandlerBase

enabled, getBooleanInitializationParameter, getDebugFlag, getHeaders, getInitializationParameter, getIntegerInitializationParameter, getLongInitializationParameter, getName, getStringInitializationParameter, handleException, init, requestEnabled, responseEnabled

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

thisClassName

protected static java.lang.String thisClassName

The full name of this class.

Constructor Detail

JAXRPCServerAttachmentHandler

public JAXRPCServerAttachmentHandler()

Method Detail

handleRequest

public boolean handleRequest(javax.xml.rpc.handler.MessageContext mc)
                      throws javax.xml.rpc.JAXRPCException

The handleRequest() method detaches attachments from the SOAPMessage and sets a static ThreadLocal variable named JAXRPCServerAttachmentHandler.requestAttachmentList to a List of AttachmentDescriptor Objects, one for each attachment. Then, the service end point can call the static method JAXRPCServerAttachmentHandler.getRequestAttachmentList() to retrieve the AttachmentDescriptor(s).

The List of AttachmentDescriptor(s) is meant to be processed by the service end point, which "know" how to dispose of the attachments. In other words, handleRequest() takes care of the mechanics of detachment but not the application-specific disposition of the attachments.

Specified by:

handleRequest in interface javax.xml.rpc.handler.Handler

Overrides:

handleRequest in class JAXRPCHandlerBase

Parameters:

mc - The MessageContext, which provides access to the SOAP message that is processed by this handler.

Returns:

Return true to indicate continued processing of the request handler chain, including the target service endpoint. Return false to indicate blocking of the request handler chain. In this case, further processing of the request handler chain is blocked and the target service endpoint is not dispatched.

Throws:

javax.xml.rpc.JAXRPCException - indicates a handler-specific runtime error. If JAXRPCException is thrown by a handleRequest method, the HandlerChain terminates the further processing of this handler chain. On the server side, the HandlerChain generates a SOAP fault that indicates that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to a runtime error during the processing of the message. On the client side, the exception is propagated to the client code

javax.xml.rpc.soap.SOAPFaultException - indicates a SOAP fault. The Handler implementation class has the responsibility of setting the SOAP fault in the SOAP message in either handleRequest and/or handleFault method. If SOAPFaultException is thrown by a server-side request handler's handleRequest method, the HandlerChain terminates the further processing of the request handlers in this handler chain and invokes the handleFault method on the HandlerChain with the SOAP message context. Next, the HandlerChain invokes the handleFault method on handlers registered in the handler chain, beginning with the Handler instance that threw the exception and going backward in execution. The client-side request handler's handleRequest method should not throw the SOAPFaultException.

handleResponse

public boolean handleResponse(javax.xml.rpc.handler.MessageContext mc)
                       throws javax.xml.rpc.JAXRPCException

Add attachments to the response SOAPMessage and, optionally, add attachment header entries to the SOAPHeader.

The service end point, invokes any of the static addResponseAttachmentXXX() methods to specify attachments that handleResponse() should add to the response SOAPMessage.

Specified by:

handleResponse in interface javax.xml.rpc.handler.Handler

Overrides:

handleResponse in class JAXRPCHandlerBase

Parameters:

mc - The MessageContext, which provides access to the SOAP message that carries the RPC response that is processed by this handler.

Returns:

Return true to indicate continued processing of the response handler chain. The handler-chain invokes the handleResponse method on the next Handler in the handler chain. Return false to indicate blocking of the response handler chain. In this case, no other response handlers in the handler chain are invoked.

Throws:

javax.xml.rpc.JAXRPCException - indicates a handler specific runtime error. If JAXRPCException is thrown by a handleResponse method, the HandlerChain terminates the further processing of this handler chain. On the server side, the HandlerChain generates a SOAP fault that indicates that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to a runtime error during the processing of the message. On the client side, the runtime exception is propagated to the client code.

getRequestAttachmentList

public static java.util.List getRequestAttachmentList()

Return requestAttachmentList, which is a ThreadLocal variable that is set to to a List of AttachmentDescriptor Objects, one for each attachment that was detached from the SOAPMessage by this handler's handleRequest() method.

getRequestAttachmentList() is meant to be invoked by the service end point to retrieve attachments that were extracted from the request SOAPMessage.

requestAttachmentList is valid after handleRequest() completes and is invalid after it is retrieved using getRequestAttachmentList(). So requestAttachmentList can be retrieved once per invocation of the handler chain.

Returns:

the requestAttachmentList ThreadLocal variable.

getResponseAttachmentList

public static java.util.List getResponseAttachmentList()

responseAttachmentList is a ThreadLocal variable that holds a List of AttachmentDescriptor Objects, one for each attachment that should be added to the response SOAPMessage by this handler's handleResponse() method.

Attachments are added to responseAttachmentList using one of the addResponseAttachmentXXX methods.

responseAttachmentList is invalid after it is retrieved using getResponseAttachmentList(). So responseAttachmentList can be retrieved once per invocation of the handler chain.

Returns:

the responseAttachmentList ThreadLocal variable.

addResponseAttachments

public static void addResponseAttachments(java.io.File[] fileAttachments)
                                   throws java.lang.Exception

Add the contents of Files to the responseAttachmentList, which contains the attachments that should be added to the response SOAPMessage by this handler's handleResponse() method.

Attachment header entries are not added to the response SOAPHeader. Use the addResponseAttachments() method that takes an AttachmentDescriptor[] to add attahment header entries to the response SOAPHeader.

Parameters:

fileAttachments - A File[] of attachments to add. Each File represents a seperate attachment.

Throws:

java.lang.Exception - If any File in fileAttachments cannot be read into a byte[].

addResponseAttachments

public static void addResponseAttachments(java.io.InputStream[] streamAttachments)
                                   throws java.lang.Exception

Add the contents of InputStreams to the responseAttachmentList, which contains the attachments that should be added to the response SOAPMessage by this handler's handleResponse() method.

All InputStream(s) are closed after being read.

Attachment header entries are not added to the response SOAPHeader. Use the addResponseAttachments() method that takes an AttachmentDescriptor[] to add attahment header entries to the response SOAPHeader.

Parameters:

streamAttachments - A InputStream[] of attachments to add to the Call object. Each InputStream represents a seperate attachment.

Throws:

java.lang.Exception - If any InputStream in streamAttachments cannot be read into a byte[].

addResponseAttachment

public static void addResponseAttachment(byte[] bytes)
                                  throws java.lang.Exception

Add a byte[] as an attachment to the to the responseAttachmentList, which contains the attachments that should be added to the response SOAPMessage by this handler's handleResponse() method.

Attachment header entries are not added to the response SOAPHeader. Use the addResponseAttachments() method that takes an AttachmentDescriptor[] to add attahment header entries to the response SOAPHeader.

Parameters:

bytes - A byte[] that holds the contents of a single attachment.

Throws:

java.lang.Exception - If byte[] is null or empty.

addResponseAttachments

public static void addResponseAttachments(AttachmentDescriptor[] attachmentDescriptors)
                                   throws java.lang.Exception

Add attachments to the to the responseAttachmentList, where attachment properties and contents are specified as org.osesb.connectors.jaxrpc.attachments.AttachmentDescriptor(s).

responseAttachmentList contains the attachments that should be added to the response SOAPMessage by this handler's handleResponse() method.

AttachmentDescriptor properties are added as Attachment header entries to the response SOAPHeader for each AttachmentDescriptor whose generateAttachmentDescriptor property is true.

Parameters:

attachmentDescriptors - An AttachmentDescriptor[] where each AttachmentDescriptor specifies the contents and properties of a single attachment.

Throws:

java.lang.Exception - If any AttachmentDescriptor is null.