Interface ItemPath

  • All Superinterfaces:
    Serializable, ShortDumpable
    All Known Subinterfaces:
    UniformItemPath
    All Known Implementing Classes:
    ItemName, ItemPathImpl

    public interface ItemPath
    extends ShortDumpable, Serializable
    General interface to ItemPath objects. A path is viewed as a sequence of path segments. There are three basic implementations of this interface: 1) ItemPathImpl =============== This is memory-optimized implementation, minimizing the number of objects created during initialization. Its segments contain plain objects (e.g. QNames, Longs), mixed with ItemPathSegments where necessary. Please see ItemPathImpl for details. 2) ItemName =========== A subclass of QName representing a single-item path. It eliminates the need to create artificial ItemPath objects to represent a single name. The problem with ItemPathImpl and ItemName is that equals/hashCode methods do not work on them as one would expect. There are too many ways how to represent a given path, so one cannot rely on these methods. (QName.equals and hashCode are final, so they cannot be adapted.) So, if ItemPath is to be used e.g. as a key in HashMap, the original implementation has to be used. 3) UniformItemPathImpl ====================== This is the original implementation. It sees the path as a sequence of ItemPathSegment objects. Its advantage is the reasonable equals/hashCode methods. The disadvantage is the memory intensiveness (creating a high number of tiny objects during path manipulations). Objects of ItemPath type are designed to be immutable. Modification operations in this API always create new objects. Naming convention: - A path consists of SEGMENTS. - However, when creating the path, we provide a sequence of COMPONENTS. We transform components into segments by applying a normalization procedure.
    • Field Detail

      • EMPTY_PATH

        static final ItemPath EMPTY_PATH
    • Method Detail

      • create

        @NotNull
        static @NotNull ItemPath create​(Object... components)
        Creates the path from given components. The components can contain objects of various kinds: - QName -> interpreted as either named segment or a special segment (if the name exactly matches special segment name) - Integer/Long -> interpreted as Id path segment - null -> interpreted as null Id path segment - ItemPathSegment -> interpreted as such - ItemPath, Object[], Collection -> interpreted recursively as a sequence of components Creates the default implementation of ItemPathImpl. Components are normalized on creation as necessary; although the number of object creation is minimized.
      • create

        @NotNull
        static @NotNull ItemPath create​(@NotNull
                                        @NotNull List<?> components)
        Creates the path from given components.
        See Also:
        create(Object...)
      • createReverse

        @NotNull
        static @NotNull ItemPath createReverse​(@NotNull
                                               @NotNull List<?> components)
        Creates the path from given components in reverse direction. E.g. [a, b, c] -> c/b/a
      • isEmpty

        boolean isEmpty()
        Returns true if the path is empty i.e. has no components.
      • isEmpty

        static boolean isEmpty​(ItemPath path)
        Returns true if the path is null or empty.
      • isNotEmpty

        static boolean isNotEmpty​(ItemPath path)
      • size

        int size()
        Returns path size i.e. the number of components.
      • append

        @NotNull
        default @NotNull ItemPath append​(Object... components)
        Returns a newly created path containing all the segments of this path with added components.
      • getSegments

        @NotNull
        @NotNull List<?> getSegments()
        Returns the path segments. Avoid using this method and access segments directly. Instead try to find suitable method in ItemPath interface. NEVER change path content using this method. TODO consider returning unmodifiable collection here (beware of performance implications)
      • getSegment

        @Nullable
        @Nullable Object getSegment​(int i)
        Returns the given path segment.
        Throws:
        IndexOutOfBoundsException - if the index is out of range
      • equivalent

        default boolean equivalent​(ItemPath path)
        Checks if the paths are equivalent. Resolves some differences in path segment representation, e.g. NameItemPathSegment vs QName, null vs missing Id path segments. Does NOT detect higher-level semantic equivalency like activation[1]/administrativeStatus vs activation/administrativeStatus. These are treated as not equivalent.
      • equals

        default boolean equals​(Object other,
                               boolean exact)
        Compares with the other object either literally (exact = true) or via .equivalent (exact = false).
      • isSubPath

        default boolean isSubPath​(ItemPath otherPath)
        Checks if current path is a strict subpath (prefix) of the other path.
      • isSubPathOrEquivalent

        default boolean isSubPathOrEquivalent​(ItemPath otherPath)
        Check if current path is a subpath (prefix) of the other path or they are equivalent.
      • isSuperPath

        default boolean isSuperPath​(ItemPath otherPath)
        Check if the other path is a strict subpath (prefix) of this path. The same as otherPath.isSubPath(this).
      • isSuperPathOrEquivalent

        default boolean isSuperPathOrEquivalent​(ItemPath path)
        Check if the other path is a subpath (prefix) of this path or they are equivalent. The same as otherPath.isSubPathOrEquivalent(this).
      • startsWith

        default boolean startsWith​(ItemPath prefix)
        Convenience method with understandable semantics.
      • isName

        static boolean isName​(Object segment)
        Returns true if the segment is a name segment. Note that special segments (parent, reference, identifier, variable) are NOT considered to be name segments, even if they can be represented using QName.
      • toName

        @NotNull
        static @NotNull ItemName toName​(Object segment)
        Returns a name corresponding to the name segment, or throw an exception otherwise.
      • toNameNullSafe

        @Nullable
        static @Nullable QName toNameNullSafe​(@Nullable
                                              @Nullable Object segment)
        Returns a name corresponding to the name segment, or throw an exception otherwise. However, accepts null segments. TODO determine whether to keep this method
      • toNameOrNull

        @Nullable
        static @Nullable ItemName toNameOrNull​(Object segment)
        Returns a name corresponding to the name segment, or null if it's no name.
      • isId

        static boolean isId​(Object o)
        Returns true if the segment is the container Id.
      • isNullId

        static boolean isNullId​(Object o)
        Returns true if the segment is the container Id with value of NULL.
      • toId

        static Long toId​(Object segment)
        Returns a Long value corresponding to the container Id segment, or throw an exception otherwise.
      • toIdOrNull

        static Long toIdOrNull​(Object segment)
        Returns a Long value corresponding to the container Id segment, or return null otherwise.
      • isSpecial

        static boolean isSpecial​(Object segment)
        Returns true if the segment is a special one: parent, reference, identifier, variable.
      • isParent

        static boolean isParent​(Object segment)
        Returns true if the segment is the Parent one ("..").
      • isObjectReference

        static boolean isObjectReference​(Object segment)
        Returns true if the segment is the Object Reference one ("@").
      • isIdentifier

        static boolean isIdentifier​(Object segment)
        Returns true if the segment is the Identifier one ("#").
      • isVariable

        static boolean isVariable​(Object segment)
        Returns true if the segment is the Variable one ("$...").
      • toVariableName

        static QName toVariableName​(Object segment)
        Returns a name corresponding to the Variable segment, or throw an exception otherwise.
      • first

        @Nullable
        @Nullable Object first()
        Returns the first segment or null if the path is empty.
      • rest

        @NotNull
        default @NotNull ItemPath rest()
        Returns the rest of the path (the tail).
      • rest

        @NotNull
        @NotNull ItemPath rest​(int n)
        Returns the rest of the path (the tail), starting at position "n".
      • firstAsPath

        ItemPath firstAsPath()
        Returns the first segment as an ItemPath. TODO consider the necessity of such method
      • remainder

        default ItemPath remainder​(ItemPath path)
        Returns the remainder of "this" path after passing all segments from the other path. (I.e. this path must begin with the content of the other path. Throws an exception when it is not the case.)
      • last

        @Nullable
        @Nullable Object last()
        Returns the last segment (or null if the path is empty).
      • allExceptLast

        @NotNull
        @NotNull ItemPath allExceptLast()
        Returns all segments except the last one.
      • allUpToIncluding

        default ItemPath allUpToIncluding​(int i)
        Returns all segments up to the specified one (including it).
      • allUpToLastName

        @NotNull
        default @NotNull ItemPath allUpToLastName()
        Returns all segments up to the last named one (excluding). Returns empty path if there's no named segment.
      • subPath

        ItemPath subPath​(int from,
                         int to)
        Returns a sub-path from (including) to (excluding) given indices.
      • startsWithName

        default boolean startsWithName()
        Returns true if the path starts with the standard segment name (i.e. NOT variable nor special symbol).
      • startsWithId

        default boolean startsWithId()
        Returns true if the path starts with with value Id.
      • startsWithNullId

        default boolean startsWithNullId()
        Returns true if the path starts with the value Id of null.
      • startsWithIdentifier

        default boolean startsWithIdentifier()
        Returns true if the path starts with an identifier (#).
      • startsWithVariable

        default boolean startsWithVariable()
        Returns true if the path starts with variable name ($...).
      • startsWithObjectReference

        default boolean startsWithObjectReference()
        Returns true if the path starts with an object reference (@).
      • startsWithParent

        default boolean startsWithParent()
        Returns true if the path starts with a parent segment (..).
      • asSingleName

        default QName asSingleName()
        If the path consists of a single name segment (not variable nor special symbol), returns the corresponding value. Otherwise returns null.
      • asSingleNameOrFail

        @NotNull
        default @NotNull ItemName asSingleNameOrFail()
        If the path consists of a single name segment (not variable nor special symbol), returns the corresponding value. Otherwise throws an exception.
      • isSingleName

        default boolean isSingleName()
        Returns true if the path consists of a single name segment. (Not variable nor special symbol.)
      • firstToName

        @NotNull
        default @NotNull ItemName firstToName()
        Returns the value of the first segment if it is a name segment; otherwise null.
      • firstToNameOrNull

        @Nullable
        default @Nullable ItemName firstToNameOrNull()
        Returns the value of the first segment if it is a name segment; otherwise null.
      • firstToVariableNameOrNull

        default QName firstToVariableNameOrNull()
        Returns the value of the first segment if it is a variable name segment; otherwise null.
      • firstToId

        default Long firstToId()
        Returns the value of the first segment if it is a Id segment; otherwise throws an exception.
      • firstToIdOrNull

        default Long firstToIdOrNull()
        Returns the value of the first segment if it is a Id segment; otherwise null.
      • firstToIdOrNull

        static Long firstToIdOrNull​(ItemPath path)
      • firstName

        @Nullable
        default @Nullable ItemName firstName()
        Returns the value of the first name segment or null if there's no name segment. NOTE: The difference between firstToName and firstName is that the former always looks at the first segment and tries to interpret it as a name. The latter, however, tries to find the first segment of Name type.
      • firstNameOrFail

        @NotNull
        default @NotNull ItemName firstNameOrFail()
        The same as firstName but throws an exception if there's no name.
      • firstNameIndex

        default int firstNameIndex()
        Returns the first name segment index; or -1 if there's no such segment.
      • lastName

        ItemName lastName()
        Returns the last name segment value; or null if there's no name segment.
      • lastNameIndex

        default int lastNameIndex()
        Returns the last name segment index; or -1 if there's no such segment.
      • checkNoSpecialSymbols

        static void checkNoSpecialSymbols​(ItemPath path)
      • checkNoSpecialSymbolsExceptParent

        static void checkNoSpecialSymbolsExceptParent​(ItemPath path)
      • containsSpecialSymbols

        default boolean containsSpecialSymbols()
      • containsSpecialSymbolsExceptParent

        default boolean containsSpecialSymbolsExceptParent()
      • namedSegmentsOnly

        @NotNull
        @NotNull ItemPath namedSegmentsOnly()
        Returns the path containing only the regular named segments.
      • removeIds

        @NotNull
        @NotNull ItemPath removeIds()
        Returns the path with no Id segments.
      • stripVariableSegment

        @NotNull
        default @NotNull ItemPath stripVariableSegment()
        Removes the leading variable segment, if present.
      • containsNameExactly

        default boolean containsNameExactly​(QName name)
        Returns true if the path contains the specified name (requires exact match).
      • startsWithName

        default boolean startsWithName​(QName name)
        Returns true if the path starts with the specified name (approximate match).
      • emptyIfNull

        static ItemPath emptyIfNull​(ItemPath path)
        Converts null ItemPath to empty one.
      • segmentsEquivalent

        static boolean segmentsEquivalent​(Object segment1,
                                          Object segment2)
        Returns true if the given segments are equivalent.
      • shortDump

        default void shortDump​(StringBuilder sb)
        Description copied from interface: ShortDumpable
        Show the content of the object intended for diagnostics. This method is supposed to append a compact, human-readable output in a single line. Unlike toString() method, there is no requirement to identify the actual class or type of the object. It is assumed that the class/type will be obvious from the context in which the output is used.
        Specified by:
        shortDump in interface ShortDumpable
        Parameters:
        sb - StringBuilder to which to a compact one-line content of the object intended for diagnostics by system administrator should be appended.