Package com.evolveum.midpoint.prism.path

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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    ItemPath.CompareResult
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final ItemPath
    EMPTY_PATH
     
    static final ItemPath
    SELF_PATH
    Self path is just an empty path, but gives it better interpretation in some contexts.

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull ItemPath
    allExceptLast()
    Returns all segments except the last one.
    default ItemPath
    allUpToIncluding(int i)
    Returns all segments up to the specified one (including it).
    default @NotNull ItemPath
    allUpToLastName()
    Returns all segments up to the last named one (excluding).
    default @NotNull ItemPath
    append(Object... components)
    Returns a newly created path containing all the segments of this path with added components.
    default ItemName
    asSingleName()
    If the path consists of a single name segment (not variable nor special symbol), returns the corresponding value.
    default @NotNull ItemName
    asSingleNameOrFail()
    If the path consists of a single name segment (not variable nor special symbol), returns the corresponding value.
    static void
    checkNoSpecialSymbols(ItemPath path)
     
    static void
    checkNoSpecialSymbolsExceptParent(ItemPath path)
     
    default ItemPath.CompareResult
    compareComplex(@Nullable ItemPath otherPath)
    Compares two item paths.
    default boolean
    containsNameExactly(QName name)
    Returns true if the path contains the specified name (requires exact match).
    default boolean
    containsSpecialSymbols()
     
    default boolean
    containsSpecialSymbolsExceptParent()
     
    static @NotNull ItemPath
    create(@NotNull List<?> components)
    Creates the path from given components.
    static @NotNull ItemPath
    create(Object... components)
    Creates the path from given components.
    static @NotNull ItemPath
    createReverse(@NotNull List<?> components)
    Creates the path from given components in reverse direction.
    static ItemPath
    emptyIfNull(ItemPath path)
    Converts null ItemPath to empty one.
    static boolean
    equals(@Nullable ItemPath itemPath, @Nullable Object other, boolean exact)
    Utility method performing equals(Object, boolean) on two nullable objects.
    default boolean
    equals(Object other, boolean exact)
    Compares with the other object either literally (exact = true) or via .equivalent (exact = false).
    default boolean
    equivalent(ItemPath path)
    Checks if the paths are equivalent.
    static boolean
    equivalent(ItemPath path1, ItemPath path2)
     
    @Nullable Object
    first()
    Returns the first segment or null if the path is empty.
    ItemPath
    firstAsPath()
    Returns the first segment as an ItemPath.
    default @Nullable ItemName
    firstName()
    Returns the value of the first name segment or null if there's no name segment.
    default int
    firstNameIndex()
    Returns the first name segment index; or -1 if there's no such segment.
    default @NotNull ItemName
    firstNameOrFail()
    The same as firstName but throws an exception if there's no name.
    default Long
    firstToId()
    Returns the value of the first segment if it is a Id segment; otherwise throws an exception.
    default Long
    firstToIdOrNull()
    Returns the value of the first segment if it is a Id segment; otherwise null.
    static Long
    firstToIdOrNull(ItemPath path)
     
    default @NotNull ItemName
    firstToName()
    Returns the value of the first segment if it is a name segment or throws an exception otherwise.
    default @Nullable ItemName
    firstToNameOrNull()
    Returns the value of the first segment if it is a name segment; otherwise null.
    static ItemName
    firstToNameOrNull(ItemPath itemPath)
     
    default @NotNull QName
    firstToQName()
    Returns the value of the first segment if it is a name segment or throws.
    default QName
    firstToVariableNameOrNull()
    Returns the value of the first segment if it is a variable name segment; otherwise null.
    static ItemPath
    fromString(@NotNull String value)
    PrismContext must be already initialized in order to call this method.
    @Nullable Object
    getSegment(int i)
    Returns the given path segment.
    @NotNull List<?>
    getSegments()
    Returns the path segments.
    boolean
    isEmpty()
    Returns true if the path is empty i.e. has no components.
    static boolean
    isEmpty(ItemPath path)
    Returns true if the path is null or empty.
    static boolean
    isId(Object o)
    Returns true if the segment is the container Id.
    static boolean
    isIdentifier(Object segment)
    Returns true if the segment is the Identifier one ("#").
    static boolean
    isName(Object segment)
    Returns true if the segment is a name segment.
    static boolean
    isNotEmpty(ItemPath path)
     
    static boolean
    isNullId(Object o)
    Returns true if the segment is the container Id with value of NULL.
    static boolean
    isObjectReference(Object segment)
    Returns true if the segment is the Object Reference one ("@").
    static boolean
    isParent(Object segment)
    Returns true if the segment is the Parent one ("..").
    default boolean
    isSingleName()
    Returns true if the path consists of a single name segment.
    static boolean
    isSpecial(Object segment)
    Returns true if the segment is a special one: parent, reference, identifier, variable.
    default boolean
    isSubPath(ItemPath otherPath)
    Checks if current path is a strict subpath (prefix) of the other path.
    default boolean
    isSubPathOrEquivalent(ItemPath otherPath)
    Check if current path is a subpath (prefix) of the other path or they are equivalent.
    default boolean
    isSuperPath(ItemPath otherPath)
    Check if the other path is a strict subpath (prefix) of this path.
    default boolean
    isSuperPathOrEquivalent(ItemPath path)
    Check if the other path is a subpath (prefix) of this path or they are equivalent.
    static boolean
    isVariable(Object segment)
    Returns true if the segment is the Variable one ("$...").
    @Nullable Object
    last()
    Returns the last segment (or null if the path is empty).
    ItemName
    lastName()
    Returns the last name segment value; or null if there's no name segment.
    default int
    lastNameIndex()
    Returns the last name segment index; or -1 if there's no such segment.
    @NotNull ItemPath
    namedSegmentsOnly()
    Returns the path containing only the regular named segments.
    default ItemPath
    remainder(ItemPath path)
    Returns the remainder of "this" path after passing all segments from the other path.
    @NotNull ItemPath
    removeIds()
    Returns the path with no Id segments.
    default @NotNull ItemPath
    rest()
    Returns the rest of the path (the tail).
    @NotNull ItemPath
    rest(int n)
    Returns the rest of the path (the tail), starting at position "n".
    static boolean
    segmentsEquivalent(Object segment1, Object segment2)
    Returns true if the given segments are equivalent.
    default void
    shortDump(StringBuilder sb)
    Show the content of the object intended for diagnostics.
    int
    size()
    Returns path size i.e. the number of components.
    default boolean
    startsWith(ItemPath prefix)
    Convenience method with understandable semantics.
    default boolean
    startsWithId()
    Returns true if the path starts with with value Id.
    default boolean
    startsWithIdentifier()
    Returns true if the path starts with an identifier (#).
    default boolean
    startsWithName()
    Returns true if the path starts with the standard segment name (i.e.
    default boolean
    startsWithName(QName name)
    Returns true if the path starts with the specified name (approximate match).
    default boolean
    startsWithNullId()
    Returns true if the path starts with the value Id of null.
    default boolean
    startsWithObjectReference()
    Returns true if the path starts with an object reference (@).
    default boolean
    startsWithParent()
    Returns true if the path starts with a parent segment (..).
    default boolean
    startsWithVariable()
    Returns true if the path starts with variable name ($...).
    default @NotNull ItemPath
    stripVariableSegment()
    Removes the leading variable segment, if present.
    ItemPath
    subPath(int from, int to)
    Returns a sub-path from (including) to (excluding) given indices.
    default ItemPathType
    toBean()
     
    static Long
    toId(Object segment)
    Returns a Long value corresponding to the container Id segment, or throw an exception otherwise.
    static Long
    toIdOrNull(Object segment)
    Returns a Long value corresponding to the container Id segment, or return null otherwise.
    static @NotNull ItemName
    toName(Object segment)
    Returns a name corresponding to the name segment, or throw an exception otherwise.
    static @Nullable QName
    toNameNullSafe(@Nullable Object segment)
    Returns a name corresponding to the name segment, or throw an exception otherwise.
    static @Nullable ItemName
    toNameOrNull(Object segment)
    Returns a name corresponding to the name segment, or null if it's no name.
    default String
    toStringStandalone()
    Returns the standalone representation of this path, i.e. the one with all the namespaces explicitly declared.
    static QName
    toVariableName(Object segment)
    Returns a name corresponding to the Variable segment, or throw an exception otherwise.

    Methods inherited from interface com.evolveum.midpoint.util.ShortDumpable

    shortDump, shortDumpLazily

  • Field Details

    • EMPTY_PATH

      static final ItemPath EMPTY_PATH

    • SELF_PATH

      static final ItemPath SELF_PATH
      Self path is just an empty path, but gives it better interpretation in some contexts.

  • Method Details

    • 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:

    • 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

    • fromString

      static ItemPath fromString(@NotNull @NotNull String value)
      PrismContext must be already initialized in order to call this method.

    • 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

    • toBean

      default ItemPathType toBean()

    • compareComplex

      default ItemPath.CompareResult compareComplex(@Nullable @Nullable ItemPath otherPath)
      Compares two item paths.

    • 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.

    • equivalent

      static boolean equivalent(ItemPath path1, ItemPath path2)

    • equals

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

    • equals

      static boolean equals(@Nullable @Nullable ItemPath itemPath, @Nullable @Nullable Object other, boolean exact)
      Utility method performing equals(Object, boolean) on two nullable objects.

    • 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 ItemName 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 or throws an exception otherwise.

    • firstToQName

      @NotNull default @NotNull QName firstToQName()
      Returns the value of the first segment if it is a name segment or throws. parent, id, name, variable

    • firstToNameOrNull

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

    • firstToNameOrNull

      static ItemName firstToNameOrNull(ItemPath itemPath)

    • 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.

    • toStringStandalone

      default String toStringStandalone()
      Returns the standalone representation of this path, i.e. the one with all the namespaces explicitly declared.

    • 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.