progress.message.jclient
Interface XMLMessage

All Superinterfaces:

Message, TextMessage

public interface XMLMessage
extends TextMessage

A XML Message is an extention of the TextMessage and is used to send a message containing XML text in a java.lang.StringBuffer. TextMessage inherits from Message and adds a text message body. XMLMessage allows access to the XML text's Document Object Model (DOM).

The inclusion of this message type is based on the fact that XML will likely become a popular mechanism for representing content of all kinds including the content of JMS messages.

When a client receives a XMLMessage, it is in read-only mode. If a client attempts to write to the message at this point, a javax.jms.MessageNotWriteableException is thrown. If clearBody is called, the message can now be both read from and written to.

The key issues with this class relate to the fact that the message content can be accessed via get/setText or get/setDocument. To avoid having to parse the message every time it is set, we want to invoke the parser (XML to DOM) and the streamer (DOM to XML) as little as possible. It should also be possible for a user to set the XML with setText() directly even if the default parser might fail for some reason. That is, the sender can setText() and the receiver can getText() and no-one knows that the message is "invalid" XML (as far as the parser is concerned).

It is also possible to use the setDocument method with any object that implements org.w3c.dom.Document even if it is not created with the default parser.

The following cases will apply to the parsing and streaming of XML and DOM's.

setDocument()

Internal DOM is set, but internal text is undefined until developer either publishes the message, or explicitly calls getText().

setText()

Internal text is set, but internal Document (DOM) is undefined until developer calls getDocument(). If getDocument() is never called, the message will not be parsed.

Version:

1.0 17-Mar-99

Author:

Tim Bemis, Bill Wood, Jacques Bargiel

See Also:

BytesMessage, MapMessage, Message, ObjectMessage, StreamMessage, TextMessage, StringBuffer

Field Summary

Fields inherited from interface javax.jms.Message

DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE

Fields inherited from interface javax.jms.Message

DEFAULT_DELIVERY_MODE, DEFAULT_PRIORITY, DEFAULT_TIME_TO_LIVE

Method Summary

org.w3c.dom.Document	getDocument() This method will return an org.w3c.dom.Document object created from the XMLMessage contents.
java.lang.String	getDocumentBuilderFactory() Gets the class name for the implementation of JAXP1.1 DocumentBuilderFactory interface.
org.xml.sax.InputSource	getSAXInputSource() This method will return an org.xml.sax.InputSource object created from the XMLMessage contents.
java.lang.String	getSAXParserFactory() Gets the class name for the implementation of JAXP1.1 SAXParserFactory interface.
boolean	isNamespaceAware() Method for checking whether or not the underlying javax.xml.parsers.DocumentBuilderFactory used when getDocument() is called is namespace aware
void	setDocument(org.w3c.dom.Document aDoc) This method accept an org.w3c.dom.Document and stores it as the internal document for this message.
void	setDocumentBuilderFactory(java.lang.String classname) Sets the class name for the implementation of JAXP1.1 DocumentBuilderFactory interface.
void	setNamespaceAware(boolean aware) Set whether or not the underlying javax.xml.parsers.DocumentBuilderFactory used to generate org.w3c.dom.Document returned by XMLMessage.getDocument() is namespace aware.
void	setSAXParserFactory(java.lang.String classname) Sets the class name for the implementation of JAXP1.1 SAXParserFactory interface.

Methods inherited from interface progress.message.jclient.Message

acknowledgeAndForward, acknowledgeAndForward, getBodySize, getChannel, getDestinationProperty, getProperties, hasChannel, isDestinationProperty, setChannel, setChannel, setDestinationProperty

Methods inherited from interface javax.jms.Message

acknowledge, clearBody, clearProperties, getBooleanProperty, getByteProperty, getDoubleProperty, getFloatProperty, getIntProperty, getJMSCorrelationID, getJMSCorrelationIDAsBytes, getJMSDeliveryMode, getJMSDestination, getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered, getJMSReplyTo, getJMSTimestamp, getJMSType, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, propertyExists, setBooleanProperty, setByteProperty, setDoubleProperty, setFloatProperty, setIntProperty, setJMSCorrelationID, setJMSCorrelationIDAsBytes, setJMSDeliveryMode, setJMSDestination, setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered, setJMSReplyTo, setJMSTimestamp, setJMSType, setLongProperty, setObjectProperty, setShortProperty, setStringProperty

Methods inherited from interface javax.jms.TextMessage

