Package com.evolveum.midpoint.prism

Interface Item<V extends PrismValue,D extends ItemDefinition<?>>

All Superinterfaces:
Cloneable, DebugDumpable, Freezable, Itemable, ParentVisitable, PathVisitable, PrismVisitable, 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
public interface Item<V extends PrismValue,D extends ItemDefinition<?>> extends Itemable, DebugDumpable, Visitable, PrismVisitable, PathVisitable, ParentVisitable, Serializable, Revivable, Freezable, Cloneable
Item is a common abstraction of Property, Reference and Container.

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 Details

    • KEY_NAMESPACE_CONTEXT

      static final String 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 interface Itemable
      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 interface Itemable
      Returns:
      item name TODO consider making element name obligatory

    • setElementName

      void setElementName(QName elementName)
      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

      void setDefinition(@NotNull D definition)
      Sets applicable item definition.
      Parameters:
      definition - the definition to set

    • getDisplayName

      default String 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

      @Unused default String 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. *Behavior*: For single-valued items, the `incomplete` flag is cleared when a known value is set up (via delta or Java API). See also https://docs.evolveum.com/midpoint/devel/design/incomplete-items-4.9.1/.

    • setIncomplete

      void setIncomplete(boolean incomplete)
      Flags the item as incomplete. FIXME: Should be package-visible to implementation
      Parameters:
      incomplete - The new value
      See Also:

    • getParent

      @Nullable @Nullable PrismContainerValue<?> getParent()
      Returns the parent of this item (if exists). Currently this has to be a PrismContainerValue.
      Returns:
      The parent if exists

    • setParent

      void setParent(@Nullable @Nullable PrismContainerValue<?> parentValue)
      Sets the parent of this item.
      Parameters:
      parentValue - The new parent

    • getPath

      @NotNull @NotNull ItemPath 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
      Specified by:
      getPath in interface Itemable
      Returns:
      the path

    • getNamespaceContext

      @Nullable default @Nullable PrismNamespaceContext 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 if PrismParser.preserveNamespaceContext() is flag was used during parsing
      Returns:
      The namespace context for this item if available.
      See Also:

    • getUserData

      @NotNull @NotNull Map<String,Object> getUserData()
      Returns the "user data", a map that allows attaching arbitrary named data to this item.
      Returns:
      the user data map

    • getUserData

      <T> T getUserData(String key)
      Returns the user data for the given key (name).

    • setUserData

      void setUserData(String key, Object value)
      Sets the user data for the given key (name).

    • getValues

      @NotNull @NotNull List<V> 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

      default Stream<V> valuesStream()

    • size

      default int size()
      Returns the number of values for this item.

    • getAnyValue

      default V 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

      default V getAnyValue(@NotNull @NotNull ValueSelector<V> selector)
      Returns a value matching given selector (or null if none exists).

    • getRealValue

      @Nullable @Nullable Object 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

      <X> X getRealValue(Class<X> type)
      Type override, also for compatibility.

    • getRealValuesArray

      @OneUseOnly("connectorConfiguration") <X> X[] getRealValuesArray(Class<X> type)
      Type override, also for compatibility.

    • getRealValues

      @NotNull @NotNull Collection<?> 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

      @NotNull 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). 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

      default boolean add(@NotNull V newValue) throws SchemaException
      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

      ItemModifyResult<V> addIgnoringEquivalents(@NotNull V newValue) throws SchemaException
      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

      default boolean addAll(Collection<V> newValues) throws SchemaException
      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

      default boolean remove(V value)
      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

      boolean remove(V value, @NotNull @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.
      Returns:
      true if this item changed as a result of the call (i.e. if at least one value was really removed)

    • removeIf

      default void removeIf(Predicate<V> predicate)

    • 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

      boolean removeAll(Collection<V> values, @NotNull @NotNull EquivalenceStrategy strategy)
      Removes all given values from the item. It is basically a shortcut for repeated remove(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

      void replace(V newValue) throws SchemaException
      Replaces all values of the item by given value.
      Throws:
      SchemaException

    • equals

      boolean equals(Object obj)
      Compares this item to the specified object under DEFAULT_FOR_EQUALS (DATA) strategy.
      Overrides:
      equals in class Object

    • equals

      boolean equals(Object obj, @NotNull @NotNull EquivalenceStrategy equivalenceStrategy)
      Compares this item to the specified object under given strategy.

    • equals

      boolean equals(Object obj, @NotNull @NotNull ParameterizedEquivalenceStrategy equivalenceStrategy)
      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.
      Overrides:
      hashCode in class Object

    • hashCode

      int hashCode(@NotNull @NotNull EquivalenceStrategy equivalenceStrategy)
      Computes hash code to be used under given equivalence strategy.

    • hashCode

      int hashCode(@NotNull @NotNull ParameterizedEquivalenceStrategy equivalenceStrategy)
      Computes hash code to be used under given equivalence strategy.

    • contains

      default boolean contains(@NotNull V value)
      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

      default boolean contains(@NotNull V value, @NotNull @NotNull EquivalenceStrategy strategy)
      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

      default V findValue(@NotNull V value, @NotNull @NotNull EquivalenceStrategy strategy)
      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

      default V findValue(V value, @NotNull @NotNull Comparator<V> comparator)
      Returns:
      a value of this item that is equivalent to the given one under given comparator (or null if no such value exists)

    • diff

      default ItemDelta<V,D> diff(Item<V,D> other)
      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

      ItemDelta<V,D> diff(Item<V,D> other, @NotNull @NotNull ParameterizedEquivalenceStrategy strategy)
      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

      default Collection<V> getClonedValues()

    • normalize

      void normalize()
      Currently doing nothing.

    • merge

      void merge(Item<V,D> otherItem) throws SchemaException
      Merge all the values of other item to this item.
      Throws:
      SchemaException

    • find

      Object find(ItemPath path)
      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

      ItemDelta<V,D> createDelta()
      Creates specific subclass of ItemDelta appropriate for type of item that this definition represents (e.g. PropertyDelta, ContainerDelta, ...)

    • createDelta

      ItemDelta<V,D> createDelta(ItemPath path)

    • acceptParentVisitor

      void acceptParentVisitor(@NotNull @NotNull Visitor visitor)
      Accepts a visitor that visits each item/value on the way to the structure root.
      Specified by:
      acceptParentVisitor in interface ParentVisitable

    • recomputeAllValues

      void recomputeAllValues()
      Re-apply PolyString (and possible other) normalizations to the object.

    • filterValues

      default void filterValues(Function<V,Boolean> function)

    • filterYields

      default void filterYields(BiFunction<V,PrismContainerValue,Boolean> function)

    • applyDefinition

      default void applyDefinition(@NotNull D definition) throws SchemaException
      Throws:
      SchemaException

    • applyDefinitionIfMissing

      default void applyDefinitionIfMissing(@NotNull D definition) throws SchemaException
      Throws:
      SchemaException

    • applyDefinition

      void applyDefinition(@NotNull D definition, boolean force) throws SchemaException
      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 - between String and PolyString values (due to the normalization).
      Throws:
      SchemaException

    • copy

      default Item<V,D> copy()

    • clone

      Item<V,D> clone()
      Literal clone.

    • createImmutableClone

      Item<V,D> createImmutableClone()

    • cloneComplex

      Item<V,D> cloneComplex(CloneStrategy strategy)
      Complex clone with different cloning strategies.
      See Also:

    • cloneCollection

      static <T extends Item<?, ?>> Collection<T> cloneCollection(Collection<T> items)

    • resetParentCollection

      static <T extends Item<?, ?>> Collection<T> resetParentCollection(Collection<T> items)
      Sets all parents to null. This is good if the items are to be "transplanted" into a different Containerable.

    • checkConsistence

      void checkConsistence(boolean requireDefinitions, ConsistencyCheckScope scope)

    • checkConsistence

      void checkConsistence(boolean requireDefinitions, boolean prohibitRaw)

    • checkConsistence

      void checkConsistence(boolean requireDefinitions, boolean prohibitRaw, ConsistencyCheckScope scope)

    • checkConsistence

      void checkConsistence()

    • checkConsistence

      void checkConsistence(ConsistencyCheckScope scope)

    • checkConsistenceInternal

      void checkConsistenceInternal(Itemable rootItem, boolean requireDefinitions, boolean prohibitRaw, ConsistencyCheckScope scope)

    • assertDefinitions

      void assertDefinitions() throws SchemaException
      Throws:
      SchemaException

    • assertDefinitions

      void assertDefinitions(Supplier<String> sourceDescriptionSupplier) throws SchemaException
      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 as hasNoValues(). 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

      static boolean hasNoValues(Item<?,?> item)

    • isOperational

      default boolean isOperational()
      Returns true if this item is metadata item that should be ignored for metadata-insensitive comparisons and hashCode functions.

    • getValues

      @NotNull static <V extends PrismValue> @NotNull Collection<V> getValues(Item<V,?> item)

    • getAllValues

      @NotNull @NotNull Collection<PrismValue> getAllValues(ItemPath path)
      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

      @NotNull static @NotNull Collection<PrismValue> getAllValues(Item<?,?> item, ItemPath path)
      See getAllValues(ItemPath).

    • getAllItems

      @NotNull @NotNull Collection<Item<?,?>> getAllItems(@NotNull @NotNull ItemPath path)
      Returns all items corresponding to the provided path. This is an analogue to getAllValues(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()

    • acceptVisitor

      default boolean acceptVisitor(PrismVisitor visitor)
      Description copied from interface: PrismVisitable
      Accept visitor and visits prism item or value and it's children Note: name is not accept, but accept visitor to prevent naming conflict in lambdas dynamic languages such as groovy with Visitable.accept(com.evolveum.midpoint.prism.Visitor)
      Specified by:
      acceptVisitor in interface PrismVisitable
      Returns:
      return value of PrismVisitor.visit(PrismVisitable) invocation for this visitable.