com.adventnet.tl1.parser
Class TL1AutonomousMessageParser

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

public class TL1AutonomousMessageParser

extends java.lang.Object

This TL1AutonomousMessageParser class is used to generate a com.adventnet.tl1.message.TL1AutonomousMessage object from a raw TL1 autonomous message string. In other words, this parser is a TL1AutonomousMessage 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 autonomous message string to create TL1AutonomousMessage objects.
• Distinguish valid (recognizable) autonomous message strings from the invalid ones.
• Ultra-flexibile context sensitive pattern recognition to parse autonomous messages of highly varied flavors. This enables parsing a whole gamut of autonomous 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 autonomous 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. Autonomous 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 autonomous 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 autonomous 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 autonomous 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 TL1AutonomousMessageParser object, use the default constructor TL1AutonomousMessageParser. The parser is initialized to the various default options. To change the default setting, use the appropriate setter methods mentioned above.
• Autonomous message Validation : To check if a raw message string is valid (recognizable) or not, use the isAutonomousMessage(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 TL1AutonomousMessage object can be generated, atleast in the Flexible Parser mode.
• TL1AutonomousMessage Generation : To generate a TL1AutonomousMessage object, use the createTL1Message(String) method. If the management system needs to dynamically vary the parser mode, to Flexible or Rigid, while generating TL1AutonomousMessage 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 autonomous 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_AutonomousMessage	Autonomous Message	- Flexible - Rigid
  RULE_Header	Header	- Flexible - Rigid
  RULE_SourceId	Source Identifier	- Flexible - Rigid
  RULE_HDRDate	Header Date	- Flexible - Rigid
  RULE_HDRTime	Header Time	- Flexible - Rigid
  RULE_AutoId	Auto Identifier	- Flexible - Rigid
  RULE_AlarmCode	Alarm Code	- Flexible - Rigid
  RULE_ATag	Auto Tag	- Flexible - Rigid
  RULE_OutputCode	Output Code	- Flexible - Rigid
  RULE_TextBlock	Text Block	- Flexible - Rigid
  RULE_Line	- Commented Line - Quoted Line - Unquoted Line	- Flexible - Rigid
  RULE_CommentedLine	Commented Line	- Flexible - Rigid
  RULE_QuotedLine	Quoted Line	- Flexible - Rigid
  RULE_UnquotedLine	Unquoted Line	- Flexible - Rigid
  RULE_QuotedParameterBlock	Quoted Parameter Block	- Flexible - Rigid
  RULE_UnquotedParameterBlock	Unquoted Parameter Block	- Flexible - Rigid
  RULE_QuotedParameter	Quoted Parameter	- Flexible - Rigid
  RULE_UnquotedParameter	Unquoted Parameter	- Flexible - Rigid
  RULE_QuotedParamName	Quoted Parameter Name	- Flexible - Rigid
  RULE_UnquotedParamName	Unquoted Parameter Name	- Flexible - Rigid
  RULE_QuotedParamValue	Quoted Parameter Value	- Flexible - Rigid
  RULE_UnquotedParamValue	Unquoted Parameter Value	- Flexible - Rigid
  RULE_QuotedSequenceChain	Quoted Sequence Chain	- Rigid
  RULE_UnquotedSequenceChain	Unquoted Sequence Chain	- Rigid
  RULE_QuotedSimpleSequence	Quoted Simple Sequence	- Rigid
  RULE_UnquotedSimpleSequence	Unquoted Simple Sequence	- Rigid
  RULE_QuotedComplexChain	Quoted Complex Chain	- Rigid
  RULE_UnquotedComplexChain	Unquoted Complex Chain	- Rigid
  RULE_QuotedComplexSequence	Quoted Complex Sequence	- Rigid
  RULE_UnquotedComplexSequence	Unquoted Complex Sequence	- Rigid
  RULE_QuotedComplexArg	Quoted Complex Argument	- Rigid
  RULE_UnquotedComplexArg	Unquoted Complex Argument	- Rigid
  RULE_QuotedLinkedSequence	Quoted Linked Sequence	- Rigid
  RULE_UnquotedLinkedSequence	Unuoted Linked Sequence	- Rigid
  RULE_QuotedInfoUnit	Quoted Information Unit	- Rigid
  RULE_UnquotedInfoUnit	Unquoted Information Unit	- Rigid

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

     String message = "\r\n\n   " + 
                      "SPFGX5 96-01-08 22:22:46" + "\r\n" + 
                      "A  12 REPT EVT OC3" + "\r\n" +
                      "\"OC3-3-3:T-UASL,TC,01-08,22-22-46,10,15\"" + \r\n" +
                      ";"; 
     TL1AutonomousMessage aumsg = null; 
     TL1AutonomousMessageParser aupsr = new TL1AutonomousMessageParser(); 
     aupsr.setParserMode(true);  // RIGID Parser mode
     try {
         aumsg = aupsr.createTL1Message(message);

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

Authors:
Chandramouli S and
Satya Narayan Dash

Since:

TL1 API 3

See Also:

TL1AutonomousMessage, TL1MessageParser

Constructor Summary

TL1AutonomousMessageParser()
Creates a new TL1AutonomousMessageParser object.

Method Summary

com.adventnet.tl1.message.TL1AutonomousMessage	createTL1Message(java.lang.String message) Generates a TL1AutonomousMessage object from a raw autonomous message string.
com.adventnet.tl1.message.TL1AutonomousMessage	createTL1Message(java.lang.String message, boolean isrigid) Generates a TL1AutonomousMessage object from a raw autonomous message string.
java.lang.String	getAlarmCode(java.lang.String message) Gets the Alarm Code from the raw autonomous message string.
java.lang.String	getATag(java.lang.String message) Gets the Auto Tag from the raw autonomous message string.
com.adventnet.tl1.message.TL1AutoID	getAutoId(java.lang.String message) Gets the Auto Identifier from the raw autonomous message string.
com.adventnet.tl1.message.TL1Param	getHDRDate(java.lang.String message) Gets the Header Date from the raw autonomous message string.
com.adventnet.tl1.message.TL1Param	getHDRTime(java.lang.String message) Gets the Header Time from the raw autonomous message string.
com.adventnet.tl1.message.TL1Header	getHeader(java.lang.String message) Gets the Header from the raw autonomous message string.
java.lang.String	getOutputCode(java.lang.String message) Gets the Output Code from the raw autonomous message string.
java.lang.String	getSourceId(java.lang.String message) Gets the Source Identifier from the raw autonomous message string.
com.adventnet.tl1.message.TL1TextBlock	getTextBlock(java.lang.String message) Gets the Text Block from the raw autonomous message string.
boolean	isAutonomousMessage(java.lang.String message) Checks whether the raw message string is a valid (recognizable) TL1 autonomous message or not.
boolean	isChainedComment() Gets the comment recognition mode.
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 autonomous 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

TL1AutonomousMessageParser

public TL1AutonomousMessageParser()

Creates a new TL1AutonomousMessageParser 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. Autonomous 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 autonomous message. By default, the parser mode is set to Flexible Parser.

Rigid Mode : The focus is on rigorous Grammar (rule) Checks. Only autonomous 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 autonomous 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 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)

isAutonomousMessage

public boolean isAutonomousMessage(java.lang.String message)

Checks whether the raw message string is a valid (recognizable) TL1 autonomous message or not. If a message string is valid it means that a valid TL1AutonomousMessage 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 autonomous message.
• false - if the message string is not a valid TL1 autonomous message.

Since:

TL1 API 4

getHeader

public com.adventnet.tl1.message.TL1Header getHeader(java.lang.String message)
                                              throws TL1ParserException

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

Parameters:

message - the raw message string.

Returns:

TL1Header object for a valid autonomous 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 autonomous message.

Since:

TL1 API 4

See Also:

getSourceId(String), getHDRDate(String), getHDRTime(String)

getSourceId

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

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

Parameters:

message - the raw message string.

Returns:

Source Identifier for a valid autonomous 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 autonomous message.

Since:

TL1 API 4

See Also:

getHeader(String)

getHDRDate

public com.adventnet.tl1.message.TL1Param getHDRDate(java.lang.String message)
                                              throws TL1ParserException

Gets the Header Date from the raw autonomous message string. Internally uses the Flexible Parser mode. Rejects (throws TL1ParserException) messages that are not valid (recognizable) autonomous messages.

Parameters:

message - the raw message string.

Returns:

TL1Param object for a valid autonomous 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 autonomous message.

Since:

TL1 API 4

See Also:

getHeader(String)

getHDRTime

public com.adventnet.tl1.message.TL1Param getHDRTime(java.lang.String message)
                                              throws TL1ParserException

Gets the Header Time from the raw autonomous message string. Internally uses the Flexible Parser mode. Rejects (throws TL1ParserException) messages that are not valid (recognizable) autonomous messages.

Parameters:

message - the raw message string.

Returns:

TL1Param object for a valid autonomous 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 autonomous message.

Since:

TL1 API 4

See Also:

getHeader(String)

getAutoId

public com.adventnet.tl1.message.TL1AutoID getAutoId(java.lang.String message)
                                              throws TL1ParserException

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

Parameters:

message - the raw message string.

Returns:

TL1AutoID object for a valid autonomous 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 autonomous message.

Since:

TL1 API 4

See Also:

getAlarmCode(String), getATag(String), getOutputCode(String)

getAlarmCode

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

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

Parameters:

message - the raw message string.

Returns:

Alarm Code for a valid autonomous 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 autonomous message.

Since:

TL1 API 4

See Also:

getAutoId(String)

getATag

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

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

Parameters:

message - the raw message string.

Returns:

Auto Tag for a valid autonomous 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 autonomous message.

Since:

TL1 API 4

See Also:

getAutoId(String)

getOutputCode

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

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

Parameters:

message - the raw message string.

Returns:

Output Code for a valid autonomous 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 autonomous message.

Since:

TL1 API 4

See Also:

getAutoId(String)

getTextBlock

public com.adventnet.tl1.message.TL1TextBlock getTextBlock(java.lang.String message)
                                                    throws TL1ParserException

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

Parameters:

message - the raw message string.

Returns:

TL1TextBlock object for a valid autonomous 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 autonomous message.

Since:

TL1 API 4

createTL1Message

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

Generates a TL1AutonomousMessage object from a raw autonomous 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) autonomous messages.

Parameters:

message - the raw message string.

Returns:

TL1AutonomousMessage object for a valid autonomous 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 autonomous message.

Since:

TL1 API 3

createTL1Message

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

Generates a TL1AutonomousMessage object from a raw autonomous message string.

This factory method parses according to the parser mode passed dynamically (at run-time) and the comment recognition mode set (before calling this method).
Rejects (throws TL1ParserException) messages that are not valid (recognizable) autonomous messages.

Parameters:

message - the raw message string.

isrigid - the parser mode to use for parsing

• true - for Rigid Parser mode.
• false - for Flexible Parser mode.

Returns:

TL1AutonomousMessage object for a valid autonomous 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 autonomous message.

Since:

TL1 API 4

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 autonomous 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 Header of a autonomous message Rigid Parser mode is used here. The default Chained Comment mode is left as it is, as comments donot matter here.

     String pattern = "\r\n\n   SPFGX508 96-01-08 22:22:46";
     TL1AutonomousMessageParser aupsr = new TL1AutonomousMessageParser();
     aupsr.setParserMode(true);
     try {
         aupsr.rule(pattern, TL1AutonomousMessageParser.RULE_Header); 
     } 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