getText, setText

Methods inherited from interface javax.jms.Message

acknowledge, clearBody, clearProperties, getBooleanProperty, getByteProperty, getDoubleProperty, getFloatProperty, getIntProperty, getJMSCorrelationID, getJMSCorrelationIDAsBytes, getJMSDeliveryMode, getJMSDestination, getJMSExpiration, getJMSMessageID, getJMSPriority, getJMSRedelivered, getJMSReplyTo, getJMSTimestamp, getJMSType, getLongProperty, getObjectProperty, getPropertyNames, getShortProperty, getStringProperty, propertyExists, setBooleanProperty, setByteProperty, setDoubleProperty, setFloatProperty, setIntProperty, setJMSCorrelationID, setJMSCorrelationIDAsBytes, setJMSDeliveryMode, setJMSDestination, setJMSExpiration, setJMSMessageID, setJMSPriority, setJMSRedelivered, setJMSReplyTo, setJMSTimestamp, setJMSType, setLongProperty, setObjectProperty, setShortProperty, setStringProperty

Method Detail

getDocument

org.w3c.dom.Document getDocument()
                                 throws JMSException

This method will return an org.w3c.dom.Document object created from the XMLMessage contents. This will allow the client application to access the contents using the DOM-tree functionality.

Returns:

the org.w3c.dom.Document object associated with the message.

Throws:

JMSException - if JMS fails to create this message due to some internal error.

setDocument

void setDocument(org.w3c.dom.Document aDoc)
                 throws JMSException

This method accept an org.w3c.dom.Document and stores it as the internal document for this message. The message content is emptied but will be generated when the message is sent.

Parameters:

aDoc - A standard org.w3c.dom.Document object.

Throws:

JMSException - if JMS fails to create this message due to some internal error.

MessageNotWriteableException - if message in read-only mode.

getDocumentBuilderFactory

java.lang.String getDocumentBuilderFactory()

Gets the class name for the implementation of JAXP1.1 DocumentBuilderFactory interface. This is the DocumentBuilderFactory class name set before either by calling setDocumentBuilderFactory(classname) or by setting the System property "javax.xml.parsers.DocumentBuilderFactory".

Returns:

the name of the implementation class.

setDocumentBuilderFactory

void setDocumentBuilderFactory(java.lang.String classname)

Sets the class name for the implementation of JAXP1.1 DocumentBuilderFactory interface. This can be used by developers who want to override the the default implementation of the parser factory which is based on Apache Xerces package.

This method cannot be called after any of the DOM-related methods (e.g. getDocument()) has been called on the XMLMessage as these methods automatically force the use of the previously set classname.

Parameters:

classname - the name of the implementation class.

getSAXParserFactory

java.lang.String getSAXParserFactory()

Gets the class name for the implementation of JAXP1.1 SAXParserFactory interface. This is the SAXParserFactory class name set before either by calling setSAXParserFactory(classname) or by setting the System property "javax.xml.parsers.SAXParserFactory".

Returns:

the name of the implementation class.

setSAXParserFactory

void setSAXParserFactory(java.lang.String classname)
                         throws JMSException

Sets the class name for the implementation of JAXP1.1 SAXParserFactory interface. This can be used by developers who want to override the the default implementation of the parser factory which is based on Apache Xerces package.

This method cannot be called after any of the SAX-related methods (e.g. getSAXInputSource()) has been called on the XMLMessage as these methods automatically force the use of the previously set classname.

Parameters:

classname - the name of the implementation class.

Throws:

JMSException

getSAXInputSource

org.xml.sax.InputSource getSAXInputSource()
                                          throws JMSException

This method will return an org.xml.sax.InputSource object created from the XMLMessage contents. This will allow the client application to access the contents using the SAX functionality.

Returns:

the org.xml.sax.InputSource object associated with the message.

Throws:

JMSException - if JMS fails to create this message due to some internal error.

setNamespaceAware

void setNamespaceAware(boolean aware)

Set whether or not the underlying javax.xml.parsers.DocumentBuilderFactory used to generate org.w3c.dom.Document returned by XMLMessage.getDocument() is namespace aware.

Parameters:

aware - boolean toggle to enable/disable namespace awareness

isNamespaceAware

boolean isNamespaceAware()

Method for checking whether or not the underlying javax.xml.parsers.DocumentBuilderFactory used when getDocument() is called is namespace aware

Returns:

boolean true if parser is namespace aware, false otherwise.