Package com.automation_pros.odva.cip.path

Class PathSegment

  • All Implemented Interfaces:
    java.lang.Comparable<PathSegment>
    Direct Known Subclasses:
    AnsiSymbolSeg, DataDefinitionSeg, LogicalSeg, NetworkSeg, PortSeg, SimpleDataSeg, SymbolicSeg
    public abstract class PathSegment
extends java.lang.Object
implements java.lang.Comparable<PathSegment>
    In CIP, "Segments" encode various pieces of information that are then used to locate objects within a device's internal address space. Most common are the ClassSeg, InstanceSeg, and AttributeSeg number encodings that all CIP devices must support. Symbols, configuration data, port addresses, and network parameters are also encoded in segments. The first byte of an encoded segment indicates the general type of information it contains, and may implicitly indicate the number of encoded bytes to follow. Details of each encoding are published in the CIP Specification, Volume 1, Appendix C.

    Many of the encodings have different layouts when used in "Packed" versus "Padded" contexts. When encoding and decoding in this package, the desired alternative is signaled by the "padded" method argument.

    As noted in that appendix C, § 1.1, the leading byte of the encoding encompasses encodings for data types, including complex structured and/or array data types. The segment implementations in this package that fall in that category are collected under the DataDefinitionSeg abstract class. These data type segments can be used to construct instances of the encoded data types in a given context.

    The DataDefinitionSeg class implements the core functions of each kind of encoder/decoder, and sets the behavioral expectations for all data definitions. This implementation goes beyond the public specification to define encodings for all types and variations of types commonly used in applications, including those implied by the object definitions of the specification. A summary of extensions:

    • Arrays can be defined with type code 0xa3 as usual, but may have a MemberSeg inserted between the dimension's length and the following data type code. This member segment indicates the unsigned offset to deduct when accessing the array. That is, the array subscripts are to be from "offset" to "offset+length-1" instead of from "0" to "length-1". This may be applied to all dimensions of a multidimensional array.
    • Arrays can also be defined with a variant first dimension, using type code 0xac, followed by one byte containing the number of bytes in the following nested indirect path (always packed). The indirect path can be empty, indicating that the size of the array is determined by the size of the buffer supplied to populate it.
    • Booleans in a structure that are "hosted" by a bit within an integer or word element of the same structure are defined by the HostedBitDefSeg class. This can only occur with the formal definition of a structure. It uses type code 0xad, followed by one byte containing the zero-based bit number within the host element, followed by one path segment indicating the host member by name or zero-based member index.
    • Structured types may be referenced by name with the NamedStructSeg class, that otherwise functions like the AbbrevStructSeg class. It uses segment type code 0xae, which is immediately followed by an AnsiSymbolSeg or SymbolicSeg containing the structure name.
    • Formal types of structures (AnonStructSeg) are extended with seven additional type codes, from 0xa4 through 0xa7, and 0xa9 through 0xab. These codes indicate one byte, two byte, four byte, or eight byte alignment/padding of the structure, or two byte, four byte, or eight byte Logix-style alignment/padding. These codes are followed by an unsigned 16-bit integer of the number of bytes in the complete definition. Each member may be preceded by an AnsiSymbolSeg or SymbolicSeg containing the member name to be accepted for access. Each member will be aligned to the lesser of the structure's alignment and the member's alignment (which is the natural alignment of elementary types), unless using Logix-style alignment, which forces the max alignment to be used for all nested structures and arrays. All eight formal structure type codes allow nested structures identified by AnonStructSeg, AbbrevStructSeg, or NamedStructSeg.

    The elementary data types shown in the CIP Spec, Volume 1, Appendix C, § 6.1, Table 6.1 are all represented by the ElementarySeg class, each as a cached singleton. This class also represents the elementary types specified by Omron's NJ/NX EtherNet/IP User Manual W506 § 8-7-1. The defined constructed data types shown in § 6.2.3, Table 6.16 are represented by the ConstructedDefSeg class, along with the following extensions:

    • Constructed Subtypes 0x00c7 through 0x00c9 represent variations of CipBOOL that use 16-bit, 32-bit, or 64-bit underlying storage (respectively) instead of the 8-bit storage defined by the specification. Corresponding subclasses (CipBOOL16, CipBOOL32, and CipBOOL64) are available as convenience constructors.
    • Constructed Subtype 0x00dc represents a Padded EPATH. The CIP Specification uses both packed and padded EPATHs in various contexts. The packed version is more common, so the padded form was chosen as the "variant" needing an explicit alternate encoding.

    See the CipPath class for details of the string representations of these segment encodings, and the parsing of those string representations back into encoded form.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static interface  PathSegment.HasAlternateHex
      Mark implementations that have nested elements that can have their hex representations shown separately.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String identifierChars  
      byte segtype
      Instances set this to their actual leading byte.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected PathSegment​(byte segtype)  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(PathSegment o)  
      static PathSegment decode​(java.nio.ByteBuffer source, boolean padded)
      Decode bytes expected to contain one encoded path segment.
      static CipPath decodeAll​(java.nio.ByteBuffer source, boolean padded)
      Decode bytes expected to contain a complete encoded path.
      boolean equals​(java.lang.Object obj)  
      abstract int getBytes()
      Obtain the number of bytes needed to encode this segment instance in packed format.
      byte getSegtype()
      Obtain this instance's leading byte
      abstract java.util.List<java.lang.String> getTokens()  
      int getWords()
      Obtain the number of 16-bit words needed to encode this segment instance in padded format.
      java.lang.String hexString​(boolean padded)  
      static java.lang.String mergeTokens​(java.util.List<java.lang.String> tokens)
      Convenience method to combine path segment tokens for display.
      abstract void put​(java.nio.ByteBuffer dest, boolean padded)
      Encode the current instance to the given destination.
      static PathSegmentDecoder registerHandler​(byte type, PathSegmentDecoder handler)
      Register a PathSegment decoding class for a byte stream type code.
      abstract PathSegment set​(java.nio.ByteBuffer source, boolean padded)
      Replace the current instance content with the decoded source bytes.
      void setSegtype​(byte segtype)
      When a single decoder covers multiple indicator byte values, it must be able to adjust its leading byte accordingly.
      abstract java.lang.String simpleString()
      Supply s simple descriptive name usable when browsing a hierarchy.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • segtype

        public byte segtype
        Instances set this to their actual leading byte. Not final since some segment types change their leading byte based on their content.

    • Constructor Detail

      • PathSegment

        protected PathSegment​(byte segtype)

    • Method Detail

      • registerHandler

        public static PathSegmentDecoder registerHandler​(byte type,
                                                 PathSegmentDecoder handler)
        Register a PathSegment decoding class for a byte stream type code.

        Classes not included in this package may register byte stream parsers for their type codes. This includes the option to replace the preloaded handler for a packaged type.

        Parameters:
        type - Byte type code to be handled.
        handler - Object that will process this type code.
        Returns:
        The decode handler previously registered for this code.

      • decode

        public static PathSegment decode​(java.nio.ByteBuffer source,
                                 boolean padded)
        Decode bytes expected to contain one encoded path segment.

        Uses the leading byte to identify the decoder needed and delegates to that decoder. Note that some path segments incorporate nested path segments. The nested elements will also be decoded.

        Parameters:
        source - The bytes to be decoded. The position will be left after the last byte of the decoded segment.
        padded - Alternate format selection. Packed format when false.
        Returns:
        The single segment or data type definition object.

      • decodeAll

        public static CipPath decodeAll​(java.nio.ByteBuffer source,
                                boolean padded)
        Decode bytes expected to contain a complete encoded path.

        Calls decode() multiple times until the source's limit is reached, returning all of the decoded objects. The last encoded object must end precisely at the source's limit.

        Parameters:
        source - The bytes to be decoded. All available bytes will be consumed.
        padded - Alternate format selection. Packed format when false.
        Returns:
        The complete collection of segment and/or data type definition objects.

      • mergeTokens

        public static java.lang.String mergeTokens​(java.util.List<java.lang.String> tokens)
        Convenience method to combine path segment tokens for display. Generally reversible via CipPath.parse(String). 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.

      • getSegtype

        public byte getSegtype()
        Obtain this instance's leading byte

      • setSegtype

        public void setSegtype​(byte segtype)
        When a single decoder covers multiple indicator byte values, it must be able to adjust its leading byte accordingly.
        Parameters:
        segtype - Updated leading byte value

      • getBytes

        public abstract int getBytes()
        Obtain the number of bytes needed to encode this segment instance in packed format.
        Returns:
        Number of bytes, assuming put() will be called with padded false.

      • getWords

        public int getWords()
        Obtain the number of 16-bit words needed to encode this segment instance in padded format. The default implementation assumes the padded format is simply the size of the packed format, rounded up to an even number of bytes.
        Returns:
        Number of words, assuming put() will be called with padded true.

      • set

        public abstract PathSegment set​(java.nio.ByteBuffer source,
                                boolean padded)
        Replace the current instance content with the decoded source bytes.

        The caller must ensure that the instance is appropriate for the bytes supplied. This permits instance re-use in optimized applications.

        Parameters:
        source - The bytes to be decoded. The position will be left after the last byte of the decoded segment.
        padded - Alternate format selection. Packed format when false.
        Returns:
        The same instance.

      • put

        public abstract void put​(java.nio.ByteBuffer dest,
                         boolean padded)
        Encode the current instance to the given destination.
        Parameters:
        dest - The buffer receiving the complete encoded instance.
        padded - Alternate format selection. Packed format when false.

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • compareTo

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

      • getTokens

        public abstract java.util.List<java.lang.String> getTokens()

      • simpleString

        public abstract java.lang.String simpleString()
        Supply s simple descriptive name usable when browsing a hierarchy. A simple type name for elementary types, a non-detailed description for complex types.
        Returns:

      • hexString

        public java.lang.String hexString​(boolean padded)

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object