org.osesb.messagepipeline.builtinstages
Class DatabaseUpdatePipelineStage

java.lang.Object
  org.osesb.messagepipeline.PipelineStage
      org.osesb.messagepipeline.builtinstages.DatabasePipelineStage
          org.osesb.messagepipeline.builtinstages.DatabaseUpdatePipelineStage

Direct Known Subclasses:

XMLToDatabaseUpdatePipelineStage

public class DatabaseUpdatePipelineStage
extends DatabasePipelineStage

DatabaseUpdatePipelineStage extends DatabasePipelineStage with a runStage() method that executes a set of configured SQL updates and puts the update count on the MessagePipelineContext. DatabaseUpdatePipelineStage works as follows:

• DatabaseUpdatePipelineStage expects a stageConfiguration that is a StandardPipelineStageConfiguration that includes a SQLStatementListConfiguration with one or more org.osesb.utilities.jdbc.SQLStatement(s). DatabaseUpdatePipelineStage also expects a org.osesb.configuration.JDBCConfiguration that is configured for the MessagePipeline as a whole or that is configured only for this PipelineStage by the StandardPipelineStageConfiguration. The configured SQLStatement(s) are executed by runStage().
• If a SQLStatement is parameterized, then runStage() looks for the values of the sql parameters in a MessagePipelineContext variable named stageName.sqlStatementName.sqlParameters, where stageName' is the name of the PipelineStage and 'sqlStatementName' is the name of the configured SQLStatement. The MessagePipelineContext variable must be an Object[] with the values for the SQLParameters. The Object[] must specify the values for the SQLParameters in the order required by the configured SQLStatement. The length of the Object[] MUST equal the number of <param> elements configured for the SQLStatement, however, if the value of the parameter is configured as a scripted variable or a constant and if the corresponding entry in the Object[] is null, then the value of the parameter is not updated, but defers to the configured value.
• The runStage() method executes the configured SQLStatement(s) and then sets a MessagePipelineContext variable named "stageName.sqlStatementName.updateCount" to an Integer object with a value equal to the updateCount for each update statement, where 'stageName' is the name of the PipelineStage and 'sqlStatementName' is the name of the configured SQLStatement.
• Descendants of DatabaseQueryPipelineStage or subsequent stages retrieve variables from the MessagePipelineContext using getContextVariable().
• zeroUpdateCountIsAnError is a configuration property that defaults to false. If true, runStage() will throw PipelineStageException if any of the configured SQL update statements return a zero updateCount. The exceptionClassification for the PipelineStageException is PipelineStageException.businessProcessException. Again, the zeroUpdateCountIsAnError configuration property applies to ALL of the configured SQL update statements.
• The runStage() of this DatabasePipelineStage does not alter the current MessagePipeline message.
• If the database query fails for any reason, then runStage() throws a PipelineStageException. Otherwise, runStage() returns 'true'.

A JDBCConfiguration defined at the pipeline level applies to all PipelineStages that require a database connection but that do not include a JDBCConfiguration in their respective PipelineStageConfiguration(s). However, a JDBCConfiguration in a PipelineStageConfiguration overrides a JDBCConfiguration defined in the MessagePipelineConfiguration.

If a JDBCConfiguration is configured at the pipeline level, then a org.osesb.utilities.jdbc.IConnectionManager is created for the MessagePipeline and all PipelineStages that do not have a JDBCConfiguration in their respective PipelineStageConfiguration(s) will obtain connections from the MessagePipeline IConnectionManager. However, if a JDBCConfiguration is configured in a PipelineStageConfiguration, then a IConnectionManager is created for that PipelineStage and the stage obtains database connections from it's connection manager.

Since:

Version .9

See Also:

DatabaseQueryPipelineStage, which extends DatabasePipelineStage with a runStage() method that executes a set of configured SQL queries and puts the resuls on the MessagePipelineContext as a cached RowSet using the Sun implementation, com.sun.rowset.CachedRowSetImpl., XMLToDatabaseUpdatePipelineStage, which extends DatabaseUpdatePipelineStage in order to implement a simple XML to database "transform" where the values of XML Elements and Attributes are mapped to the values of the input parameters for a SQL update statement.

Field Summary

Fields inherited from class org.osesb.messagepipeline.builtinstages.DatabasePipelineStage

dbConn, initialAutoCommit, jdbcConnectionManager, stageConfiguration

Fields inherited from class org.osesb.messagepipeline.PipelineStage

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

Constructor Summary

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

Method Summary

static void	main(java.lang.String[] args) main() For testing and sandboxing.
boolean	runStage(EAIMessage eaiMessage) Run PipelineStage logic.

