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 class ItemPath.CompareResult

Field Summary

Fields
Modifier and Type Field Description

static ItemPath EMPTY_PATH

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
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.
`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.
`@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.
`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.
`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.
`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.
`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 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
  - 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.
  - 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.
  - 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.

Interface ItemPath

Nested Class Summary

Field Summary

Method Summary

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

Field Detail

EMPTY_PATH

Method Detail

create

create

createReverse

isEmpty

isEmpty

isNotEmpty

size

append

getSegments

getSegment

compareComplex

equivalent

equivalent

equals

equals

isSubPath

isSubPathOrEquivalent

isSuperPath

isSuperPathOrEquivalent

startsWith

isName

toName

toNameNullSafe

toNameOrNull

isId

isNullId

toId

toIdOrNull

isSpecial

isParent

isObjectReference

isIdentifier

isVariable

toVariableName

first

rest

rest

firstAsPath

remainder

last

allExceptLast

allUpToIncluding

allUpToLastName

subPath

startsWithName

startsWithId

startsWithNullId

startsWithIdentifier

startsWithVariable

startsWithObjectReference

startsWithParent

asSingleName

asSingleNameOrFail

isSingleName

firstToName

firstToQName

firstToNameOrNull

firstToNameOrNull

firstToVariableNameOrNull

firstToId

firstToIdOrNull

firstToIdOrNull

firstName

firstNameOrFail

firstNameIndex

lastName

lastNameIndex

checkNoSpecialSymbols

checkNoSpecialSymbolsExceptParent

containsSpecialSymbols

containsSpecialSymbolsExceptParent

namedSegmentsOnly