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 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.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.
-
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 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.
-
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.
-
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).
-
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 interfaceShortDumpable
- Parameters:
sb
- StringBuilder to which to a compact one-line content of the object intended for diagnostics by system administrator should be appended.
-
-