org.osesb.messagepipeline.builtinstages
Class DatabaseResultSetToXMLPipelineStage

java.lang.Object
  org.osesb.messagepipeline.PipelineStage
      org.osesb.messagepipeline.builtinstages.DatabaseResultSetToXMLPipelineStage

public class DatabaseResultSetToXMLPipelineStage
extends PipelineStage

DatabaseResultSetToXMLPipelineStage extends PipelineStage with a runStage() method that transforms a java.sql.ResultSet to XML. DatabaseResultSetToXMLPipelineStage is similar to DatabaseQueryToXMLPipelineStage, except that the ResultSet is created by a previous PipelineStage and passed down the MessagePipeline to an instance of DatabaseResultSetToXMLPipelineStage an an EAIObjectMessage().

Optionally, DatabaseResultSetToXMLPipelineStage can be configured with a stageConfiguration that is a org.osesb.connectors.jdbc.relationalxml.ResultSetToXMLTransformerConfiguration for a org.osesb.connectors.jdbc.relationalxml.ResultSetToXMLTransformer, which is invoked by runStage() to convert a ResultSet to XML text. If a ResultSetToXMLTransformerConfiguration is not configured, the ResultSetToXMLTransformer uses standard transformation properties.

Once the transformation is complete, runstage() will 1) set the current MessagePipeline EAIXMLMessage to the transformed XML using the setOutputMessage() method and/or 2) set a MessagePipelineContext variable to the result of the transform as XML text. This behavior is determined by the <setOutputMessageToTransformResult> and the <setContextVariableToTransformResult> PipelineStageConfiguration elements.

runStage() uses the configured ResultSetToXMLTransformer to convert the ResultSet to XML text using the a ResultSetToXMLFormat to specify formatting properties. The following table summarizes formatting properties:

JDBC ResultSet to XML conversion Properties.

Property Name	Description	Default Value
includeMetaDataHeader	If true, a column meta-data header is included as the first XML Element.	false
rootElementName	The name of the root Element.	table
namespaceURI	The namespace for the generated xml.	none
namespacePrefix	The namespace prefix for the generated xml.	none
rowElementName	The name of the repeating row Elements.	row
useColumnNameAsColumnElementName	Use the column name as the column Element name within a row Element.	true
columnElementName	The name of the repeating column Element(s) within a row Element.	none
columnElementFormat	Formatting of column data, which can be COL_FORMAT_ATTRIBUTE, COL_FORMAT_ELEMENT, or COL_FORMAT_MIXED.	COL_FORMAT_MIXED
includeColumnMetaData	If true, column meta-data is included with each column Element.	false
rootElementAttributes	Additional root Element Attributes for the generated XML specified as Properties.	none

columnElementFormat descriptions.

COL_FORMAT_ATTRIBUTE	Column meta-data and values are formatted as XML Attributes.
COL_FORMAT_ELEMENT	Column meta-data and values are formatted as XML Elements.
COL_FORMAT_MIXED	Column meta-data is formatted as Attributes and the column value is formatted as the value of the column Element.

Default xml formatting properties are specified in ResultSetToXMLFormat. To override any default property, add a <resultset-toxml-transformer-configuration> element to the <stageConfiguration>. Only overridden properties need to be specified. For example, the following <resultset-toxml-transformer-configuration> element overrides default format properties for the root element name, the row element name, and the includeColumnMetaData flag.

<!--  override a few default xml format properties -->
      <resultset-toxml-transformer-configuration>
          <resultset-toxml-format-properties>
              <!-- Root Element name for the XML output -->
              <format-property name="rootElementName" value="myMessage"/>
              <!-- Database row generates a "row" element in the XML output; this is the "row" element name. -->
              <format-property name="rowElementName" value="myRow"/>
              <!-- Include column MetaData with column elements. -->
              <format-property name="includeColumnMetaData" value="true"/>
          </resultset-toxml-format-properties>
      </resultset-toxml-transformer-configuration>
 

So, using default formatting properties, the XML for a single row from an employee table would look something like:

<table>
            <row>
                  <EMPNO>000010</EMPNO>
                  <FIRSTNME>CHRISTINE</FIRSTNME>
                  <MIDINIT>I</MIDINIT>
                  <LASTNAME>HAAS</LASTNAME>
                  <WORKDEPT>A00</WORKDEPT>
                  <PHONENO>3978</PHONENO>
                  <HIREDATE>01/01/1965</HIREDATE>
                  <JOB>PRES</JOB>
                  <EDLEVEL>18</EDLEVEL>
                  <SEX>F</SEX>
                  <BIRTHDATE>08/24/1933</BIRTHDATE>
                  <SALARY>52750.00</SALARY>
                  <BONUS>1000.00</BONUS>
                  <COMM>4220.00</COMM>
            </row>
      </table>
 

Since:

Version .9

Field Summary

protected ResultSetToXMLTransformer

resultSetToXMLTransformer The ResultSetToXMLTransformer, which converts a JDBC ResultSet to XML text.

Fields inherited from class org.osesb.messagepipeline.PipelineStage

log, messagePipelineContext, nextStage, parentMessagePipeline, pipelineStageConfiguration, previousStage, thisClassName

Constructor Summary

DatabaseResultSetToXMLPipelineStage(MessagePipeline parentMessagePipeline, PipelineStageConfiguration pipelineStageConfiguration)
Creates a new instance of DatabaseResultSetToXMLPipelineStage.

Method Summary

