XDDocument

In this section:

An XDDocument is the carrier of the message being processed. Documents usually hold XML messages, but can be set to flat mode to hold byte arrays or strings.

During the message life cycle in iWay Service Manager, it is first read from a protocol, then passed to a preparser if any is defined. Once past the preparser, an XDDocument is immediately created to carry the message through the remainder of the system. Documents can be moved from one XDDocument to another, for example, a business processing agent performs some operation on the incoming XDDocument and loads the results into an outgoing XDDocument.

The XDDocument carrying the final state of the document is passed to the emitter to be carried from the system to its destination.

The XDDocument carries XML messages as a tree of XDNodes, described below. The XDDocument itself provides some convenience methods for interacting with the tree. A full node and tree manipulation API is provided by the XDNode class itself.

SOAP business agents are identical to regular business agents. The system properly handles the envelope. The getRoot() method of the document deals only with the payload.

XDDocuments always hold a reference to the listener under which they function. This enables document operations to properly handle I18N considerations and to obtain other configuration information that may be needed. Therefore, never use the empty constructor when creating your own XDDocument. Always use the constructor that accepts an XXMaster, XDWorker, and so on. In any exit, you can accomplish this by entering:

XDDocument d = new XDDocument(this);

The document provides a variety of useful methods.

XDDocument Methods

Method

Description

addLine

Adds a data line to a flat document.

addPreEmitter

Adds a preemitter to the document.

addReplyTo

Adds one destination to an output document.

addSibling

Adds a preconstructed document as a sibling of this document. Can be a standard document (one containing an XML tree) or a flat document that holds non-XML.

copyTo

Copies the data (tree or flat data) from the document to an output document.

createSiblingDocument

Creates a new document that is a sibling of this document. The sibling document can carry a different tree and have different destination addresses. During output, all output document siblings are sent. This method allows a business agent to produce multiple outputs.

findByName

Locates a subtree within the document tree. This method is provided for convenience, and a full complement of tree manipulation methods are provided by the XDNode interface.

flatten

Flattens the tree in the document to a string.

getEncoding

Returns the IANA encoding for this document.

getJavaEncoding

Returns the Java encoding for this document. Usually this is the same as the IANA encoding.

getRoot

Returns the root of an XDNode tree that is the basis of the document.

isFlat

Returns true if this is a flat document, false if this is an XML document.

moveTree

Moves the payload from an input document to an output document. The payload can be XML or flat.

printTree

Flattens the tree in the document to a string with embedded carriage returns. This is useful only for tracing. If the document is large or supports staging, a truncated tree may be generated.

resetPreEmitters

Eliminates all associated preemitters.

setEncoding

Sets the IANA encoding for this document. Internal tables attempt to determine the appropriate Java encoding.

setFlat

Sets the document to flat or XML.

setInError

Sets the document error state. Any emit is sent to the errorTo address, if available.

setReplyTo

Adds a reply destination. Any single XDDocument can hold one or more reply addresses, and each sibling document can hold its own unique set of addresses.

setRoot

Sets the root of an XDNode tree as the basis of the document.

xnode

Returns a list of nodes meeting the XPATH expression passed as a parameter. The expression is supported as a selector into the current document, and does not support the full XPATH syntax.

Documents can carry non-XML information. This can be string or byte arrays. The form of the document is determined by the type of data stored; the flatten() routines always convert the contents to displayable form for tracing. Non-XML documents carry information between channel components just as do XML documents.


Top of page

x
Controlling Listeners From Exits

It is possible to control listener activity from exits. Control can be accomplished by posting a message to a listener using postMessage.

Messages that can be posted are:

Message

Description

ACTIVATE

Starts the listener if it is in STOP or PASSIVE state.

STOP

Stops the listener. This is the equivalent of using the stop command from the console. Any outstanding messages are completed before the stop takes effect.

PASSIVATE

Listener stops accepting messages, although it remains active. The listener continues to check for a STOP request.

PULSE

Listener in PASSIVE state accepts one cycle of messages and reenters PASSIVE state. This is not supported by all listeners.

The XDControlAgent exposes these messages to the agent flow. However, you can issue them from your own code as needed. Users are strongly cautioned that use of posted messages can seriously affect performance and can get the system "out of state" in a way that is hard to debug.


Top of page

x
Sibling Documents

Siblings are subdocuments associated with the document being processed. A sibling is created by an exit, which is responsible for setting any emit parameters and values into the document. Once created, the sibling is carried through the processing stream by the host document to which it is attached.

When a host document reaches the end of the processing flow, each sibling is individually emitted. Although siblings can have siblings, and any document can have any number of siblings, there is no logic currently applied to the position of the document in the sibling "tree"; each is treated individually in the order accessed.

Use of siblings is rare – the most common use is to create documents for emit that require different preemitters yet are created during the main document life cycle.

