Class PathParser

  • All Implemented Interfaces:
    java.lang.Iterable<java.lang.String>, Expression

    class PathParser
    extends java.lang.Object
    implements Expression
    The PathParser object is used to parse XPath paths. This will parse a subset of the XPath expression syntax, such that the path can be used to identify and navigate various XML structures. Example paths that this can parse are as follows.
     
        ./example/path
        ./example[2]/path/
        example/path
        example/path/@attribute
        ./path/@attribute 
        
     
    If the parsed path does not match an XPath expression similar to the above then an exception is thrown. Once parsed the segments of the path can be used to traverse data structures modelled on an XML document or fragment.
    See Also:
    ExpressionBuilder
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private class  PathParser.PathSection
      The PathSection represents a section of a path that is extracted.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected boolean attribute
      This is used to determine if the path is an attribute.
      protected Cache<java.lang.String> attributes
      This is used to cache the attributes created by this path.
      protected java.lang.StringBuilder builder
      This is used to build a fully qualified path expression.
      protected java.lang.String cache
      This is the the cached canonical representation of the path.
      protected int count
      This represents the number of characters in the source path.
      protected char[] data
      This is a copy of the source data that is to be parsed.
      protected Cache<java.lang.String> elements
      This is used to cache the elements created by this path.
      protected java.util.List<java.lang.Integer> indexes
      This contains a list of the indexes for each path segment.
      protected java.lang.String location
      This is the fully qualified path expression for this.
      protected java.util.List<java.lang.String> names
      This contains a list of the path segments that were parsed.
      protected int off
      This is the current seek position for the parser.
      protected java.lang.String path
      This is a cache of the canonical path representation.
      protected java.util.List<java.lang.String> prefixes
      This is used to store the path prefixes for the parsed path.
      protected int start
      This is the start offset that skips any root references.
      protected Style style
      This is the format used to style the path segments.
      protected Type type
      This is the type the expressions are to be parsed for.
    • Constructor Summary

      Constructors 
      Constructor Description
      PathParser​(java.lang.String path, Type type, Format format)
      Constructor for the PathParser object.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void align()
      This is used to add a default index to a segment or attribute extracted from the source expression.
      private void attribute()
      This is used to extract an attribute from the path expression.
      private void attribute​(int start, int count)
      This will add a path segment to the list of segments.
      private void attribute​(java.lang.String segment)
      This will insert the path segment provided.
      private void build()
      This method is used to build a fully qualified path that has each segment index.
      private void element()
      This is used to extract an element from the path expression.
      private void element​(int start, int count)
      This will add a path segment to the list of segments.
      private void element​(java.lang.String segment)
      This will insert the path segment provided.
      java.lang.String getAttribute​(java.lang.String name)
      This is used to acquire the attribute path using this XPath expression.
      protected java.lang.String getAttributePath​(java.lang.String path, java.lang.String name)
      This is used to acquire the attribute path using this XPath expression.
      java.lang.String getElement​(java.lang.String name)
      This is used to acquire the element path using this XPath expression.
      protected java.lang.String getElementPath​(java.lang.String path, java.lang.String name)
      This is used to acquire the element path using this XPath expression.
      java.lang.String getFirst()
      This can be used to acquire the first path segment within the expression.
      int getIndex()
      If the first path segment contains an index it is provided by this method.
      java.lang.String getLast()
      This can be used to acquire the last path segment within the expression.
      java.lang.String getPath()
      This location contains the full path expression with all of the indexes explicitly shown for each path segment.
      Expression getPath​(int from)
      This allows an expression to be extracted from the current context.
      Expression getPath​(int from, int trim)
      This allows an expression to be extracted from the current context.
      java.lang.String getPrefix()
      This is used to extract a namespace prefix from the path expression.
      private void index()
      This is used to extract an index from an element.
      boolean isAttribute()
      This is used to determine if the expression points to an attribute value.
      private boolean isDigit​(char value)
      This is used to determine if the provided character is a digit.
      boolean isEmpty()
      This method is used to determine if this expression is an empty path.
      private boolean isEmpty​(java.lang.String text)
      This is used to determine if a string is empty.
      private boolean isLetter​(char value)
      This is used to determine if the provided character is an alpha numeric character.
      boolean isPath()
      This is used to determine if the expression is a path.
      private boolean isSpecial​(char value)
      This is used to determine if the provided character is a legal XML element character.
      private boolean isValid​(char value)
      This is used to determine if the provided character is a legal XML element character.
      java.util.Iterator<java.lang.String> iterator()
      This is used to iterate over the path segments that have been extracted from the source XPath expression.
      private void parse​(java.lang.String path)
      This method is used to parse the provided XPath expression.
      private void path()
      This method is used to parse the provided XPath expression.
      private void segment()
      This method is used to extract a path segment from the source expression.
      private void skip()
      This is used to skip any root prefix for the path.
      java.lang.String toString()
      Provides a canonical XPath expression.
      private void truncate()
      This method is used to trim any trailing characters at the end of the path.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator
    • Field Detail

      • attributes

        protected Cache<java.lang.String> attributes
        This is used to cache the attributes created by this path.
      • elements

        protected Cache<java.lang.String> elements
        This is used to cache the elements created by this path.
      • indexes

        protected java.util.List<java.lang.Integer> indexes
        This contains a list of the indexes for each path segment.
      • prefixes

        protected java.util.List<java.lang.String> prefixes
        This is used to store the path prefixes for the parsed path.
      • names

        protected java.util.List<java.lang.String> names
        This contains a list of the path segments that were parsed.
      • builder

        protected java.lang.StringBuilder builder
        This is used to build a fully qualified path expression.
      • location

        protected java.lang.String location
        This is the fully qualified path expression for this.
      • cache

        protected java.lang.String cache
        This is the the cached canonical representation of the path.
      • path

        protected java.lang.String path
        This is a cache of the canonical path representation.
      • style

        protected Style style
        This is the format used to style the path segments.
      • type

        protected Type type
        This is the type the expressions are to be parsed for.
      • attribute

        protected boolean attribute
        This is used to determine if the path is an attribute.
      • data

        protected char[] data
        This is a copy of the source data that is to be parsed.
      • count

        protected int count
        This represents the number of characters in the source path.
      • start

        protected int start
        This is the start offset that skips any root references.
      • off

        protected int off
        This is the current seek position for the parser.
    • Constructor Detail

      • PathParser

        public PathParser​(java.lang.String path,
                          Type type,
                          Format format)
                   throws java.lang.Exception
        Constructor for the PathParser object. This must be given a valid XPath expression. Currently only a subset of the XPath syntax is supported by this parser. Once finished the parser will contain all the extracted path segments.
        Parameters:
        path - this is the XPath expression to be parsed
        type - this is the type the expressions are parsed for
        format - this is the format used to style the path
        Throws:
        java.lang.Exception
    • Method Detail

      • isEmpty

        public boolean isEmpty()
        This method is used to determine if this expression is an empty path. An empty path can be represented by a single period, '.'. It identifies the current path.
        Specified by:
        isEmpty in interface Expression
        Returns:
        returns true if this represents an empty path
      • isPath

        public boolean isPath()
        This is used to determine if the expression is a path. An expression represents a path if it contains more than one segment. If only one segment exists it is an element name.
        Specified by:
        isPath in interface Expression
        Returns:
        true if this contains more than one segment
      • isAttribute

        public boolean isAttribute()
        This is used to determine if the expression points to an attribute value. An attribute value contains an '@' character before the last segment name. Such expressions distinguish element references from attribute references.
        Specified by:
        isAttribute in interface Expression
        Returns:
        this returns true if the path has an attribute
      • getIndex

        public int getIndex()
        If the first path segment contains an index it is provided by this method. There may be several indexes within a path, however only the index at the first segment is issued by this method. If there is no index this will return 1.
        Specified by:
        getIndex in interface Expression
        Returns:
        this returns the index of this path expression
      • getPrefix

        public java.lang.String getPrefix()
        This is used to extract a namespace prefix from the path expression. A prefix is used to qualify the XML element name and does not form part of the actual path structure. This can be used to add the namespace in addition to the name.
        Specified by:
        getPrefix in interface Expression
        Returns:
        this returns the prefix for the path expression
      • getFirst

        public java.lang.String getFirst()
        This can be used to acquire the first path segment within the expression. The first segment represents the parent XML element of the path. All segments returned do not contain any slashes and so represents the real element name.
        Specified by:
        getFirst in interface Expression
        Returns:
        this returns the parent element for the path
      • getLast

        public java.lang.String getLast()
        This can be used to acquire the last path segment within the expression. The last segment represents the leaf XML element of the path. All segments returned do not contain any slashes and so represents the real element name.
        Specified by:
        getLast in interface Expression
        Returns:
        this returns the leaf element for the path
      • getPath

        public java.lang.String getPath()
        This location contains the full path expression with all of the indexes explicitly shown for each path segment. This is used to create a uniform representation that can be used for comparisons of different path expressions.
        Specified by:
        getPath in interface Expression
        Returns:
        this returns an expanded version of the path
      • getElement

        public java.lang.String getElement​(java.lang.String name)
        This is used to acquire the element path using this XPath expression. The element path is simply the fully qualified path for this expression with the provided name appended. If this is an empty path, the provided name is returned.
        Specified by:
        getElement in interface Expression
        Parameters:
        name - this is the name of the element to be used
        Returns:
        a fully qualified path for the specified name
      • getElementPath

        protected java.lang.String getElementPath​(java.lang.String path,
                                                  java.lang.String name)
        This is used to acquire the element path using this XPath expression. The element path is simply the fully qualified path for this expression with the provided name appended. If this is an empty path, the provided name is returned.
        Parameters:
        path - this is the path expression to be used
        name - this is the name of the element to be used
        Returns:
        a fully qualified path for the specified name
      • getAttribute

        public java.lang.String getAttribute​(java.lang.String name)
        This is used to acquire the attribute path using this XPath expression. The attribute path is simply the fully qualified path for this expression with the provided name appended. If this is an empty path, the provided name is returned.
        Specified by:
        getAttribute in interface Expression
        Parameters:
        name - this is the name of the attribute to be used
        Returns:
        a fully qualified path for the specified name
      • getAttributePath

        protected java.lang.String getAttributePath​(java.lang.String path,
                                                    java.lang.String name)
        This is used to acquire the attribute path using this XPath expression. The attribute path is simply the fully qualified path for this expression with the provided name appended. If this is an empty path, the provided name is returned.
        Parameters:
        path - this is the path expression to be used
        name - this is the name of the attribute to be used
        Returns:
        a fully qualified path for the specified name
      • iterator

        public java.util.Iterator<java.lang.String> iterator()
        This is used to iterate over the path segments that have been extracted from the source XPath expression. Iteration over the segments is done in the order they were parsed from the source path.
        Specified by:
        iterator in interface java.lang.Iterable<java.lang.String>
        Returns:
        this returns an iterator for the path segments
      • getPath

        public Expression getPath​(int from)
        This allows an expression to be extracted from the current context. Extracting expressions in this manner makes it more convenient for navigating structures representing the XML document. If an expression can not be extracted with the given criteria an exception will be thrown.
        Specified by:
        getPath in interface Expression
        Parameters:
        from - this is the number of segments to skip to
        Returns:
        this returns an expression from this one
      • getPath

        public Expression getPath​(int from,
                                  int trim)
        This allows an expression to be extracted from the current context. Extracting expressions in this manner makes it more convenient for navigating structures representing the XML document. If an expression can not be extracted with the given criteria an exception will be thrown.
        Specified by:
        getPath in interface Expression
        Parameters:
        from - this is the number of segments to skip to
        trim - the number of segments to trim from the end
        Returns:
        this returns an expression from this one
      • parse

        private void parse​(java.lang.String path)
                    throws java.lang.Exception
        This method is used to parse the provided XPath expression. When parsing the expression this will trim any references to the root context, also any trailing slashes are removed. An exception is thrown if the path is invalid.
        Parameters:
        path - this is the XPath expression to be parsed
        Throws:
        java.lang.Exception
      • path

        private void path()
                   throws java.lang.Exception
        This method is used to parse the provided XPath expression. When parsing the expression this will trim any references to the root context, also any trailing slashes are removed. An exception is thrown if the path is invalid.
        Throws:
        java.lang.Exception
      • build

        private void build()
        This method is used to build a fully qualified path that has each segment index. Building a path in this manner ensures that a parsed path can have a unique string that identifies the exact XML element the expression points to.
      • skip

        private void skip()
                   throws java.lang.Exception
        This is used to skip any root prefix for the path. Skipping the root prefix ensures that it is not considered as a valid path segment and so is not returned as part of the iterator nor is it considered with building a string representation.
        Throws:
        java.lang.Exception
      • segment

        private void segment()
                      throws java.lang.Exception
        This method is used to extract a path segment from the source expression. Before extracting the segment this validates the input to ensure it represents a valid path. If the path is not valid then this will thrown an exception.
        Throws:
        java.lang.Exception
      • element

        private void element()
                      throws java.lang.Exception
        This is used to extract an element from the path expression. An element value is one that contains only alphanumeric values or any special characters allowed within an XML element name. If an illegal character is found an exception is thrown.
        Throws:
        java.lang.Exception
      • attribute

        private void attribute()
                        throws java.lang.Exception
        This is used to extract an attribute from the path expression. An attribute value is one that contains only alphanumeric values or any special characters allowed within an XML attribute name. If an illegal character is found an exception is thrown.
        Throws:
        java.lang.Exception
      • index

        private void index()
                    throws java.lang.Exception
        This is used to extract an index from an element. An index is a numerical value that identifies the position of the path within the XML document. If the index can not be extracted from the expression an exception is thrown.
        Throws:
        java.lang.Exception
      • truncate

        private void truncate()
                       throws java.lang.Exception
        This method is used to trim any trailing characters at the end of the path. Trimming will remove any trailing legal characters at the end of the path that we do not want in a canonical string representation of the path expression.
        Throws:
        java.lang.Exception
      • align

        private void align()
                    throws java.lang.Exception
        This is used to add a default index to a segment or attribute extracted from the source expression. In the event that a segment does not contain an index, the default index of 1 is assigned to the element for consistency.
        Throws:
        java.lang.Exception
      • isEmpty

        private boolean isEmpty​(java.lang.String text)
        This is used to determine if a string is empty. A string is considered empty if it is null or of zero length.
        Parameters:
        text - this is the text to check if it is empty
        Returns:
        this returns true if the string is empty or null
      • isDigit

        private boolean isDigit​(char value)
        This is used to determine if the provided character is a digit. Only digits can be used within a segment index, so this is used when parsing the index to ensure all characters are valid.
        Parameters:
        value - this is the value of the character
        Returns:
        this returns true if the provide character is a digit
      • isValid

        private boolean isValid​(char value)
        This is used to determine if the provided character is a legal XML element character. This is used to ensure all extracted element names conform to legal element names.
        Parameters:
        value - this is the value of the character
        Returns:
        this returns true if the provided character is legal
      • isSpecial

        private boolean isSpecial​(char value)
        This is used to determine if the provided character is a legal XML element character. This is used to ensure all extracted element and attribute names conform to the XML specification.
        Parameters:
        value - this is the value of the character
        Returns:
        this returns true if the provided character is legal
      • isLetter

        private boolean isLetter​(char value)
        This is used to determine if the provided character is an alpha numeric character. This is used to ensure all extracted element and attribute names conform to the XML specification.
        Parameters:
        value - this is the value of the character
        Returns:
        this returns true if the provided character is legal
      • element

        private void element​(int start,
                             int count)
        This will add a path segment to the list of segments. A path segment is added only if it has at least one character. All segments can be iterated over when parsing has completed.
        Parameters:
        start - this is the start offset for the path segment
        count - this is the number of characters in the segment
      • attribute

        private void attribute​(int start,
                               int count)
        This will add a path segment to the list of segments. A path segment is added only if it has at least one character. All segments can be iterated over when parsing has completed.
        Parameters:
        start - this is the start offset for the path segment
        count - this is the number of characters in the segment
      • element

        private void element​(java.lang.String segment)
        This will insert the path segment provided. A path segment is represented by an optional namespace prefix and an XML element name. If there is no prefix then a null is entered this will ensure that the names and segments are kept aligned by index.
        Parameters:
        segment - this is the path segment to be inserted
      • attribute

        private void attribute​(java.lang.String segment)
        This will insert the path segment provided. A path segment is represented by an optional namespace prefix and an XML element name. If there is no prefix then a null is entered this will ensure that the names and segments are kept aligned by index.
        Parameters:
        segment - this is the path segment to be inserted
      • toString

        public java.lang.String toString()
        Provides a canonical XPath expression. This is used for both debugging and reporting. The path returned represents the original path that has been parsed to form the expression.
        Specified by:
        toString in interface Expression
        Overrides:
        toString in class java.lang.Object
        Returns:
        this returns the string format for the XPath