Module openj9.dtfj
Package com.ibm.dtfj.javacore.parser.framework.tag

Class LineRule

java.lang.Object
com.ibm.dtfj.javacore.parser.framework.tag.LineRule
All Implemented Interfaces:
ILineRule
Direct Known Subclasses:
ClassLoaderLineRule, MonitorObjectLineRule, NativeStackTraceLineRule, PointerSizeLineRule, StackTraceLineRule, ThreadInfoLineRule
public abstract class LineRule extends Object implements ILineRule
This is the basic line parser for a javacore tag. A set of frequently-encountered pattern matching behaviours are implemented as helper methods to facilitate pattern matching. However, the concrete subtype must implement the actual pattern matching and token generation logic for a particular tag. Each tag is ideally assigned it's own linerule, unless multiple tags share the exact same pattern.

This linerule parses a line based on the parsing logic implemented by the concrete type, and adds the parsed data as tokens to an internal token map. The concrete classes only need to specify HOW the line is parsed, and HOW the tokens are generated, but it need not worry about the actual line parsing call. The parsing framework calls the line parser internally.

GENERAL BEHAVIOUR: See the javadoc of the helper methods, but generally, as tokens are generated, or alternately, sections of the source string (which is stored internally in a buffer) matched and discarded, the processed subsections are removed from the source string until nothing remains. Some helper methods may just find a pattern but not do anything, others will find the first occurrence of a pattern, and discard all characters from the start of the source to the first encountered pattern.

HANDLING TOKEN TYPES: Based on how javacores are structured, it is assumed that each tag line contains at most one instance of a token type. If two or more of the same token types exist, this is indicative that the line should be split into two or more separate javacore tag lines. Consequently, only at most one instance of a token type is added to the token map. If the token type already exists in the map, it will be overwritten.

The parser framework will execute the line parsing logic implemented by the concrete subclass and return a list of tokens (generally a map, where the key is the token type, and the value is the token value) to the section parser that uses these line rules. A series of line rules can be registered into a Tag Parser, which in turn gets used by a Section Parser.

Note that methods are provided to explicitly generate and add a token, and the concrete-class must call these methods explicitly to add a token.