static void	main(java.lang.String[] args) main() For testing and sandboxing.
boolean	runStage(EAIMessage eaiMessage) Run PipelineStage logic.
void	stageProcessingStarting() The MessagePipeline will invoke this method on each PipelineStage immediately before invoking the runStage() method.

Methods inherited from class org.osesb.messagepipeline.PipelineStage

beingDroppedFromPool, commit, getMessagePipelineContext, getNextStage, getParentMessagePipeline, getPipelineStageConfiguration, getPreviousStage, handlePipelineException, handlePipelineException, logMessage, propagate, rollback, setNextStage, setOutputMessage, setPreviousStage, setResultMessage, stageProcessingComplete

Methods inherited from class java.lang.Object

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

Field Detail

resultSetToXMLTransformer

protected ResultSetToXMLTransformer resultSetToXMLTransformer

The ResultSetToXMLTransformer, which converts a JDBC ResultSet to XML text.

See stageProcessingStarting().

Constructor Detail

DatabaseResultSetToXMLPipelineStage

public DatabaseResultSetToXMLPipelineStage(MessagePipeline parentMessagePipeline,
                                           PipelineStageConfiguration pipelineStageConfiguration)
                                    throws java.lang.Exception

Creates a new instance of DatabaseResultSetToXMLPipelineStage.

Parameters:

parentMessagePipeline - The MessagePipeline that constructed this DatabaseResultSetToXMLPipelineStage.

pipelineStageConfiguration - A PipelineStageConfiguration for this DatabaseResultSetToXMLPipelineStage.

Throws:

java.lang.Exception - if constructed with a null parentMessagePipeline or a null pipelineStageConfiguration.

Method Detail

runStage

public boolean runStage(EAIMessage eaiMessage)
                 throws PipelineStageException

Run PipelineStage logic.

Optionally, DatabaseResultSetToXMLPipelineStage can be configured with a stageConfiguration that is a org.osesb.connectors.jdbc.relationalxml.ResultSetToXMLTransformerConfiguration for a org.osesb.connectors.jdbc.relationalxml.ResultSetToXMLTransformer, which is invoked by runStage() to convert a ResultSet to XML text. If a ResultSetToXMLTransformerConfiguration is not configured, the ResultSetToXMLTransformer uses standard transformation properties.

The ResultSetToXMLTransformer is invoked by runStage() to convert a ResultSet to XML text.

Once the transformation is complete, runstage() will 1) set the current MessagePipeline EAIXMLMessage to the transformed XML using the setOutputMessage() method and/or 2) set a MessagePipelineContext variable to the result of the transform as XML text. This behavior is determined by the <setOutputMessageToTransformResult> and the <setContextVariableToTransformResult> PipelineStageConfiguration elements as follows:

1. If <setOutputMessageToTransformResult> is true the current MessagePipeline message is set to the result of the transformation.
2. If <setContextVariableToTransformResult>, the specified MessagePipelineContext variable is set to the result of th transformation.
3. The <setContextVariableToTransformResult> configuration element allows the programmer to specify the name of the context variable for the transform result. The default context variable name is "stageName.transformResult", where stageName is the name of the PipelineStage, which is set using the 'name' attribute of the PipelineConfiguration.
4. Default behavior is to set the current MessagePipeline message to the result of the transformation and not set a MessagePipelineContext variable.

If a PipelineStage's runStage() method returns false, then pipeline processing terminates with that stage and subsequent stages are not run. However, returning false does not indicate an error to the MessagePipeline. Returning false from runStage() indicates that pipeline processing completed normally before the end of the pipeline was reached.

If a PipelineStage's runStage() method returns true, then the MessagePipeline runs the next stage.

When pipeline processing ends normally, without throwing a PipelineStageException, the MessagePipeline will commit outstanding transactions beginning with the first PipelineStage. The 'transactionScope' PipelineStageConfiguration property controls how the commit() and rollback() PipelineStage methods are invoked. See the getTransactionScope() method in PipelineStageConfiguration for details around configuring 'transactionScope' for PipelineStages.

If a PipelineStage's runStage() method throws a PipelineStageException, then pipeline processing terminates with that stage and subsequent stages are not run.

When pipeline processing ends with a PipelineStageException, the MessagePipeline will roll back outstanding transactions beginning with the PipelineStage that threw the Exception. The 'transactionScope' PipelineStageConfiguration property controls how the commit() and rollback() PipelineStage methods are invoked. See the getTransactionScope() method in PipelineStageConfiguration for details around configuring 'transactionScope' for PipelineStages.

Overrides:

runStage in class PipelineStage

Parameters:

eaiMessage - The EAI message, which is the output of the last PipeLineStage that invoked setOutputMessage(), or, if this is the first PiplelineStage, then this is the EAIMessage that the MessagePipeline was invoked with.

Returns:

true to continue pipeline processing or false to terminate pipeline processing.

Throws:

a - PipelineStageException if any errors occur.

PipelineStageException

stageProcessingStarting

public void stageProcessingStarting()
                             throws PipelineStageException

The MessagePipeline will invoke this method on each PipelineStage immediately before invoking the runStage() method.

In this method, PipelineStages should perform setup opertaions. The PipelineStages might instantiate support classes, establish JMS connections, or retrieve objects from a pool.

Note that in the case of propagated messages, the MessagePipeline will invoke stageProcessingStarting() more than once.

Overrides:

stageProcessingStarting in class PipelineStage

Throws:

PipelineStageException - if an error occurs.

main

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

main() For testing and sandboxing.

Parameters:

args - commandline arguments