Interface Item<V extends PrismValue,D extends ItemDefinition<?>>
- All Superinterfaces:
DebugDumpable
,Freezable
,Itemable
,ParentVisitable
,PathVisitable
,Revivable
,Serializable
,Visitable
- All Known Subinterfaces:
PrismContainer<C>
,PrismObject<O>
,PrismProperty<T>
,PrismReference
,ShadowAssociationsContainer
,ShadowAttributesContainer
,ShadowSimpleAttribute<T>
,ValueMetadata
- All Known Implementing Classes:
DummyContainerImpl
,DummyItem
,DummyPropertyImpl
,DummyReferenceImpl
,ItemImpl
,PrismContainerImpl
,PrismObjectImpl
,PrismPropertyImpl
,PrismReferenceImpl
,ShadowAssociation
,ShadowAssociationsContainerImpl
,ShadowAttributesContainerImpl
,ShadowReferenceAttribute
,ShadowSimpleAttributeImpl
,ValueMetadataAdapter
This is supposed to be a superclass for all items. Items are things that can appear in containers, which generally means only a property, reference and container itself. Therefore this is in fact superclass for those three definitions.
- Author:
- Radovan Semancik
-
Field Summary
Fields inherited from interface com.evolveum.midpoint.util.DebugDumpable
INDENT_STRING
-
Method Summary
Modifier and TypeMethodDescriptionvoid
acceptParentVisitor
(@NotNull Visitor visitor) Accepts a visitor that visits each item/value on the way to the structure root.default boolean
Adds a given value, overwriting existing one.boolean
add
(V newValue, @NotNull EquivalenceStrategy strategy) Adds a value, overwriting existing one(s).default boolean
addAll
(Collection<V> newValues) Adds given values, with the same semantics as repeated add(..) calls.boolean
addAll
(Collection<V> newValues, @NotNull EquivalenceStrategy strategy) Adds given values, with the same semantics as repeated add(..) calls.addIgnoringEquivalents
(V newValue) Adds a value, not looking for equivalent values.addRespectingMetadataAndCloning
(V value, @NotNull EquivalenceStrategy strategy, EquivalenceStrategy metadataEquivalenceStrategy) Adds a value, respecting the metadata.default void
applyDefinition
(D definition) void
applyDefinition
(D definition, boolean force) Applies the definition to this item (and all its values, down to the lowest level).default void
applyDefinitionIfMissing
(D definition) void
void
assertDefinitions
(boolean tolerateRawValues, Supplier<String> sourceDescriptionSupplier) void
assertDefinitions
(Supplier<String> sourceDescriptionSupplier) void
void
checkConsistence
(boolean requireDefinitions, boolean prohibitRaw) void
checkConsistence
(boolean requireDefinitions, boolean prohibitRaw, ConsistencyCheckScope scope) void
checkConsistence
(boolean requireDefinitions, ConsistencyCheckScope scope) void
void
checkConsistenceInternal
(Itemable rootItem, boolean requireDefinitions, boolean prohibitRaw, ConsistencyCheckScope scope) void
clear()
Removes all values from the item.clone()
Literal clone.static <T extends Item<?,
?>>
Collection<T>cloneCollection
(Collection<T> items) cloneComplex
(CloneStrategy strategy) Complex clone with different cloning strategies.default boolean
default boolean
contains
(V value, @NotNull EquivalenceStrategy strategy) copy()
Creates specific subclass of ItemDelta appropriate for type of item that this definition represents (e.g.createDelta
(ItemPath path) Computes a difference (delta) with the specified item using DEFAULT_FOR_DELTA_APPLICATION (REAL_VALUE_CONSIDER_DIFFERENT_IDS) equivalence strategy.diff
(Item<V, D> other, @NotNull ParameterizedEquivalenceStrategy strategy) Computes a difference (delta) with the specified item using given equivalence strategy.boolean
Compares this item to the specified object under DEFAULT_FOR_EQUALS (DATA) strategy.boolean
equals
(Object obj, @NotNull EquivalenceStrategy equivalenceStrategy) Compares this item to the specified object under given strategy.boolean
equals
(Object obj, @NotNull ParameterizedEquivalenceStrategy equivalenceStrategy) Compares this item to the specified object under given strategy.default void
filterValues
(Function<V, Boolean> function) default void
filterYields
(BiFunction<V, PrismContainerValue, Boolean> function) Returns object (Item or PrismValue) pointed to by the given path.<IV extends PrismValue,
ID extends ItemDefinition<?>>
PartiallyResolvedItem<IV,ID> findPartial
(ItemPath path) default V
findValue
(V value, @NotNull EquivalenceStrategy strategy) default V
findValue
(V value, @NotNull Comparator<V> comparator) @NotNull Collection<Item<?,
?>> getAllItems
(@NotNull ItemPath path) Returns all items corresponding to the provided path.static @NotNull Collection<PrismValue>
getAllValues
(Item<?, ?> item, ItemPath path) @NotNull Collection<PrismValue>
getAllValues
(ItemPath path) Returns all values corresponding to the provided path.default V
Returns any of the values.default V
getAnyValue
(@NotNull ValueSelector<V> selector) Returns a value matching given selector (or null if none exists).default Collection<V>
Returns applicable definition.default String
Returns a display name for the item.Returns the name of the item.default String
getHelp()
Returns help message defined for the item.default @Nullable PrismNamespaceContext
Returns the namespace context for this item if available.@Nullable PrismContainerValue<?>
Returns the parent of this item (if exists).@NotNull ItemPath
getPath()
Returns the path of this item (sequence of names from the "root" container or similar object to this item).@Nullable Object
Returns the "real value" (content) of this item: - value contained in PrismPropertyValue - Referencable in PrismReferenceValue - Containerable in PrismContainerValue - Objectable in PrismObjectValue Note that the real value can contain operational items.<X> X
getRealValue
(Class<X> type) Type override, also for compatibility.@NotNull Collection<?>
Returns (potentially empty) collection of "real values".default <X> @NotNull Collection<X>
getRealValues
(Class<X> type) Returns detached collection of real values, although the values are still _connected_ to the original item (in case of complex properties, references, and containers).<X> X[]
getRealValuesArray
(Class<X> type) Type override, also for compatibility.default @NotNull Collection<Object>
Returns the "user data", a map that allows attaching arbitrary named data to this item.<T> T
getUserData
(String key) Returns the user data for the given key (name).getValue()
Returns the value, if there is only one.Returns the values for this item.static <V extends PrismValue>
@NotNull Collection<V>default boolean
default boolean
Returns true if this item and all contained items have definitions.int
hashCode()
Computes hash code to be used under DEFAULT_FOR_EQUALS (currently DATA) equivalence strategy.int
hashCode
(@NotNull EquivalenceStrategy equivalenceStrategy) Computes hash code to be used under given equivalence strategy.int
hashCode
(@NotNull ParameterizedEquivalenceStrategy equivalenceStrategy) Computes hash code to be used under given equivalence strategy.default boolean
static boolean
hasNoValues
(Item<?, ?> item) default boolean
hasRaw()
Returns true is at least one of the values is raw.default boolean
isEmpty()
Normally the same ashasNoValues()
.boolean
Flag that indicates incomplete item.default boolean
Returns true if this item is metadata item that should be ignored for metadata-insensitive comparisons and hashCode functions.default boolean
isRaw()
Returns true is all the values are raw.default boolean
Returns true if the item contains 0 or 1 values and (by definition) is not multivalued.default boolean
void
Merge all the values of other item to this item.void
Currently doing nothing.void
Re-apply PolyString (and possible other) normalizations to the object.default boolean
Removes values equivalent to given value from the item.boolean
remove
(V value, @NotNull EquivalenceStrategy strategy) Removes values equivalent to given value from the item; under specified equivalence strategy OR when values represent the same value via "representsSameValue(.., lax=false)" method.boolean
removeAll
(Collection<V> values, @NotNull EquivalenceStrategy strategy) Removes all given values from the item.default void
removeRespectingMetadata
(V value, @NotNull EquivalenceStrategy strategy, EquivalenceStrategy metadataEquivalenceStrategy) Removes values equivalent to given value from the item; under specified equivalence strategy OR when values represent the same value via "representsSameValue(.., lax=false)" method.void
Replaces all values of the item by given value.void
replaceAll
(Collection<V> newValues, @NotNull EquivalenceStrategy strategy) Replaces all values of the item by given values.static <T extends Item<?,
?>>
Collection<T>resetParentCollection
(Collection<T> items) Sets all parents to null.void
setDefinition
(D definition) Sets applicable item definition.void
setElementName
(QName elementName) Sets the name of the item.void
setIncomplete
(boolean incomplete) Flags the item as incomplete.void
setParent
(@Nullable PrismContainerValue<?> parentValue) Sets the parent of this item.void
setUserData
(String key, Object value) Sets the user data for the given key (name).default int
size()
Returns the number of values for this item.Methods inherited from interface com.evolveum.midpoint.util.DebugDumpable
debugDump, debugDump, debugDumpLazily, debugDumpLazily
Methods inherited from interface com.evolveum.midpoint.prism.Freezable
checkImmutable, checkMutable, freeze, isImmutable
Methods inherited from interface com.evolveum.midpoint.prism.PathVisitable
accept
-
Field Details
-
KEY_NAMESPACE_CONTEXT
-
-
Method Details
-
getDefinition
D getDefinition()Returns applicable definition.May return null if no definition is applicable or the definition is not known.
- Specified by:
getDefinition
in interfaceItemable
- Returns:
- applicable definition
-
hasCompleteDefinition
default boolean hasCompleteDefinition()Returns true if this item and all contained items have definitions. -
getElementName
ItemName getElementName()Returns the name of the item.The name is a QName. It uniquely defines an item.
The name may be null, but such an item will not work.
The name is the QName of XML element in the XML representation.
- Specified by:
getElementName
in interfaceItemable
- Returns:
- item name TODO consider making element name obligatory
-
setElementName
Sets the name of the item.The name is a QName. It uniquely defines an item.
The name may be null, but such an item will not work.
The name is the QName of XML element in the XML representation.
- Parameters:
elementName
- the name to set TODO consider removing this method
-
setDefinition
Sets applicable item definition.- Parameters:
definition
- the definition to set
-
getDisplayName
Returns a display name for the item.Returns null if the display name cannot be determined.
The display name is fetched from the definition. If no definition (schema) is available, the display name will not be returned.
- Returns:
- display name for the item
-
getHelp
Returns help message defined for the item.Returns null if the help message cannot be determined.
The help message is fetched from the definition. If no definition (schema) is available, the help message will not be returned.
- Returns:
- help message for the item
-
isIncomplete
boolean isIncomplete()Flag that indicates incomplete item. If set to true then the values in this item are not complete. If this flag is true then it can be assumed that the object that this item represents has at least one value. This is a method how to indicate that the item really has some values, but are not here. This may be used for variety of purposes. It may indicate that the account has a password, but the password value is not revealed. This may indicate that a user has a photo, but the photo was not requested and therefore is not returned. This may be used to indicate that only part of the attribute values were returned from the search. And so on. -
setIncomplete
void setIncomplete(boolean incomplete) Flags the item as incomplete.- Parameters:
incomplete
- The new value- See Also:
-
getParent
Returns the parent of this item (if exists). Currently this has to be a PrismContainerValue.- Returns:
- The parent if exists
-
setParent
Sets the parent of this item.- Parameters:
parentValue
- The new parent
-
getPath
Returns the path of this item (sequence of names from the "root" container or similar object to this item). Note that if the containing object is a delta (usually a container delta), then the path -
getNamespaceContext
Returns the namespace context for this item if available. Namespace context is currently stored in user data with key Namespace context is stored only ifPrismParser.preserveNamespaceContext()
is flag was used during parsing- Returns:
- The namespace context for this item if available.
- See Also:
-
getUserData
Returns the "user data", a map that allows attaching arbitrary named data to this item.- Returns:
- the user data map
-
getUserData
Returns the user data for the given key (name). -
setUserData
Sets the user data for the given key (name). -
getValues
Returns the values for this item. Although the ordering of this values is not important, and each value should be present at most once, we currently return them as a list instead of a set. TODO reconsider this FIXME we should return immutable list, to avoid manipulating the values directly FIXME and maybe we should return List<? extends V> to avoid specializing the values, see ShadowAssociationValue in midPoint -
valuesStream
-
size
default int size()Returns the number of values for this item. -
getAnyValue
Returns any of the values. Usually called when we are quite confident that there is only a single value; or we don't care which of the values we get. Does not create values if there are none. -
getValue
V getValue()Returns the value, if there is only one. Throws exception if there are more values. If there is no value, this method either: - returns null (for properties) - throws an exception (for items that can hold multiple values) - creates an empty value (for containers and references). TODO think again whether getOrCreateValue would not be better -
getAnyValue
Returns a value matching given selector (or null if none exists). -
getRealValue
Returns the "real value" (content) of this item: - value contained in PrismPropertyValue - Referencable in PrismReferenceValue - Containerable in PrismContainerValue - Objectable in PrismObjectValue Note that the real value can contain operational items. It can also contain container IDs (although they are not considered to be part of the real value). It does not contain information about item element name nor other metadata like origin, definition, etc. (Although e.g. Containerable can be converted back into PrismContainerValue that can be used to retrieve this information.) -
getRealValue
Type override, also for compatibility. -
getRealValuesArray
Type override, also for compatibility. -
getRealValues
Returns (potentially empty) collection of "real values". The list itself is detached, freely modifiable. (Note that the values can still embed a parent, e.g., for containers and references.)- See Also:
-
getRealValues
Returns detached collection of real values, although the values are still _connected_ to the original item (in case of complex properties, references, and containers). BEWARE, it's not always possible to get the real values. -
getRealValuesOrRawTypes
@OneUseOnly("Delta serialization") @Experimental @NotNull default @NotNull Collection<Object> getRealValuesOrRawTypes() -
isSingleValue
default boolean isSingleValue()Returns true if the item contains 0 or 1 values and (by definition) is not multivalued. -
isSingleValueByDefinition
default boolean isSingleValueByDefinition() -
add
Adds a given value, overwriting existing one. It compares values using DEFAULT_FOR_EQUALS (DATA) strategy, so it e.g. takes value metadata differences into account. It is because this method is used during parsing, internal computations (typically using generated beans), and similar situations where we expect little sophistication when it comes to value comparison. The less surprises the better.- Throws:
SchemaException
-
add
@OneUseOnly("convenience") boolean add(@NotNull V newValue, @NotNull @NotNull EquivalenceStrategy strategy) throws SchemaException Adds a value, overwriting existing one(s). Uses specified equivalence strategy.- Returns:
- true if this item changed as a result of the call. This is either during real value addition or during overwriting existing value with a different one. The "difference" is taken using the DEFAULT_FOR_EQUALS (DATA) equivalence strategy.
- Throws:
SchemaException
-
addIgnoringEquivalents
Adds a value, not looking for equivalent values. (This means that the new value is always added, if possible.) Note that we check the cardinality of the item according to its definition, i.e. we do not allow single-valued item to contain more than one value.- Throws:
SchemaException
-
addAll
Adds given values, with the same semantics as repeated add(..) calls.- Returns:
- true if this item changed as a result of the call (i.e. if at least one value was really added)
- Throws:
SchemaException
-
addAll
boolean addAll(Collection<V> newValues, @NotNull @NotNull EquivalenceStrategy strategy) throws SchemaException Adds given values, with the same semantics as repeated add(..) calls. For equality testing uses given strategy.- Returns:
- true if this item changed as a result of the call (i.e. if at least one value was really added)
- Throws:
SchemaException
-
remove
Removes values equivalent to given value from the item. Note we use REAL_VALUE_CONSIDER_DIFFERENT_IDS strategy that ignores value metadata and operational data. This may or may not be good! TODO reconsider -
remove
Removes values equivalent to given value from the item; under specified equivalence strategy OR when values represent the same value via "representsSameValue(.., lax=false)" method.- Returns:
- true if this item changed as a result of the call (i.e. if at least one value was really removed)
-
removeIf
-
addRespectingMetadataAndCloning
ItemModifyResult<V> addRespectingMetadataAndCloning(V value, @NotNull @NotNull EquivalenceStrategy strategy, EquivalenceStrategy metadataEquivalenceStrategy) throws SchemaException Adds a value, respecting the metadata. I.e. if equivalent value exists, the metadata are merged. (Replacing metadata of colliding provenance, adding all the others.) If a value is to be added as a whole, it is cloned.- Throws:
SchemaException
-
removeRespectingMetadata
ItemModifyResult<V> removeRespectingMetadata(V value, @NotNull @NotNull EquivalenceStrategy strategy, EquivalenceStrategy metadataEquivalenceStrategy) Removes values equivalent to given value from the item; under specified equivalence strategy OR when values represent the same value via "representsSameValue(.., lax=false)" method. Respects metadata, i.e. if value to be removed has metadata specified, this method removes only particular metadata. Only if this means that all metadata are gone, then the value is deleted.- Returns:
- null if value was removed, otherwise value which was modified.
-
removeAll
Removes all given values from the item. It is basically a shortcut for repeatedremove(PrismValue, EquivalenceStrategy)
call.- Returns:
- true if this item changed as a result of the call (i.e. if at least one value was really removed)
-
clear
void clear()Removes all values from the item. -
replaceAll
void replaceAll(Collection<V> newValues, @NotNull @NotNull EquivalenceStrategy strategy) throws SchemaException Replaces all values of the item by given values.- Throws:
SchemaException
-
replace
Replaces all values of the item by given value.- Throws:
SchemaException
-
equals
Compares this item to the specified object under DEFAULT_FOR_EQUALS (DATA) strategy. -
equals
Compares this item to the specified object under given strategy. -
equals
Compares this item to the specified object under given strategy. -
hashCode
int hashCode()Computes hash code to be used under DEFAULT_FOR_EQUALS (currently DATA) equivalence strategy. -
hashCode
Computes hash code to be used under given equivalence strategy. -
hashCode
Computes hash code to be used under given equivalence strategy. -
contains
- Returns:
- true if the item contains a given value (by default using DEFAULT_FOR_EQUALS i.e. DATA strategy) Note that the "sameness" (ID-only value matching) is NOT considered here.
-
contains
- Returns:
- true if the item contains a given value under specified equivalence strategy Note that the "sameness" (ID-only value matching) is NOT considered here.
-
findValue
- Returns:
- a value of this item that is equivalent to the given one under given equivalence strategy (or null if no such value exists)
-
findValue
- Returns:
- a value of this item that is equivalent to the given one under given comparator (or null if no such value exists)
-
diff
Computes a difference (delta) with the specified item using DEFAULT_FOR_DELTA_APPLICATION (REAL_VALUE_CONSIDER_DIFFERENT_IDS) equivalence strategy. Compares item values only -- does NOT dive into lower levels. -
diff
Computes a difference (delta) with the specified item using given equivalence strategy. Note this method cannot accept general EquivalenceStrategy here; it needs the parameterized strategy. Compares item values only -- does NOT dive into lower levels. -
getClonedValues
-
normalize
void normalize()Currently doing nothing. -
merge
Merge all the values of other item to this item.- Throws:
SchemaException
-
find
Returns object (Item or PrismValue) pointed to by the given path. -
findPartial
<IV extends PrismValue,ID extends ItemDefinition<?>> PartiallyResolvedItem<IV,ID> findPartial(ItemPath path) -
createDelta
Creates specific subclass of ItemDelta appropriate for type of item that this definition represents (e.g. PropertyDelta, ContainerDelta, ...) -
createDelta
-
acceptParentVisitor
Accepts a visitor that visits each item/value on the way to the structure root.- Specified by:
acceptParentVisitor
in interfaceParentVisitable
-
recomputeAllValues
void recomputeAllValues()Re-apply PolyString (and possible other) normalizations to the object. -
filterValues
-
filterYields
-
applyDefinition
- Throws:
SchemaException
-
applyDefinitionIfMissing
- Throws:
SchemaException
-
applyDefinition
Applies the definition to this item (and all its values, down to the lowest level). It may even convert the values, e.g. from their raw (unparsed) form to the parsed one, or - for resource attributes - betweenString
andPolyString
values (due to the normalization).- Throws:
SchemaException
-
copy
-
clone
Literal clone. -
createImmutableClone
-
cloneComplex
Complex clone with different cloning strategies.- See Also:
-
cloneCollection
-
resetParentCollection
Sets all parents to null. This is good if the items are to be "transplanted" into a different Containerable. -
checkConsistence
-
checkConsistence
void checkConsistence(boolean requireDefinitions, boolean prohibitRaw) -
checkConsistence
-
checkConsistence
void checkConsistence() -
checkConsistence
-
checkConsistenceInternal
void checkConsistenceInternal(Itemable rootItem, boolean requireDefinitions, boolean prohibitRaw, ConsistencyCheckScope scope) -
assertDefinitions
- Throws:
SchemaException
-
assertDefinitions
- Throws:
SchemaException
-
assertDefinitions
void assertDefinitions(boolean tolerateRawValues, Supplier<String> sourceDescriptionSupplier) throws SchemaException - Throws:
SchemaException
-
isRaw
default boolean isRaw()Returns true is all the values are raw. -
hasRaw
default boolean hasRaw()Returns true is at least one of the values is raw. -
isEmpty
default boolean isEmpty()Normally the same ashasNoValues()
. But a container is considered empty also if all its values (PCVs) are empty. This is a bit strange and should be revisited. -
hasNoValues
default boolean hasNoValues() -
hasAnyValue
default boolean hasAnyValue() -
hasNoValues
-
isOperational
default boolean isOperational()Returns true if this item is metadata item that should be ignored for metadata-insensitive comparisons and hashCode functions. -
getValues
-
getAllValues
Returns all values corresponding to the provided path. The path may contain ambiguous segments (e.g. `assignment/targetRef` when there are more assignments). Limitations: . The path can contain only name segments and the "identifier" (`#`) segment - at least for now. No ID segments. . There are no guarantees about duplicate values. They may or may not be present in the returned collections. . The caller should not modify the returned collection in any way. Note to implementors: Please take care about the performance of this method. -
getAllValues
-
getAllItems
Returns all items corresponding to the provided path. This is an analogue togetAllValues(ItemPath)
. The only difference here is that `#` segment is not allowed, as it does not correspond to an item. (Shouldn't these methods be rather called findAllValues/findAllItems?) -
getHighestId
Long getHighestId()
-