All Superinterfaces:

Serializable, ShortDumpable

All Known Subinterfaces:

UniformItemPath

All Known Implementing Classes:

ItemName, ItemPathImpl, UniformItemPathImpl
```
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
`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 ItemPath`	`allUpToLastName()`	Returns all segments up to the last named one (excluding).
`default ItemPath`	`append(Object... components)`	Returns a newly created path containing all the segments of this path with added components.
`default QName`	`asSingleName()`	If the path consists of a single name segment (not variable nor special symbol), returns the corresponding value.
`default 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(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 ItemPath`	`create(Object... components)`	Creates the path from given components.
`static ItemPath`	`create(List<?> components)`	Creates the path from given components.
`static ItemPath`	`createReverse(List<?> components)`	Creates the path from given components in reverse direction.
`static ItemPath`	`emptyIfNull(ItemPath path)`	Converts null ItemPath to empty one.
`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)`
`Object`	`first()`	Returns the first segment or null if the path is empty.
`ItemPath`	`firstAsPath()`	Returns the first segment as an ItemPath.
`default 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 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 ItemName`	`firstToName()`	Returns the value of the first segment if it is a name segment; otherwise null.
`default ItemName`	`firstToNameOrNull()`	Returns the value of the first segment if it is a name segment; otherwise null.
`static ItemName`	`firstToNameOrNull(ItemPath itemPath)`
`default QName`	`firstToVariableNameOrNull()`	Returns the value of the first segment if it is a variable name segment; otherwise null.
`Object`	`getSegment(int i)`	Returns the given path segment.
`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`	`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 ("$...").
`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.
`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.
`ItemPath`	`removeIds()`	Returns the path with no Id segments.
`default ItemPath`	`rest()`	Returns the rest of the path (the tail).
`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 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 ItemName`	`toName(Object segment)`	Returns a name corresponding to the name segment, or throw an exception otherwise.
`static QName`	`toNameNullSafe(Object segment)`	Returns a name corresponding to the name segment, or throw an exception otherwise.
`static 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 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 ItemPath create(@NotNull
                       List<?> components)
```
    Creates the path from given components.
    
    See Also:
    
    create(Object...)
  - createReverse
```
@NotNull
static ItemPath createReverse(@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.
  - size
```
int size()
```
    Returns path size i.e. the number of components.
  - append
```
@NotNull
default ItemPath append(Object... components)
```
    Returns a newly created path containing all the segments of this path with added components.
  - getSegments
```
@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
Object getSegment(int i)
```
    Returns the given path segment.
    
    Throws:
    
    IndexOutOfBoundsException - if the index is out of range
  - compareComplex
```
default ItemPath.CompareResult compareComplex(@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).
  - 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 ItemName toName(Object segment)
```
    Returns a name corresponding to the name segment, or throw an exception otherwise.
  - toNameNullSafe
```
@Nullable
static QName toNameNullSafe(@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 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
Object first()
```
    Returns the first segment or null if the path is empty.
  - rest
```
@NotNull
default ItemPath rest()
```
    Returns the rest of the path (the tail).
  - rest
```
@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
Object last()
```
    Returns the last segment (or null if the path is empty).
  - allExceptLast
```
@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 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 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 ItemName firstToName()
```
    Returns the value of the first segment if it is a name segment; otherwise null.
  - firstToNameOrNull
```
@Nullable
default 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 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 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
ItemPath namedSegmentsOnly()
```
    Returns the path containing only the regular named segments.
  - removeIds
```
@NotNull
ItemPath removeIds()
```
    Returns the path with no Id segments.
  - stripVariableSegment
```
@NotNull
default 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

size

append

getSegments

getSegment

compareComplex

equivalent

equivalent

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

firstToNameOrNull

firstToNameOrNull

firstToVariableNameOrNull

firstToId

firstToIdOrNull

firstToIdOrNull

firstName

firstNameOrFail

firstNameIndex

lastName

lastNameIndex

checkNoSpecialSymbols

checkNoSpecialSymbolsExceptParent

containsSpecialSymbols

containsSpecialSymbolsExceptParent

namedSegmentsOnly

removeIds

stripVariableSegment

containsNameExactly