com.adventnet.tl1.parser
Class TL1InputMessageParser

java.lang.Object
  |
  +--com.adventnet.tl1.parser.TL1InputMessageParser

public class TL1InputMessageParser

extends java.lang.Object

This TL1InputMessageParser class is used to generate a com.adventnet.tl1.message.TL1InputMessage object from a raw TL1 input message string. In other words, this parser is a TL1InputMessage factory. It employs powerful regular-expression based pattern recognition algorithms to scan and extract relevant information as well as performs exhaustive grammar (rule) checks on the raw message string.

Background Information : Typically, TL1 based management applications need to interface with TL1 devices / infrastructure belonging to diverse technologies, domains, and vendors. These devices, although conforming to the Bellcore (Telcordia) standards at a high level often do have many variations and flavors when it comes to specific TL1 messages. Apart from this, each standard TL1 message has its own information structure and size, and there is no standard way of capturing TL1 message formats for management applications to automate message processing. Flexible and smart parsing of TL1 messages is crucial for building robust, interoperable TL1 management applications.

On the other hand, TL1 agents / north-bound interfaces need to construct standard, Bellcore specification compliant TL1 messages. Rigorous grammar checking of TL1 messages is crucial for building standard compliant, interoperable TL1 agents / interfaces.

Key Benefits :

• Effortlessly scan, recognize and extract relevant information from the raw TL1 input message string to create TL1InputMessage objects.
• Distinguish valid (recognizable) input message strings from the invalid ones.
• Ultra-flexibile context sensitive pattern recognition to parse input messages of highly varied flavors. This enables parsing a whole gamut of input messages irrespective of their wide variations.
• Perform rigorous grammar (rule) checks, on the message string, for complete conformance with the GR-831-CORE specification of Bellcore (Telcordia).
• Finegrained access for performing grammar (rule) checks on each and every building-block (pattern structure) used in input messages.
• Special recognition option for allowing chained comments as well as restricting comments to the standard format.

Warning : This parser class is meant for single threaded usage. In other words, methods of this class are not synchronized or multi-threaded. Therefore each thread must create and use a new instance of this parser. However, this constraint is not a problem as this parser is light-weight.

Options Supported :

• Parser Mode : (refer setParserMode(boolean))
• Flexible Mode : The focus is on flexible and smart pattern recognition. Input messages that deviate from the GR-831-CORE specification should be parsed using this mode. If a particular message string is rejected by the parser (throws TL1ParserException) in this mode, it means that it is not a valid input message. To initialize the parser to Flexible Parser mode, use the setParserMode(false) method. By default, the parser is set to Flexible Parser mode.
• Rigid Mode : The focus is on rigorous Grammar (rule) Checks. Only input messages that are fully compliant with the GR-831-CORE specification are parsed. All other messages with any deviation are rejected (throws TL1ParserException). To initialize the parser to Rigid Parser mode, use the setParserMode(true) method.
• Comment Recognition Mode : (refer setChainedComment(boolean))
• Chained Comment : Special pattern recognition logic for enabling chained comments is triggered. Systems that need to process input messages with multiple chained comments (comments inside comments) should use this mode. To initialize the parser to Chained Comment mode, use the setChainedComment(true) method. By default, the parser is set to Chained Comment mode.
• Standard Comment : Comments are parsed for the GR-831-CORE specification compliance. Here chained comments are rejected and only standard comments are allowed. To initialize the parser to Standard Comment mode, use the setChainedComment(false) method.

Usage :

• Parser Instantiation : To create a new TL1InputMessageParser object, use the default constructor TL1InputMessageParser. The parser is initialized to the various default options. To change the default setting use the appropriate setter methods mentioned above.
• Input message Validation : To check if a raw message string is valid (recognizable) or not, use the isInputMessage(java.lang.String) method. If a message string is valid this method returns true, otherwise returns false. If a message string is valid it means that a valid TL1InputMessage object can be generated, atleast in the Flexible Parser mode.
• TL1InputMessage Generation : To generate a TL1InputMessage object, use the createTL1Message(String) method. If the management system needs to dynamically vary the parser mode, to Flexible or Rigid, while generating TL1InputMessage objects, use the createTL1Message(String, boolean) method.
• Fine-grained Grammar Check : To perform grammar checks on any of individual building-blocks (micro pattern structures) of the input message, use the rule(String, int) method, with the appropriate Rule Constant for that building-block. To know more about these individual building-blocks refer to the GR-831-CORE specification. Most of the Rule Constants are applicable (active) for both Flexible and Rigid parser modes. But some of them are applicable for only one parser mode, depending on which mode they are used by the parser for pattern recognition. The following table maps each of the Rule Constants to their pattern structures and their applicable parser modes. All the Rule Constants are of public static final int type.
  
  

  Rule Constant	Pattern Structure	Parser Mode
  RULE_InputMessage	Input Message	- Flexible - Rigid
  RULE_CommandCode	Command Code	- Flexible - Rigid
  RULE_TargetId	Target Identifier	- Flexible - Rigid
  RULE_AccessId	Access Identifier	- Flexible - Rigid
  RULE_CorrelationTag	Correlation Tag	- Flexible - Rigid
  RULE_GeneralBlock	General Block	- Flexible - Rigid
  RULE_GBDate	General Block Date	- Rigid
  RULE_GBTime	General Block Time	- Rigid
  RULE_CommandParameterBlock	Command Parameter Block	- Flexible - Rigid
  RULE_CommandParameter	Command Parameter	- Flexible - Rigid
  RULE_CommandParamName	Command Parameter Name	- Flexible - Rigid
  RULE_CommandParamValue	Command Parameter Value	- Flexible - Rigid
  RULE_CommandSequenceChain	Command Sequence Chain	- Rigid
  RULE_CommandSimpleSequence	Command Simple Sequence	- Rigid
  RULE_CommandComplexChain	Command Complex Chain	- Rigid
  RULE_CommandComplexSequence	Command Complex Sequence	- Rigid
  RULE_CommandComplexArg	Command Complex Argument	- Rigid
  RULE_CommandLinkedSequence	Command Linked Sequence	- Rigid
  RULE_CommandInfoUnit	Command Information Unit	- Rigid

Example code snippet : This is a code snippet for creating a TL1InputMessage object by parsing a raw message string.

     String message = "RTRV-OC12:FMX117S:OC12-ALL:9:,,,::STINFO=YES;";
     TL1InputMessage imsg = null; 
     TL1InputMessageParser ipsr = new TL1InputMessageParser(); 
     ipsr.setParserMode(true);  // RIGID Parser mode
     try {
         imsg = ipsr.createTL1Message(message);

         // Instead you can also use the method shown below
         // In this case, you need not code ipsr.setParserMode(true)
         // imsg = ipsr.createTL1Message(message, true);
     } catch(TL1ParserException tpex) {
         tpex.printStackTrace();
         ... // Error recovery code    
     }
 

Authors:
Chandramouli S and
Satya Narayan Dash

Since:

TL1 API 3

See Also:

TL1InputMessage, TL1MessageParser

Constructor Summary

TL1InputMessageParser()
Creates a new TL1InputMessageParser object.

Method Summary

com.adventnet.tl1.message.TL1InputMessage	createTL1Message(java.lang.String message) Generates a TL1InputMessage object from a raw input message string.
com.adventnet.tl1.message.TL1InputMessage	createTL1Message(java.lang.String message, boolean isrigid) Generates a TL1InputMessage object from a raw input message string.
com.adventnet.tl1.message.TL1ParamBlock	getAccessId(java.lang.String message) Gets the Access Identifier from the raw input message string.
java.lang.String	getCommandCode(java.lang.String message) Gets the Command Code from the raw input message string.
java.lang.String	getCorrelationTag(java.lang.String message) Gets the Correlation Tag from the raw input message string.
com.adventnet.tl1.message.TL1ParamBlock	getGeneralBlock(java.lang.String message) Gets the General Block from the raw input message string.
com.adventnet.tl1.message.TL1ParamGroup	getMessagePayloadBlock(java.lang.String message) Gets the Message Payload Block from the raw input message string.
java.lang.String	getTargetId(java.lang.String message) Gets the Target Identifier from the raw input message string.
boolean	isChainedComment() Gets the comment recognition mode.
boolean	isInputMessage(java.lang.String message) Checks whether the raw message string is a valid (recognizable) TL1 input message or not.
boolean	isRigidParser() Gets the parser mode.
void	rule(java.lang.String parsable, int rule) Checks the grammar (rule) of any of the individual building-blocks (micro pattern structures) of the TL1 input message.
void	setChainedComment(boolean ischain) Sets the comment recognition mode to Chained or Standard.
void	setParserMode(boolean isrigid) Sets the parser mode to Flexible or Rigid Parser.

Methods inherited from class java.lang.Object

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

Constructor Detail

TL1InputMessageParser

public TL1InputMessageParser()

Creates a new TL1InputMessageParser object.

The new parser object is initialized to the default options. That is, the parser mode is set to Flexible Parser and the comment recognition mode is set to Chained Comment. To switch the parser mode to Rigid Parser, call the setParserMode method explicitly. To switch the comment recognition mode to Standard Comment, call the setChainedComment method explicitly.

Method Detail

setParserMode

public void setParserMode(boolean isrigid)

Sets the parser mode to Flexible or Rigid Parser.

createTL1Message(String) and rule(String, int) methods parse according to the parser mode set.

Flexible Mode : The focus is on flexible and smart pattern recognition. Input messages that deviate from the GR-831-CORE specification should be parsed using this mode. If a particular message string is rejected by the parser (throws TL1ParserException) in this mode, it means that it is not a valid input message. By default, the parser mode is set to Flexible Parser.

Rigid Mode : The focus is on rigorous Grammar (rule) Checks. Only input messages that are fully compliant with the GR-831-CORE specification are parsed. All other messages with any deviation are rejected (throws TL1ParserException). To switch the parser mode to Rigid Parser, call this method explicitly.

Parameters:

isrigid - the parser mode.

• true - for RIGID Parser mode.
• false - for FLEXIBLE Parser mode.

Since:

TL1 API 4

See Also:

isRigidParser()

isRigidParser

public boolean isRigidParser()

Gets the parser mode.

Returns:

• true - for RIGID Parser mode.
• false - for FLEXIBLE Parser mode.

Since:

TL1 API 4

See Also:

setParserMode(boolean)

setChainedComment

public void setChainedComment(boolean ischain)

Sets the comment recognition mode to Chained or Standard.

createTL1Message(String) and rule(String, int) methods recognise comments according to the comment recognition mode set.

Chained Comment : Special pattern recognition logic for enabling chained comments is triggered. Systems that need to process input messages with multiple chained comments (comments inside comments) should use this mode. By default, the comment recognition mode is set to Chained.

Standard Comment : Comments are parsed for the GR-831-CORE specification compliance. Here chained comments are rejected (throws TL1ParserException) and only standard comments are allowed. To switch the comment recognition mode to Standard Comment, call this method explicitly.

Parameters:

ischain - the comment recognition mode.

• true - for Chained Comment mode.
• false - for Standard Comment mode.

Since:

TL1 API 4

See Also:

isChainedComment()

isChainedComment

public boolean isChainedComment()

Gets the comment recognition mode.

Returns:

• true - for Chained Comment mode.
• false - for Standard Comment mode.

Since:

TL1 API 4

See Also:

setChainedComment(boolean)

isInputMessage

public boolean isInputMessage(java.lang.String message)

Checks whether the raw message string is a valid (recognizable) TL1 input message or not. If a message string is valid it means that a valid TL1InputMessage object can be generated, atleast in the Flexible Parser mode.

Parameters:

message - the raw message string.

Returns:

• true - if the message string is a valid TL1 input message.
• false - if the message string is not a valid TL1 input message.

Since:

TL1 API 4

getCommandCode

public java.lang.String getCommandCode(java.lang.String message)
                                throws TL1ParserException

Gets the Command Code from the raw input message string. Internally uses the Flexible Parser mode. Rejects (throws TL1ParserException) messages that are not valid (recognizable) input messages.

Parameters:

message - the raw message string.

Returns:

Command Code for a valid input message string; null for a null message string and if message.trim() is an empty string.

Throws:

TL1ParserException - if the message string is not a valid input message.

Since:

TL1 API 4

getTargetId

public java.lang.String getTargetId(java.lang.String message)
                             throws TL1ParserException

Gets the Target Identifier from the raw input message string. Internally uses the Flexible Parser mode. Rejects (throws TL1ParserException) messages that are not valid (recognizable) input messages.

Parameters:

message - the raw message string.

Returns:

Target Identifier for a valid input message string; null for a null message string and if message.trim() is an empty string.

Throws:

TL1ParserException - if the message string is not a valid input message.

Since:

TL1 API 4

getAccessId

public com.adventnet.tl1.message.TL1ParamBlock getAccessId(java.lang.String message)
                                                    throws TL1ParserException

Gets the Access Identifier from the raw input message string. Internally uses the Flexible Parser mode. Rejects (throws TL1ParserException) messages that are not valid (recognizable) input messages.

Parameters:

message - the raw message string.

Returns:

TL1ParamBlock for a valid input message string; null for a null message string and if message.trim() is an empty string.

Throws:

TL1ParserException - if the message string is not a valid input message.

Since:

TL1 API 4

getCorrelationTag

public java.lang.String getCorrelationTag(java.lang.String message)
                                   throws TL1ParserException

Gets the Correlation Tag from the raw input message string. Internally uses the Flexible Parser mode. Rejects (throws TL1ParserException) messages that are not valid (recognizable) input messages.

Parameters:

message - the raw message string.

Returns:

Correlation Tag for a valid input message string; null for a null message string and if message.trim() is an empty string.

Throws:

TL1ParserException - if the message string is not a valid input message.

Since:

TL1 API 4

getGeneralBlock

public com.adventnet.tl1.message.TL1ParamBlock getGeneralBlock(java.lang.String message)
                                                        throws TL1ParserException

Gets the General Block from the raw input message string. Internally uses the Flexible Parser mode. Rejects (throws TL1ParserException) messages that are not valid (recognizable) input messages.

Parameters:

message - the raw message string.

Returns:

TL1ParamBlock for a valid input message string; null for a null message string and if message.trim() is an empty string.

Throws:

TL1ParserException - if the message string is not a valid input message.

Since:

TL1 API 4

getMessagePayloadBlock

public com.adventnet.tl1.message.TL1ParamGroup getMessagePayloadBlock(java.lang.String message)
                                                               throws TL1ParserException

Gets the Message Payload Block from the raw input message string. Internally uses the Flexible Parser mode. Rejects (throws TL1ParserException) messages that are not valid (recognizable) input messages.

Parameters:

message - the raw message string.

Returns:

TL1ParamGroup for a valid input message string; null for a null message string and if message.trim() is an empty string.

Throws:

TL1ParserException - if the message string is not a valid input message.

Since:

TL1 API 4

createTL1Message

public com.adventnet.tl1.message.TL1InputMessage createTL1Message(java.lang.String message)
                                                           throws TL1ParserException

Generates a TL1InputMessage object from a raw input message string.

This factory method parses according to the parser mode and the comment recognition mode set.
Rejects (throws TL1ParserException) messages that are not valid (recognizable) input messages.

Parameters:

message - the raw message string.

Returns:

TL1InputMessage object for a valid input message string; null for a null message string and if message.trim() is an empty string.

Throws:

TL1ParserException - if the message string is not a valid input message.

Since:

TL1 API 3

createTL1Message

public com.adventnet.tl1.message.TL1InputMessage createTL1Message(java.lang.String message,
                                                                  boolean isrigid)
                                                           throws TL1ParserException

Generates a TL1InputMessage object from a raw input message string.

This factory method parses according to the parser mode and the comment recognition mode set.
Rejects (throws TL1ParserException) messages that are not valid (recognizable) input messages.

Parameters:

message - the raw message string.

Returns:

TL1InputMessage object for a valid input message string; null for a null message string and if message.trim() is an empty string.

Throws:

TL1ParserException - if the message string is not a valid input message.

Since:

TL1 API 3

rule

public void rule(java.lang.String parsable,
                 int rule)
          throws TL1ParserException

Checks the grammar (rule) of any of the individual building-blocks (micro pattern structures) of the TL1 input message. To know more about these individual building-blocks refer to the GR-831-CORE specification.

This rule checker method offers fine-grained grammar validation capability to applications. It parses according to the parser mode and the comment recognition mode set.
Rejects (throws TL1ParserException) patterns that donot conform to the valid grammar of that particular Rule Constant passed.

Most of the Rule Constants are applicable (active) for both Flexible and Rigid parser modes. But some of them are applicable for only one parser mode, depending on which mode they are used by the parser for pattern. All the Rule Constants are of public static final int type. Please refer to the Rule Constant Matrix for more information on specific Rule Constants.

Example code snippet : This is a code snippet for validating the Access Identifier of a input message Rigid Parser mode is used here. The default Chained Comment mode is left as it is, as comments donot matter here.

     String pattern = "OC3-6-1-2&OC3-6-1-4,OC3-6-1-3&OC3-6-1-5";
     TL1InputMessageParser ipsr = new TL1InputMessageParser();
     ipsr.setParserMode(true);
     try {
         ipsr.rule(pattern, TL1InputMessageParser.RULE_AccessId); 
     } catch (TL1ParseException tpex) {
         tpex.printStackTrace();
         ... // Error recovery code    
     }
 

Parameters:

parsable - the raw building-block (pattern structure) string.

rule - the Rule Constant corresponding to the particular pattern structure checked.

Throws:

TL1ParserException - if the message string is a valid pattern.

Since:

TL1 API 4