See Also:

  • Field Details

    • fSource

      protected final StringBuffer fSource

    • fCharSubSet

      protected final StringBuffer fCharSubSet

    • fLineNumber

      protected int fLineNumber

    • fOffset

      protected int fOffset

  • Constructor Details

    • LineRule

      public LineRule()

  • Method Details

    • parseLine

      public IAttributeValueMap parseLine(String source, int lineNumber, int startingOffset)
      Initializes buffer, token list, and other fields prior to parsing and tokenising a line. The user-implemented method that parses the line is called here. This method is called internally by the framework, so the user never needs to explicitly call this method.
      Specified by:
      parseLine in interface ILineRule
      Parameters:
      source - string containing source to parse
      lineNumber - line number on file of source
      startingOffset - offset of the first character in the source line. offsets are determined externally from the start of the file.
      Returns:
      attribute value map containing parsed tokens.

    • getLineNumber

      protected int getLineNumber()
      Returns:
      line number on disk of the source line being parsed.

    • processLine

      protected abstract void processLine(String source, int startingOffset)
      Must be implemented by the subtype. It gets called internally by the parser framework, so the user need not worry about calling this explicitly.
      Parameters:
      startingOffset -
      source - to be parsed.

    • addToken

      protected IParserToken addToken(String type, Matcher matcher)
      Adds a token of the type specified via argument to the internal token map, and assigns it the value matched by the pattern matcher. The generated token is returned, or null if no pattern was matched.

      If the token type already exists in the token map, it overwrites the value with the new token.
      Parameters:
      type - of the token to be generated
      matcher - containing pattern to match. the value matched is assigned as the value of the token
      Returns:
      generated token if match is successful, or null otherwise

    • addToken

      protected void addToken(IParserToken token)
      Adds a non-null token to the token map. If the token type already exists, it overwrites the value.
      Parameters:
      token -

    • addToken

      protected IParserToken addToken(String type, String value)
      Adds a token of the type specified to the internal token list and assigns it the value specified by the argument. Returns the generated token.

      If the token type already exists in the token map, it overwrites the value with the new token.
      Parameters:
      type - of the token
      value - of the token
      Returns:
      generated token.

    • addAllCharactersAsTokenAndConsumeFirstMatch

      protected IParserToken addAllCharactersAsTokenAndConsumeFirstMatch(String type, Matcher matcher)
      Grabs all characters up to the first match specified by the matcher, and adds the latter as a token of a argument-specified type to the internal token list. All the aforementioned characters as well as the first pattern matched are removed from the source buffer. The matched pattern is not included in the token.

      If the token type already exists in the token map, it overwrites the value with the new token.
      Parameters:
      type -
      matcher -
      Returns:
      generated token if match found, or null otherwise

    • addAllCharactersAsTokenUntilFirstMatch

      protected IParserToken addAllCharactersAsTokenUntilFirstMatch(String type, Matcher matcher)
      Grabs all characters up to but excluding the first match specified by the matcher, and adds the latter as a token of an argument-specified type.

      If the token type already exists in the token map, it overwrites the value with the new token.
      Parameters:
      type -
      matcher -
      Returns:
      generated token if match found, or null otherwise

    • addAllCharactersAsTokenUntilIndex

      protected IParserToken addAllCharactersAsTokenUntilIndex(String type, int endIndex, boolean stripTrailingWhitespace)
      Copies all characters from start to endIndex - 1. Also gives the option to strip trailing whitespace.

      If the token type already exists in the token map, it overwrites the value with the new token.
      Parameters:
      type - token type
      endIndex -
      stripTrailingWhitespace - if whitespace starting from endIndex - 1 to n, where n >=0 && n < endIndex.
      Returns:
      generated token
      Throws:
      IndexOutOfBoundsException - if endIndex > source buffer length || endIndex <= 0

    • addNonPrefixedHexToken

      protected IParserToken addNonPrefixedHexToken(String type)
      Matches the first hexadecimal match encountered that is not prefixed by "0x" as a token. The latter is then prefixed to the value of the token before generating the token.

      If the token type already exists in the token map, it overwrites the value with the new token.
      Parameters:
      type - of token to be generated
      Returns:
      generated token if hexadecimal match found, or null otherwise.

    • addPrefixedHexToken

      protected IParserToken addPrefixedHexToken(String type)
      Matches the first prefixed hexadecimal pattern encountered, and adds it as a token. Pattern, and all characters prior to the pattern are consumed from the buffer.

      If the token type already exists in the token map, it overwrites the value with the new token.
      Parameters:
      type - of token to be generated
      Returns:
      generated token, if match found, or null otherwise

    • matchAndConsumeValue

      protected String matchAndConsumeValue(Matcher matcher)
      Finds the first occurrence of the pattern in the source.
      Returns the character sequence that matched that pattern.
      Deletes any character sequences from the start of the source to the end of the matched character sequence, and retains the remainder characters for further analysis.
      Parameters:
      matcher - containing pattern to match
      Returns:
      string value or null

    • consumeCharacters

      protected String consumeCharacters(int startIndex, int endIndex)
      Consumes a section of characters from the buffer.
      Parameters:
      startIndex - inclusive
      endIndex - exclusive
      Returns:
      String value of consumed characters
      Throws:
      IndexOutOfBoundsException - if start and end are outside the buffer range.

    • consumeUntilFirstMatch

      protected boolean consumeUntilFirstMatch(Matcher matcher)
      Matches the first occurrence of the pattern and consumes all characters from the start of the buffer until the first occurrence of the pattern. The pattern itself is also consumed. No tokens are generated.
      Parameters:
      matcher -
      Returns:
      true if matched and consumed, false otherwise

    • findFirst

      protected boolean findFirst(Matcher matcher)
      Finds the first match. No consumption or token generation occurs. The buffer state is left intact.
      Parameters:
      matcher -
      Returns:
      true if match found, false otherwise

    • indexOfLast

      protected int indexOfLast(Matcher matcher)
      Returns the starting index of the last matched pattern, but doesn't consume anything or generate tokens.
      Parameters:
      matcher -
      Returns:
      starting index of last match, or -1 if nothing found