Siblings do not automatically inherit the attributes of the document to which they are applied. Attribute inheritance can be accomplished by creating a document and adding it as a sibling of the exit output document.

XDDocument ed = new XDDocument(this,inDoc);
ed.setRoot(<what I want emitted>);
outDoc.addSibling(ed);

Alternately, you might create a document and add your own errorTo or replyTo addresses using the appropriate XDDocument method calls.

A convenient use of siblings is to send error messages to one destination and the document to another. In such a case, set the new sibling error state to true via setInError(true). When the main document is emitted, the sibling is emitted to the errorTo address(es).

A process flow provides an iterator that can send each sibling through subsequent processing steps. The iterator “breaks” the sibling relationship, enabling the flow to work with each sibling as an individual document.


Top of page

x
Making Error Documents

Two convenience classes are provided to assist in construction of error documents. These documents are emitted to the errorTo address(es). The first, XDErrorDocument, constructs a standard error document carrying, where possible, the original input in the <data> section of the document. The second, XDUEDocument, sets the data section of the error document to the contents of the document passed in as a template. These classes extend XDDocument, and may assist you in creating standard error documents; there is no requirement to create error documents by this approach.

The following code example constructs an error document and passes it plus the payload contents of the template document on for further action. The payload is carried in the <data> section of the error document in a form appropriate to the type of payload being carried.

public String execute(XDDocument docIn, XDDocument docOut) throws XDException
{
   // sample for copy process only; remove this and insert your code here
   copyTree(docIn, docOut);
   XDNode enode = new XDNode("testerror");
   docIn.setRoot(enode); // add my error tree, use docin for convenience
   XDUEDocument ed = new XDUEDocument(
     getWorker(), // link into this flow
     docIn, // source of addresses and data (model)
     XDUEDocument.PIPE_AGENT, //flow position of error
     "test", // actual source of error
     null, // additional attributes to include
     -222, // my error code
     "This is error string"); //my error description
   docOut.addSibling(ed); // chain to main document
   return "success";
}

To reprocess the contents of the error document, you can configure the ErrorFilter to extract the contents of the <data> portion of the standard error document and pass it on through the system.


Top of page

x
Document Attachments

XDDocuments provide methods for conveniently working with attachments. These methods enable an exit or protocol component to:

Attachments can optionally be carried by both XML and flat documents. That is, all operations on the document content continue to work; the extra payload is carried with the document, and is copied from document to document during exit chaining and process flows. When the document is emitted, the standard multipart preemitter, if configured, emits the attachment part ignoring the XML or flat content. You can easily write a preemitter that mixes the two, depending upon your application needs. Conditional routing services apply to the carried document XML payload, and do not respect attachments carried along by the document.

Multipart documents reaching a listener are parsed by the provided multipart preparser, and the attachments are made available to the XDDocument API as discussed in this section. The API presumes that an incoming multipart document has been preparsed by the multipart preparser, although you can add attachments to any document. If you do not parse an incoming multipart document with the provided preparser, the incoming attachments are not available to the attachment API.

Details of the API are discussed in the provided Javadoc.

The API supports several methods:

Method

Description

addAttachment

Adds one attachment to the document, which has been prepared by the openMultiPart() call. You provide a name, headers, and the content data.

closeMultiPart

Finalizes any added attachments. Failure to call this method results in the loss of added attachments, and possibly unpredictable contents of the document.

getAttachmentBytes

Returns a byte array of the contents of the attachment.

getAttachmentCount

Returns the number of attachments. A document with no attachments returns 0.

getAttachmentHeaders

Returns a map of the headers for a specific attachment. All header keys are returned as lowercase.

openMultiPart

Preparses the document to receive new attachments. These can be added to a document with no attachments, or to one that already has attachments.

You need to call openMultiPart only to manipulate attachments, and not to get attachments.

When adding an attachment, the header map should contain all information needed to process the attachment, which varies by MIME type. You must include the content-type header. Handlers are provided for most of the standard types.

The following code example, taken from an exit, adds an attachment to a document, and then retrieves the attachment.

try
 {
    int count = doc.openMultiPart();  /* get the count of current attachments */
    Map headers = new HashMap(4);
    headers.put("content-type","text/plain");   /* set the content type */
    docOut.addAttachment("Attach"+(count+1), headers,
                        ("Attachment data "+count).getBytes());
    count = doc.closeMultiPart();
    byte[] in = doc.getAttachmentBytes(count-1);
    debug("got back '"+new String(in)+"'");
 }
 catch (Throwable t)
 {
    throw new XDException(t);
 }

This example should return the text of the added attachments. Naturally, there is no limit to the number of attachments inserted into a document that has been opened for multipart operations.

An iWay Service Manager tool, CreateMultipart, is provided to help you construct test documents. For more information, see Supplied Tools.


iWay Software