Package com.evolveum.midpoint.prism

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

    • Method Detail

      • 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​(@Nullable
                   D definition)
        Sets applicable item definition.
        Parameters:
        definition - the definition to set TODO consider removing this method

      • 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

        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.

      • 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

      • 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

      • 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

        <X> X[] getRealValuesArray​(Class<X> type)
        Type override, also for compatibility.

      • getRealValues

        @NotNull
@NotNull Collection<?> getRealValues()
        Returns (potentially empty) collection of "real values".

      • 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

        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

        void 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

        void 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

        void 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.

      • clear

        void clear()
        Removes all values from the item.

      • 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.

      • 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.

      • find

        Object find​(ItemPath path)
        Returns object (Item or PrismValue) pointed to by the given path.

      • createDelta

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

      • 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.

      • copy

        default Item<?,​?> copy()

      • clone

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

      • createImmutableClone

        Item<V,​D> createImmutableClone()

      • 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,
                      boolean prohibitRaw)

      • checkConsistence

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

      • checkConsistence

        void checkConsistence()

      • checkConsistenceInternal

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

      • 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.

      • 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.

      • 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()