org.osesb.msgrouting
Class BrokerErrorMessage

java.lang.Object
  org.osesb.msgrouting.BrokerErrorMessage

public class BrokerErrorMessage
extends java.lang.Object

Ancestor for BrokerErrorMessage(s).

A BrokerErrorMessage is returned to the service requestor by a transport handler when an exception occurs during message processing and the requestor expects a reply.

See the org.osesb.transporthandlers package in the transport-handlers module.

A standard broker error message XML looks like:

<err:brokerError xmlns:err="http://www.osesb.org/brokerError">
         <dateTime>24 Feb 2007 04:22:02</dateTime>
         <exceptionClassification>testException</exceptionClassification>
         <relatesToMessageType namespaceURI="www.osesb.org" localPart="testMessage" />
         <relatesToMessageID>1234</relatesToMessageID>
         <errorMessage>org.osesb.messagepipeline.PipelineStageException:
           exceptionClassification: testException
           pipelineName: testMessagePipeline
           pipelineConfigFile: org/osesb/messagepipeline/test/testdata/message-pipeline-test-config.xml
           pipelineStageName: JMSClientPipelineStage-asynch
           pipelineStageConfigFile: org/osesb/messagepipeline/test/testdata/jmssender-pipeline-stage-aynch-test-config.xml
           pipelineStageClassName: org.osesb.messagepipeline.builtinstages.JMSClientPipelineStage
           EAIMessage messageType: {www.osesb.org}testMessage
           exceptionMessage: org.osesb.messagepipeline.builtinstages.JMSClientPipelineStage.runStage(): Exception sending JMS Message with the contents of the EAIMessage. Exception: This is a test PipelineStageException.</errorMessage>
       </err:brokerError>
 

This class encapsulates the properties that compose a BrokerErrorMessage and includes the following operative methods:

• toXML() constructs XML representation for a BrokerErrorMessage. toXML() is invoked by transport handlers to return broker error messages to service requestors.
• isBrokerErrorMessage() tests that the given XML is a BrokerErrorMessage. isBrokerErrorMessage() is invoked by clients to test if a returned message is a broker error message.
• fromXML() constructs a BrokerErrorMessage object from broker error XML. fromXML() is invoked by clients to obtain a java representation of broker error XML.

BrokerErrorMessage includes standard properties and extended properties. Standard properties are common to all BrokerErrorMessage(s). Extended properties are used to extend BrokerErrorMessage with properties that are message-conversation specific. For example, a 'purchaseNumber' property could be used to associate a BrokerErrorMessage with a purchase order submission. Extended properties are set using the setExtendedProperty() method.

Standard BrokerErrorMessage properties are set using accessor methods. Standard BrokerErrorMessage properties are:

• exceptionClassification is meant to be used by osesb error handling especially at it relates to the disposition of a PipelineStageException. exceptionClassification should be one of: 1) PipelineStageException.businessProcessException, 2) PipelineStageException.applicationException, 3) PipelineStageException.testException
• errorMessage is the error message descriptive text. Typically, this is set by transport handlers as the PipelineStageException that is the root cause of the error.
• relatesToMessageType is a QName representing the message type of the message that was sent to osESB that a BrokerErrorMessage relates to.
• relatesToMessageID is the message ID of the message that was sent to the broker that a BrokerErrorMessage relates to.
• errorTimestampFormat is the format for the timestamp element in the XML generated by toXML(). The timestamp format defaults to DateTimeConversionUtility.DEFAULT_TIMESTAMP_FORMAT.

Since:

Version .9

Field Summary

