org.apache.tsik.messaging
Class MessageProvider

java.lang.Object
  org.apache.tsik.messaging.MessageProvider

public class MessageProvider

extends Object

Performs message-specific processing needed by a transport, and is typically provided by the web service API. The XmlRequest.getProvider() method returns the provider that will be used by a transport for processing that request message and its response message.

Subclasses, which are implemented as part of a web service API, should normally provide two static methods for getting and setting the default provider for a given web service:

 public static MessageProvider getDefaultProvider() {
     ...
 }
 public static void setDefaultProvider(MessageProvider defaultProvider) {
     ...
 } 

getDefaultProvider is then normally called by the constructor of each request class in the web service API, and this value is passed to AbstractRequest.AbstractRequest(org.apache.tsik.messaging.MessageProvider). Applications may call setDefaultProvider to change the provider that is used.

Field Summary

static XPath	LAST_CHILD_XPATH The common location for a response signature is represented by this XPath expression: /*/*[last()].
static XPath	ROOT_ELEMENT_XPATH The common location for a request signature is represented by this XPath expression: /*.

Constructor Summary

MessageProvider()

Method Summary

void	checkTransport(XmlTransport transport, XmlRequest request) Checks whether the transport is valid for sending the given request, and throws an exception if message processing should not proceed.
TrustVerifier	getDefaultTrustVerifier() Returns the default TrustVerifier for this provider.
boolean	getRequestSignatureInsertBefore(Document request) Returns true if the sigature is to be inserted before the XPath location of the request signature, or false if the signature is to be appended as the last child of the XPath location.
XPath	getRequestSignatureLocation(Document request) Returns the XPath location of the context element for inserting the XML Signature in the body of the request message.
XPath	getResponseSignatureLocation(Document response) Returns the XPath location of the XML Signature element in the body of the response message.
Document[]	getSchemaDocuments() Returns the schema documents that can be used to validate the request and response messages.
Document	getXML(XmlRequest request) Obtains the XML representation of a service request.
XmlResponse	makeResponse(XmlRequest request, Document response) Makes the response object for a given response document.

Methods inherited from class java.lang.Object

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

Field Detail

ROOT_ELEMENT_XPATH

public static final XPath ROOT_ELEMENT_XPATH

The common location for a request signature is represented by this XPath expression: /*.

LAST_CHILD_XPATH

public static final XPath LAST_CHILD_XPATH

The common location for a response signature is represented by this XPath expression: /*/*[last()].

Constructor Detail

MessageProvider

public MessageProvider()

Method Detail

checkTransport

public void checkTransport(XmlTransport transport,
                           XmlRequest request)
                    throws XmlMessageException,
                           InsecureTransportException

Checks whether the transport is valid for sending the given request, and throws an exception if message processing should not proceed. For example, if XmlTransportSecurity.isTransportPrivate() returns false and the provider requires privacy, InsecureTransportException should be thrown.

The default implementation of this method does nothing.

Parameters:

transport - TODO.

request - TODO.

Throws:

XmlMessageException - TODO.

InsecureTransportException - TODO.

getDefaultTrustVerifier

public TrustVerifier getDefaultTrustVerifier()

Returns the default TrustVerifier for this provider. If a TrustVerifier is associated with the transport, it will override the default verifier.

The default implementation of this method returns an AllPermissiveTrustVerifier. This method should normally be overridden in subclases.

Returns:

the default verifier or null if the response should not be verified by default.

getRequestSignatureLocation

public XPath getRequestSignatureLocation(Document request)

Returns the XPath location of the context element for inserting the XML Signature in the body of the request message. This method is only called by transports that support message signing, and only when the signature is located in the body of the message. The getRequestSignatureInsertBefore(org.w3c.dom.Document) method determines whether the signature is inserted before this element or appended as the last child of this element.

The default implementation of this method returns null. This may be overridden in subclases.

Parameters:

request - is the request document to which the signature will be added.

Returns:

the XPath location of the context element, or null if a Signature in the message body is not allowed.

getRequestSignatureInsertBefore

public boolean getRequestSignatureInsertBefore(Document request)

Returns true if the sigature is to be inserted before the XPath location of the request signature, or false if the signature is to be appended as the last child of the XPath location. This method is only called by transports that support message signing, and only when the signature is located in the body of the message. The getRequestSignatureLocation(org.w3c.dom.Document) method determines the XPath location of the context element.

The default implementation of this method returns false. This may be overridden in subclases.

Parameters:

request - is the request document to which the signature will be added.

Returns:

true if the signature is to be inserted before the context element, or false if the signature is to be appended as the last child of the context element.

getResponseSignatureLocation

public XPath getResponseSignatureLocation(Document response)

Returns the XPath location of the XML Signature element in the body of the response message. This method is only called by transports that support message signing, and only when the signature is located in the body of the message.

The default implementation of this method returns null. This may be overridden in subclases.

Parameters:

response - is the response message containing a signature.

Returns:

the XPath location of the XML Signature element, or null if a Signature in the message body is not allowed.

getSchemaDocuments

public Document[] getSchemaDocuments()
                              throws XmlMessageException

Returns the schema documents that can be used to validate the request and response messages. This method is only called by transports that perform schema validation.

The default implementation of this method returns null. This may be overridden in subclases.

Returns:

the array of schema documents, or null if no schema is available.

Throws:

XmlMessageException - TODO.

getXML

public Document getXML(XmlRequest request)
                throws XmlMessageException

Obtains the XML representation of a service request. The standard message signature is not included in the XML returned by this method, since the signature is added by the transport layer. This method should normally be called only by the XmlTransport.

The default implementation of this method returns XmlRequest.getXML(). This may be overridden in subclases.

Parameters:

request - of the request object.

Returns:

the XML form of the request object.

Throws:

XmlMessageException - is thrown if an error occurs when generating the XML for the request. Subclasses of MessageProvider should normally throw a subclass of XmlMessageException.

makeResponse

public XmlResponse makeResponse(XmlRequest request,
                                Document response)
                         throws XmlMessageException

Makes the response object for a given response document. This method should normally be called only by the XmlTransport.

The default implementation of this method returns XmlRequest.makeResponse(org.w3c.dom.Document). This may be overridden in subclases.

Parameters:

request - of the request object.

response - is the response document returned by the service.

Returns:

the response object produced from the given response document.

Throws:

XmlMessageException - is thrown if an error occurs when generating the response. Subclasses of MessageProvider should normally throw a subclass of XmlMessageException.