Package com.automation_pros.odva.cip.path

Class CipPath

  • All Implemented Interfaces:
    java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<CipPath>, java.lang.Iterable<PathSegment>, java.util.Collection<PathSegment>, java.util.List<PathSegment>, java.util.RandomAccess
    public class CipPath
extends java.util.ArrayList<PathSegment>
implements java.io.Externalizable, java.lang.Comparable<CipPath>

    An ordered list of Path Segments to be used as a locator for CIP objects, data elements, and/or network nodes in the various services in the CIP specification. Instances may be constructed from individual items, collections of items, or string representations of items. Use PathSegment.decodeAll() to construct an instance from encoded bytes.

    See Also:
    Serialized Form

    • Field Detail

      • keywords

        public static final java.util.Map<java.lang.String,​PathTokenParser> keywords

      • typewords

        public static final java.util.Map<java.lang.String,​TypeTokenParser> typewords

      • sLogger

        public static final org.slf4j.Logger sLogger

      • emptyPath

        public static final CipPath emptyPath

      • identifierPattern

        public static final java.util.regex.Pattern identifierPattern

      • alignPattern

        public static final java.util.regex.Pattern alignPattern

      • nonIdentifierChars

        public static final java.util.regex.Pattern nonIdentifierChars

      • tokenModeIncompatible

        public static final java.util.regex.Pattern tokenModeIncompatible

      • locked

        protected boolean locked

    • Constructor Detail

      • CipPath

        public CipPath()

      • CipPath

        public CipPath​(PathSegment... segments)
        Construct an instance from individual path segments.
        Parameters:
        segments - Items to assemble, in order, into the new instance.

      • CipPath

        public CipPath​(int initialCapacity)
        Construct an empty instance.
        Parameters:
        initialCapacity - The @{link java.util.ArrayList ArrayList} capacity to pass to the superclass.

      • CipPath

        public CipPath​(java.util.Collection<? extends PathSegment> segments)
        Construct an instance from a collection of path segments, in the collection's natural order.
        Parameters:
        segments - Items to assemble into the new instance.

    • Method Detail

      • compare

        public static int compare​(java.util.List<PathSegment> path0,
                          java.util.List<PathSegment> path1)
        Helper function to compare lists of Path Segments, even when not instantiated as a CipPath object.
        Parameters:
        path0 -
        path1 -
        Returns:

      • registerKeyword

        public static PathTokenParser registerKeyword​(java.lang.String key,
                                              PathTokenParser handler)

        Register a string parser for a given path keyword.

        When the path string parser encounters parentheses, square brackets, or curly braces, it switches to keyword mode. All of the text inside the parentheses is tokenized, then passed to successive keyword handlers until all tokens are consumed.

        The List<> passed to the handler will be modifiable, and the handler must remove the tokens it consumes. The keyword itself is popped before the handler is called.

        Parameters:
        key - The lowercase keyword that triggers this handler
        handler - Object that will process this keyword
        Returns:
        The handler previously registered for this keyword, or null.

      • getKeyword

        public static PathTokenParser getKeyword​(java.lang.String key)

      • getTypeword

        public static TypeTokenParser getTypeword​(java.lang.String key)

      • parseType

        public static DataDefinitionSeg parseType​(java.lang.String first,
                                          java.util.List<java.lang.String> tokens,
                                          boolean typeOnly)

      • parse

        public static CipPath parse​(java.util.List<java.lang.String> tokens)
        Construct a complete path from a list of string tokens and arguments. Parentheses surround a nested data type definition. Otherwise, a series of data type keywords will be combined into an anonymous structure. Keywords followed by an equals sign become the member name for the data type following the equals.
        Parameters:
        tokens - String tokens followed by the string arguments they will need. Parentheses, brackets, braces, and equals should be passed as individual tokens.
        Returns:
        The path instance.

      • route

        public static CipPath route​(java.util.List<java.lang.String> tokens)
        Construct a route path from a list of port & address token pairs.
        Parameters:
        tokens - A list of individual tokens containing pairs of arguments for the Port Segment token parser. Basically the same format documented for use in Allen-Bradley Logix Message Instructions' "Connection Path" elements.
        Returns:
        A path instance contain only Port Segments.

      • parseTag

        public static CipPath parseTag​(java.lang.String path)
        Decode a string containing a complete human-readable object path.

        The string must have the following explicit format: 

        (keyword args... keyword ...)tagpath

        The keyword section and the tagpath section are both optional and may be repeated. Any keyword section may include data type definition segments. Data type definitions may include tokens of the form keyname=keyword, which will be interpreted as named members of an implicit, anonymous CIP structure. Nested open parentheses introduce an explicit anonymous CIP structure. Data type definitions may be followed by square-bracketed dimensions, delimited by commas or whitespace.

        An empty string yields an empty list of path segments. Whitespace or commas may separate token in a keyword section. Whitespace is not allowed in a tagpath section. In a tagpath section, commas are only allowed separating multiple array subscripts.

        The tagpath must follow normal syntax rules for Logix Tag names including structure member names and array subscripts. Tag and structure member names will produce Ansi Symbol segments. Array subscripts will generate Member Logical segments. Trailing bit reference will generate an Extended Logical segment. A nested tagpath may be used as an array subscript and will be wrapped in the appropriate Extended Logical segment.

        Parameters:
        path - String containing a generic CIP Path and/or Logix Tag Path
        Returns:
        The corresponding path segment objects.

      • parseTag

        public static CipPath parseTag​(java.io.StreamTokenizer st)

      • decodeHex

        public static java.nio.ByteBuffer decodeHex​(java.lang.String source)

      • encodeHex

        public static java.lang.String encodeHex​(java.nio.ByteBuffer b)

      • parse

        public static CipPath parse​(java.lang.String path)

        Parse a path string in one of three forms:

        1. A tagpath with optional braced/bracketed/parenthesized token string as described for parseTag(),
        2. A token string, or
        3. A packed or padded hexadecimal byte string, as found in electronic data sheets. If a hex string but not decodable, the problem will be reported from the padded encoding perspective.
        Parameters:
        path - The string to parse for a path
        Returns:

      • add

        public boolean add​(PathSegment pathSegment)
        Specified by:
        add in interface java.util.Collection<PathSegment>
        Specified by:
        add in interface java.util.List<PathSegment>
        Overrides:
        add in class java.util.ArrayList<PathSegment>

      • add

        public void add​(int index,
                PathSegment element)
        Specified by:
        add in interface java.util.List<PathSegment>
        Overrides:
        add in class java.util.ArrayList<PathSegment>

      • remove

        public PathSegment remove​(int index)
        Specified by:
        remove in interface java.util.List<PathSegment>
        Overrides:
        remove in class java.util.ArrayList<PathSegment>

      • remove

        public boolean remove​(java.lang.Object o)
        Specified by:
        remove in interface java.util.Collection<PathSegment>
        Specified by:
        remove in interface java.util.List<PathSegment>
        Overrides:
        remove in class java.util.ArrayList<PathSegment>

      • clear

        public void clear()
        Specified by:
        clear in interface java.util.Collection<PathSegment>
        Specified by:
        clear in interface java.util.List<PathSegment>
        Overrides:
        clear in class java.util.ArrayList<PathSegment>

      • addAll

        public boolean addAll​(java.util.Collection<? extends PathSegment> c)
        Specified by:
        addAll in interface java.util.Collection<PathSegment>
        Specified by:
        addAll in interface java.util.List<PathSegment>
        Overrides:
        addAll in class java.util.ArrayList<PathSegment>

      • addAll

        public boolean addAll​(int index,
                      java.util.Collection<? extends PathSegment> c)
        Specified by:
        addAll in interface java.util.List<PathSegment>
        Overrides:
        addAll in class java.util.ArrayList<PathSegment>

      • removeRange

        protected void removeRange​(int fromIndex,
                           int toIndex)
        Overrides:
        removeRange in class java.util.ArrayList<PathSegment>

      • removeAll

        public boolean removeAll​(java.util.Collection<?> c)
        Specified by:
        removeAll in interface java.util.Collection<PathSegment>
        Specified by:
        removeAll in interface java.util.List<PathSegment>
        Overrides:
        removeAll in class java.util.ArrayList<PathSegment>

      • listIterator

        public java.util.ListIterator<PathSegment> listIterator​(int index)
        Specified by:
        listIterator in interface java.util.List<PathSegment>
        Overrides:
        listIterator in class java.util.ArrayList<PathSegment>

      • listIterator

        public java.util.ListIterator<PathSegment> listIterator()
        Specified by:
        listIterator in interface java.util.List<PathSegment>
        Overrides:
        listIterator in class java.util.ArrayList<PathSegment>

      • iterator

        public java.util.Iterator<PathSegment> iterator()
        Specified by:
        iterator in interface java.util.Collection<PathSegment>
        Specified by:
        iterator in interface java.lang.Iterable<PathSegment>
        Specified by:
        iterator in interface java.util.List<PathSegment>
        Overrides:
        iterator in class java.util.ArrayList<PathSegment>

      • spliterator

        public java.util.Spliterator<PathSegment> spliterator()
        Specified by:
        spliterator in interface java.util.Collection<PathSegment>
        Specified by:
        spliterator in interface java.lang.Iterable<PathSegment>
        Specified by:
        spliterator in interface java.util.List<PathSegment>
        Overrides:
        spliterator in class java.util.ArrayList<PathSegment>

      • removeIf

        public boolean removeIf​(java.util.function.Predicate<? super PathSegment> filter)
        Specified by:
        removeIf in interface java.util.Collection<PathSegment>
        Overrides:
        removeIf in class java.util.ArrayList<PathSegment>

      • replaceAll

        public void replaceAll​(java.util.function.UnaryOperator<PathSegment> operator)
        Specified by:
        replaceAll in interface java.util.List<PathSegment>
        Overrides:
        replaceAll in class java.util.ArrayList<PathSegment>

      • sort

        public void sort​(java.util.Comparator<? super PathSegment> c)
        Specified by:
        sort in interface java.util.List<PathSegment>
        Overrides:
        sort in class java.util.ArrayList<PathSegment>

      • getBytes

        public int getBytes()
        Compute the total number of bytes in the packed encoding of this path.
        Returns:
        Number of bytes.

      • getWords

        public int getWords()
        Compute the total number of 16-bit words in the padded encoding of this path. Multiply by two for the byte length.
        Returns:

      • encodeAll

        public void encodeAll​(boolean padded,
                      java.nio.ByteBuffer dest)
        Construct the encoded form of all of the items in this path. Does not include any length element.
        Parameters:
        padded - Format flag, true for padded, false for packed.
        dest - Buffer to receive the encoded form.

      • reDecode

        public CipPath reDecode​(boolean padded)

      • getTokens

        public java.util.List<java.lang.String> getTokens()
        Compute the string tokens that would be needed to regenerate this instance with parse(tokenList).
        Returns:
        A list of string tokens.

      • tokenString

        public java.lang.String tokenString()
        Convenience method to display this instance in token form, possibly not reversibly. Tokens are joined with spaces when
        • either token is quoted, or
        • to prevent identifier merging, or
        • to delimit an identifier character from an open parenthesis.
        Returns:
        A human-readable version of the path's items.

      • hexString

        public java.lang.String hexString​(boolean padded)
        Obtain the encoded form of this path as hexadecimal digits, with a single space delimiting segments.
        Parameters:
        padded - Whether to encode the path into bytes in padded form.
        Returns:
        The hexadecimal string form of the selected encoding.

      • toString

        public java.lang.String toString()
        State machine based encoding of this segment list into a parseable output string.

        A symbol segment always switches out of token mode.

        State 0 = prior was tokens State 1 = prior was symbol State 2 = prior was subscript State 3 = prior was bit

        Overrides:
        toString in class java.util.AbstractCollection<PathSegment>

      • compareTo

        public int compareTo​(CipPath path1)
        Specified by:
        compareTo in interface java.lang.Comparable<CipPath>

      • readExternal

        public void readExternal​(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException
        CIP paths are deserialized by retrieving the byte array and decoding it directly.
        Specified by:
        readExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException

      • writeExternal

        public void writeExternal​(java.io.ObjectOutput out)
                   throws java.io.IOException
        CIP paths are serialized in padded byte encoded form.
        Specified by:
        writeExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException

      • describe

        public static void describe​(CipPath p)

      • fragmentTest

        public static CipPath fragmentTest​(java.lang.String sample)

      • parseTest

        public static CipPath parseTest​(java.lang.String sample)

      • main

        public static void main​(java.lang.String[] args)