Methods inherited from class org.osesb.messagepipeline.builtinstages.DatabasePipelineStage

beingDroppedFromPool, closeJDBCConnection, commit, executeQuery, executeUpdate, getJDBCConnection, getSQLStatement, getSQLStatements, loadJDBCConnectionManager, releaseJDBCConnection, rollback, stageProcessingComplete, stageProcessingStarting

Methods inherited from class org.osesb.messagepipeline.PipelineStage

getMessagePipelineContext, getNextStage, getParentMessagePipeline, getPipelineStageConfiguration, getPreviousStage, handlePipelineException, handlePipelineException, logMessage, propagate, setNextStage, setOutputMessage, setPreviousStage, setResultMessage

Methods inherited from class java.lang.Object

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

Constructor Detail

DatabaseUpdatePipelineStage

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

Creates a new instance of DatabaseUpdatePipelineStage.

Parameters:

parentMessagePipeline - The MessagePipeline that constructed this PipelineStage.

pipelineStageConfiguration - A PipelineStageConfiguration for this PipelineStage.

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.

This runStage() method does not use or modify the MessagePipeline's current message.

DatabaseUpdatePipelineStage expects a stageConfiguration that is a StandardPipelineStageConfiguration that includes a SQLStatementListConfiguration with one or more org.osesb.utilities.jdbc.SQLStatement(s). DatabaseUpdatePipelineStage also expects a org.osesb.configuration.JDBCConfiguration that is configured for the MessagePipeline as a whole or that is configured only for this PipelineStage by the StandardPipelineStageConfiguration. The configured SQLStatement(s) are executed by runStage().

If a SQLStatement is parameterized, then runStage() looks for the values of the sql parameters in a MessagePipelineContext variable named stageName.sqlStatementName.sqlParameters, where stageName' is the name of the PipelineStage and 'sqlStatementName' is the name of the configured SQLStatement. The MessagePipelineContext variable must be an Object[] with the values for the SQLParameters. The Object[] must specify the values for the SQLParameters in the order required by the configured SQLStatement. The length of the Object[] MUST equal the number of <param> elements configured for the SQLStatement, however, if the value of the parameter is configured as a scripted variable or a constant and if the corresponding entry in the Object[] is null, then the value of the parameter is not updated, but defers to the configured value.

The runStage() method executes the configured SQLStatement(s) and then sets a MessagePipelineContext variable named "stageName.sqlStatementName.updateCount" to an Integer object with a value equal to the updateCount for each update statement, where 'stageName' is the name of the PipelineStage and 'sqlStatementName' is the name of the configured SQLStatement.

Descendants of DatabaseQueryPipelineStage or subsequent stages retrieve variables from the MessagePipelineContext using getContextVariable().

zeroUpdateCountIsAnError is a configuration property that defaults to false. If true, runStage() will throw PipelineStageException if any of the configured SQL update statements return a zero updateCount. The exceptionClassification for the PipelineStageException is PipelineStageException.businessProcessException. Again, the zeroUpdateCountIsAnError configuration property applies to ALL of the configured SQL update statements.

MessagePipeline invokes the runStage() method on each PipelineStage in the order they appear in the MessagePipelineConfiguration. More specifically, the MessagePipeline invokes the following PipelineStage methods:

1. stageProcessingStarting(): The PipelineStage should allocate resources needed by runStage() in this method.
2. runStage()(): Main PipelineStage logic. To propagate the results of runStage() to the next stage, a PipelineStage invokes setOutputMessage() and/or propagate() with the EAIMessage to be passed to the next stage. setOutputMessage() is usually one of the last statements in runStage(), but propagate() can be invoked at any point in the runStage() method. See setOutputMessage() and propagate().
3. commit(): If a PipeleineStageException is not thrown, then commit() is invoked to commit outstanding transactions. The 'transactionScope' PipelineStageConfiguration property controls how the commit() and rollback() methods are invoked. See the getTransactionScope() method in PipelineStageConfiguration for details.
4. rollback(): If a PipeleineStageException is thrown, then rollback() is invoked to rollback outstanding transactions. The 'transactionScope' PipelineStageConfiguration property controls how the commit() and rollback() methods are invoked. See the getTransactionScope() method in PipelineStageConfiguration for details.
5. stageProcessingComplete(): PipelineStage should release resources in this method. The MessagePipeline invokes stageProcessingComplete() after all PipelineStage transactions are committed or rolled back.

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 DatabasePipelineStage

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

main

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

main() For testing and sandboxing.

Parameters:

args - commandline arguments