protected static java.lang.String	BROKER_ERRORMESSAGE_NAMESPACEPREFIX The default namespace prefix for the XML error message generated by BrokerErrorMessage#toXML().
protected static java.lang.String	BROKER_ERRORMESSAGE_NAMESPACEURI The default namespaceURI for the XML error message generated by BrokerErrorMessage#toXML().
protected static java.lang.String	BROKER_ERRORMESSAGE_ROOTTAGNAME The default tagName for the root Element of the XML generated by BrokerErrorMessage#toXML().
protected java.lang.String	errorMessage The error message for this BrokerErrorMessage.
protected java.util.Date	errorMessageCreateDateTime A Date object representing the date-time that the BrokerErrorMessage was created.
protected java.lang.String	errorTimestampFormat The format for the timestamp element in the XML generated by toXML().
protected java.lang.String	exceptionClassification A classification for the BrokerErrorMessage.
protected java.lang.String	relatesToMessageID This is the message ID of the message that was sent to osESB that this BrokerErrorMessage relates to.
protected javax.xml.namespace.QName	relatesToMessageType The message type of the message that was sent to the broker that this BrokerErrorMessage relates to.
protected static java.util.Map	standardPropertyNames fromXML() must distinguish between standard BrokerErrorMessage properties and extended properties.
protected java.lang.String	thisClassName The full name of this class.

Constructor Summary

BrokerErrorMessage(java.lang.String errorMessage)
Construct instance of BrokerErrorMessage.

Method Summary

static BrokerErrorMessage	fromXML(java.lang.String brokerErrorXML) Creates a new BrokerErrorMessage object from the given broker error XML, which looks like:
java.lang.String	getErrorMessage() Return the error message for this BrokerErrorMessage.
java.util.Date	getErrorMessageCreateDateTime() Get the Date object representing the date-time that the BrokerErrorMessage was created.
java.lang.String	getErrorTimestampFormat() Get the timestamp format for the XML error message generated by toXML().
java.lang.String	getExceptionClassification() Get the classification for the BrokerErrorMessage.
java.util.Properties	getExtendedProperties() Return the extended Properties for this BrokerErrorMessage.
java.lang.String	getExtendedProperty(java.lang.String propertyName) Return an extended Property by name.
java.lang.String	getRelatesToMessageID() Get the message ID of the originating message that was sent to osESB that this BrokerErrorMessage relates to.
javax.xml.namespace.QName	getRelatesToMessageType() Get the message type (QName) of the originating message that was sent to osESB that this BrokerErrorMessage relates to.
static boolean	isBrokerErrorMessage(java.lang.String xmlText) Returns true if the given XML is broker error message XML.
static void	main(java.lang.String[] args) main(): For testing and sandboxing.
void	setErrorTimestampFormat(java.lang.String errorTimestampFormat) Set the timestamp format for the XML error message generated by toXML().
void	setExceptionClassification(java.lang.String exceptionClassification) Set the classification for the BrokerErrorMessage.
void	setExtendedProperties(java.util.Properties extendedProperties) Set the extended Properties for this BrokerErrorMessage.
void	setExtendedProperty(java.lang.String propertyName, java.lang.String propertyValue) Set an extended Property by name.
void	setRelatesToMessageID(java.lang.String relatesToMessageID) Set the message ID of the originating message that was sent to osESB that this BrokerErrorMessage relates to.
void	setRelatesToMessageType(javax.xml.namespace.QName relatesToMessageType) Set the message type (QName) of the originating message that was sent to osESB that this BrokerErrorMessage relates to.
java.lang.String	toXML() Generates a broker XML error message from this BrokerErrorMessage that looks like:

Methods inherited from class java.lang.Object

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

Field Detail

thisClassName

protected java.lang.String thisClassName

The full name of this class.

exceptionClassification

protected java.lang.String exceptionClassification

A classification for the BrokerErrorMessage.

exceptionClassification is meant to be used by osESB error handling especially at it relates to the disposition of the PipelineStageException.

exceptionClassification should be one of:

• PipelineStageException.businessProcessException
• PipelineStageException.applicationException
• PipelineStageException.testException

errorMessage

protected java.lang.String errorMessage

The error message for this BrokerErrorMessage.

relatesToMessageType

protected javax.xml.namespace.QName relatesToMessageType

The message type of the message that was sent to the broker that this BrokerErrorMessage relates to.

relatesToMessageID

protected java.lang.String relatesToMessageID

This is the message ID of the message that was sent to osESB that this BrokerErrorMessage relates to.

If the originating message was sent to osESB over JMS, then this is the JMS MessageID of the JMS Message that was received by osESB.

If the originating message was sent over SOAP, then this is the value of the <wsa:MessageID> entry in the SOAPHeader of the SOAPMessage that was received by osESB.

