WebSphere Message Brokers
File: as24998_
Writer: Lorraine Waitt

Concept topic

This build: July 31, 2007 21:38:53

Java user-defined input node life cycle

This topic guides you through the various stages in the life of a user-defined input node written using the Java programming language. It covers the following stages in an input node's life cycle:

Registration

During the registration phase a user-defined input node written in Java makes itself known to the broker. The node is registered with the broker through the static getNodeName method. Whenever a broker starts, it loads all the relevant Java classes. The static method getNodeName is called at this point, and the broker registers the input node with the node name specified in the getNodeName method. If you do not specify a node name, the broker automatically creates a name for the node based on the package in which it is contained.

Using a static method here means that the method can be called by the broker before the node itself is instantiated.

Instantiation

A Java User-defined input node is instantiated when a broker deploys a message flow containing the user-defined input node. When the node is instantiated, the constructor of the input node's class is called.

When a node is instantiated, any terminals that you have specified are created. A message processing node can have any number of input and output terminals associated with it. You must include the createInputTerminal and createOutputTerminal methods in your node constructor in order to declare these terminals.

If you want to handle exceptions that are passed back to your input node, you should use createOutputTerminal to create a catch terminal for your input node. When the input node catches an error, the catch terminal will process it in the same way that a regular MQInput node would. You can allow most exceptions, such as exceptions caused by deployment problems, to pass back to the broker, and the broker will warn the user of any possible configuration errors.

As a minimum, your constructor class needs only to create these output terminals on your input node. However, if you need to initialize attribute values, such as defining the parser that will initially parse a message passed from the input node, you should also include that code at this point in your input node.

Processing

Message processing for an input node begins when the broker calls the run method. The run method creates the input message, and should contain the processing function for the input node.

The run method is defined in MbInputNodeInterface, which is the interface used in a user-defined input node that defines it as an input node. You must include a run method in your node. If you do not include a run method in your user-defined input node, then the node source code will not compile.

When a message flow containing a user-defined input node is deployed successfully, the broker calls the node's run implementation method, and continues to call this method while it waits for messages to process.

When a message flow starts, a single thread is dispatched by the broker, and is called into the input node's run method. If the dispatchThread() method is called, further threads can also be created in the same run method. These new threads immediately call into the input node's run method, and can be treated the same as the original thread. The number of new threads that can be created is defined by the additionalInstances property. The recommended model is to make sure that threads are dispatched after a message has been created and before it is propagated. This ensures that only one thread at a time is waiting for a new message.

The user-defined input node can choose a different threading model and is responsible for implementing the chosen model. If the input node supports the additionalInstances property, and dispatchThread() is called, then the code must be fully re-entrant, and any functions that are invoked by the node should also be re-entrant. If the input node forces single threading, that is, it does not call dispatchThread(), then it should be made clear to the user of that node that setting the additionalInstances property will have no effect on the input node.

For more information on the threading model for User-defined Input nodes, see Threading.

Destruction

A Java user-defined input node is destroyed when the node is deleted or the broker is shut down. You do not need to include anything in your code that specifies the node should be physically deleted, because this can be handled by the garbage collector.

However, if you want notification that a node is about to be deleted, you can use the onDelete method. You might want to do this if there are resources that you want to delete, other than those that will be garbage collected. For example, if you have opened a socket, this will not be properly closed when the node is automatically deleted. You can include this instruction in your onDelete method to ensure that the socket is closed properly.

Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:38:53

as24998_ This topic's URL is: