This topic will help you understand the interactions that take place between WebSphere Message Broker components when you run a user-defined parser. It explains each stage in terms of the events that cause, occur during, and after of each stage, and the APIs that are called. Understanding the concepts in this topic will allow you to design and develop your parser more effectively.
The first phase in the user-defined parser's life cycle is the registration phase. The purpose of the registration phase is to register the user-defined parser with the broker. This phase is triggered by the initialization phase of the start-up of the execution group process.
The parser is created during the instantiation phase of the parser life cycle. When an input message is received, or an output message is built in a compute node, the relevant parser is identified, and parser requirements are taken from the message header, such as MQMD. The broker starts, loads the Loadable Implementation Library (LIL), and the parser factory. The execution group process creates an instance of the parser, and the broker makes a call to cpiCreateContext to allow the parser object to acquire the appropriate section of the message.
Before this function is called, the broker will have created a name element as the effective root element for the parser. However, this element is not named. The parser should name this element in the cpiSetElementName function.
The broker then makes a call to cpiParseBuffer. The purpose of cpiParseBuffer at this stage is to perform any necessary initialization, and to return the length of the message content that the parser is taking ownership of. The parser assesses how much of the message data to parse, and claims the appropriate number of bytes.
Whenever an instance of a user-defined parser object is created, the context creation implementation function cpiCreateContext is also invoked by the message broker. This allows the parser to allocate instance data associated with the parser. A cpiDeleteContext function to delete the context of the parser object is also required.
The purpose of the processing phase is to manipulate, alter, and reference elements within a message object that the parser is interpreting. The message flow processing phase begins when any message processing activity occurs, such as navigation, that requires access to an element within a message that does not exist in the broker's internal model representation of the message concerned.
During the message flow processing phase, the parser is invoked in response to attempts to navigate into the message tree. The parser examines the buffer allocated when cpiParseBuffer was called, and creates any necessary message elements.
These functions are invoked when any form of navigation is made, such as a filter expression that specifies a message field, into the part of the syntax element tree that logically represents the data for a message format supported by a user-defined parser. This occurs when an operation within the broker requires a syntax element tree to be built or extended.
When the parser has finished parsing the relevant parts of the syntax element tree, it calls cpiWriteBuffer. This function appends its portion of the syntax element tree to the bit stream in the message buffer that is associated with the parser object. This creates the output message.
The Destruction phase is the final phase in the user-defined parser life cycle. When the parser has written its portion of the syntax element tree to the bit stream and created the output message, the system resources that were created by the broker for the parser to use need to be released.
The destruction phase begins when the mqsistop command is used to stop the execution process.