errorMessageCreateDateTime

protected java.util.Date errorMessageCreateDateTime

A Date object representing the date-time that the BrokerErrorMessage was created.

errorTimestampFormat

protected java.lang.String errorTimestampFormat

The format for the timestamp element in the XML generated by toXML(). Defaults to DateTimeConversionUtility.DEFAULT_TIMESTAMP_FORMAT.

standardPropertyNames

protected static java.util.Map standardPropertyNames

fromXML() must distinguish between standard BrokerErrorMessage properties and extended properties. This is a Map of standard property names; Map value entries are not used.

BROKER_ERRORMESSAGE_ROOTTAGNAME

protected static java.lang.String BROKER_ERRORMESSAGE_ROOTTAGNAME

The default tagName for the root Element of the XML generated by BrokerErrorMessage#toXML().

BROKER_ERRORMESSAGE_NAMESPACEURI

protected static java.lang.String BROKER_ERRORMESSAGE_NAMESPACEURI

The default namespaceURI for the XML error message generated by BrokerErrorMessage#toXML().

BROKER_ERRORMESSAGE_NAMESPACEPREFIX

protected static java.lang.String BROKER_ERRORMESSAGE_NAMESPACEPREFIX

The default namespace prefix for the XML error message generated by BrokerErrorMessage#toXML().

Constructor Detail

BrokerErrorMessage

public BrokerErrorMessage(java.lang.String errorMessage)

Construct instance of BrokerErrorMessage.

Method Detail

toXML

public java.lang.String toXML()
                       throws java.lang.Exception

Generates a broker XML error message from this BrokerErrorMessage that looks like:

<err:brokerError xmlns:err="http://www.osesb.org/brokerError">
        <dateTime>16 Feb 2007 04:49:24</dateTime>
        <exceptionClassification>testException</exceptionClassification>
        <relatesToMessageType namespaceURI="www.osesb.org" localPart="testMessage" />
        <relatesToMessageID>1234</relatesToMessageID>
        <errorMessage>org.osesb.messagepipeline.PipelineStageException:
          exceptionClassification: testException
          pipelineName: testMessagePipeline
          pipelineConfigFile: org/osesb/messagepipeline/test/testdata/message-pipeline-test-config.xml
          pipelineStageName: JMSClientPipelineStage-asynch
          pipelineStageConfigFile: org/osesb/messagepipeline/test/testdata/jmssender-pipeline-stage-aynch-test-config.xml
          pipelineStageClassName: org.osesb.messagepipeline.builtinstages.JMSClientPipelineStage
          EAIMessage messageType: {www.osesb.org}testMessage
          exceptionMessage: org.osesb.messagepipeline.builtinstages.JMSClientPipelineStage.runStage(): Exception sending JMS Message with the contents of the EAIMessage. Exception: This is a test PipelineStageException.</errorMessage>
      </err:brokerError>
 

Throws:

java.lang.Exception - if There is a problem constructing a broker error XML Message.

fromXML

public static BrokerErrorMessage fromXML(java.lang.String brokerErrorXML)
                                  throws java.lang.Exception

Creates a new BrokerErrorMessage object from the given broker error XML, which looks like:

<err:brokerError xmlns:err="http://www.osesb.org/brokerError">
        <dateTime>16 Feb 2007 04:49:24</dateTime>
        <exceptionClassification>testException</exceptionClassification>
        <relatesToMessageType namespaceURI="www.osesb.org" localPart="testMessage" />
        <relatesToMessageID>1234</relatesToMessageID>
        <errorMessage>org.osesb.messagepipeline.PipelineStageException:
          exceptionClassification: testException
          pipelineName: testMessagePipeline
          pipelineConfigFile: org/osesb/messagepipeline/test/testdata/message-pipeline-test-config.xml
          pipelineStageName: JMSClientPipelineStage-asynch
          pipelineStageConfigFile: org/osesb/messagepipeline/test/testdata/jmssender-pipeline-stage-aynch-test-config.xml
          pipelineStageClassName: org.osesb.messagepipeline.builtinstages.JMSClientPipelineStage
          EAIMessage messageType: {www.osesb.org}testMessage
          exceptionMessage: org.osesb.messagepipeline.builtinstages.JMSClientPipelineStage.runStage(): Exception sending JMS Message with the contents of the EAIMessage. Exception: This is a test PipelineStageException.</errorMessage>
      </err:brokerError>
 

Throws:

java.lang.Exception - if There is a problem constructing a BrokerErrorMessage object from a broker error XML Message.

isBrokerErrorMessage

public static boolean isBrokerErrorMessage(java.lang.String xmlText)
                                    throws java.lang.Exception

Returns true if the given XML is broker error message XML. Tests that the root tag name is the expected tag name.

Parameters:

xmlText - The XML to test.

Returns:

true if the given XML is broker error message XML.

Throws:

java.lang.Exception - if xmlText cannot be parsed.

getErrorMessage

public java.lang.String getErrorMessage()

Return the error message for this BrokerErrorMessage.

getExceptionClassification

public java.lang.String getExceptionClassification()

Get the classification for the BrokerErrorMessage.

exceptionClassification is meant to be used by osESB error handling especially at it relates to the disposition of the PipelineStageException.

exceptionClassification should be one of:

• PipelineStageException.businessProcessException
• PipelineStageException.applicationException
• PipelineStageException.testException

setExceptionClassification

public void setExceptionClassification(java.lang.String exceptionClassification)

Set the classification for the BrokerErrorMessage.

exceptionClassification is meant to be used by osESB error handling especially at it relates to the disposition of the PipelineStageException.

exceptionClassification should be one of:

• PipelineStageException.businessProcessException
• PipelineStageException.applicationException
• PipelineStageException.testException

getRelatesToMessageType

public javax.xml.namespace.QName getRelatesToMessageType()

Get the message type (QName) of the originating message that was sent to osESB that this BrokerErrorMessage relates to.

Returns:

The message type of the originating message that was sent to osESB that this BrokerErrorMessage relates to.

setRelatesToMessageType

public void setRelatesToMessageType(javax.xml.namespace.QName relatesToMessageType)

Set the message type (QName) of the originating message that was sent to osESB that this BrokerErrorMessage relates to.

Parameters:

relatesToMessageType - The message type of the originating message that was sent to osESB that this BrokerErrorMessage relates to.

getRelatesToMessageID

public java.lang.String getRelatesToMessageID()

Get the message ID of the originating message that was sent to osESB that this BrokerErrorMessage relates to.

Returns:

The message ID of the originating message that was sent to osESB that this BrokerErrorMessage relates to.

setRelatesToMessageID

public void setRelatesToMessageID(java.lang.String relatesToMessageID)

Set the message ID of the originating message that was sent to osESB that this BrokerErrorMessage relates to.

Parameters:

relatesToMessageID - The message ID of the originating message that was sent to osESB that this BrokerErrorMessage relates to.

getErrorMessageCreateDateTime

public java.util.Date getErrorMessageCreateDateTime()

Get the Date object representing the date-time that the BrokerErrorMessage was created.

setErrorTimestampFormat

public void setErrorTimestampFormat(java.lang.String errorTimestampFormat)

Set the timestamp format for the XML error message generated by toXML().

getErrorTimestampFormat

public java.lang.String getErrorTimestampFormat()

Get the timestamp format for the XML error message generated by toXML().

getExtendedProperties

public java.util.Properties getExtendedProperties()

Return the extended Properties for this BrokerErrorMessage.

Returns:

the extended Properties for this BrokerErrorMessage.

setExtendedProperties

public void setExtendedProperties(java.util.Properties extendedProperties)

Set the extended Properties for this BrokerErrorMessage.

Parameters:

extendedProperties - The extended Properties for this BrokerErrorMessage.

getExtendedProperty

public java.lang.String getExtendedProperty(java.lang.String propertyName)

Return an extended Property by name.

Returns:

a named extended Property.

setExtendedProperty

public void setExtendedProperty(java.lang.String propertyName,
                                java.lang.String propertyValue)

Set an extended Property by name.

Parameters:

propertyName - The Property name.

propertyValue - The Property value.

main

public static void main(java.lang.String[] args)

main(): For testing and sandboxing.

Parameters:

args - commandline arguments