WebSphere Message Brokers
File: as01413_
Writer: Lorraine Waitt

Concept topic

This build: July 31, 2007 21:36:56

User-defined parser life cycle

This topic guides you through the various stages in the life of a user-defined message flow parser. The stages are as follows:

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.

Registration

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.

Instantiation

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.

Processing

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.

The parser can then navigate through the message elements, using any or all of the following parser implementation functions:
  • cpiParseFirstChild
  • cpiParseLastChild
  • cpiParsePreviousSibling
  • cpiParseNextSibling

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.

You should be aware of the following points when deciding how best to navigate the syntax element tree:
  • A Syntax element has five pointers to its parents, siblings, and first and last children. This means that you have available a finite set of navigations
  • The same internal classes are used to perform all of these navigations
  • The parser does not control the navigation. The ESQL or a user-defined node makes the decision about which direction to navigate in, and the order in which the navigational parser implementation functions are invoked. The user-defined parser has no control over this, and needs to respond correctly to the chosen navigation scheme. This could mean parsing right to left, as well as left to right, for instance.
  • When writing a user-defined parser, it is expected that you place the actual parser code in a parseNextItem function. This function should build the syntax element tree one element at a time, setting names, values and complete flags appropriately. How you implement this function depends on the nature of the bit stream to be parsed. The sample parser supplied with WebSphere Message Broker demonstrates this.

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.

Destruction

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.

Related tasks
Creating a parser in C
Notices | Trademarks | Downloads | Library | Support | Feedback

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

as01413_ This topic's URL is: