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 proper definition.

      • 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

      • size

        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

        boolean isSingleValue()
        Returns true if the item contains 0 or 1 values and (by definition) is not multivalued.

      • add

        boolean add​(@NotNull
            V newValue,
            boolean checkUniqueness)
     throws SchemaException
        Adds a given value, unless an equivalent one is already there (if checkUniqueness is true).
        Returns:
        true if this item changed as a result of the call (i.e. if the value was really added) Note that even if checkUniqueness is false 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

      • add

        default boolean add​(@NotNull
                    V newValue)
             throws SchemaException
        Adds a given value, unless an equivalent one is already there. It is the same as calling add with checkUniqueness=true.
        Returns:
        true if this item changed as a result of the call (i.e. if the value was really added)
        Throws:
        SchemaException

      • add

        boolean add​(@NotNull
            V newValue,
            @NotNull
            @NotNull EquivalenceStrategy equivalenceStrategy)
     throws SchemaException
        Adds a given value, unless an equivalent one is already there. It is the same as calling add with checkUniqueness=true. Uses given strategy for equivalence testing.
        Returns:
        true if this item changed as a result of the call (i.e. if the value was really added)
        Throws:
        SchemaException

      • addAll

        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,
               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

      • addAll

        boolean addAll​(Collection<V> newValues,
               boolean checkUniqueness,
               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

        boolean remove​(V value)
        Removes given value from the item. "Given value" currently means any value that is considered equivalent via REAL_VALUE equivalence strategy or a value that is considered "the same" 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) Note that there can be more than one values removed.

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

      • removeAll

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

      • equals

        boolean equals​(Object obj)
        Compares this item to the specified object under NOT_LITERAL strategy (if no other is pre-set).
        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 NOT_LITERAL 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

        boolean contains​(V value)
        Returns:
        true if the item contains a given value (by default using NOT_LITERAL strategy) Note that the "sameness" (ID-only value matching) is NOT considered here.

      • contains

        boolean contains​(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.

      • contains

        boolean contains​(V value,
                 @Nullable
                 @Nullable EquivalenceStrategy strategy,
                 @Nullable
                 @Nullable Comparator<V> comparator)
        Returns:
        true if the item contains a given value using comparator (if not null) or under specified equivalence strategy (if comparator is null). Note that the "sameness" (ID-only value matching) is NOT considered here.

      • containsEquivalentValue

        boolean containsEquivalentValue​(V value,
                                @Nullable
                                @Nullable Comparator<V> comparator)
        Returns:
        true if the item contains an equivalent value Item value is considered to be equivalent to the given value if: 1) given value is ID-only container value and item value has the same ID, or 2) comparator is not null and it gives "equals" (0) result when comparing these values, or 3) comparator is null and values match under IGNORE_METADATA_CONSIDER_DIFFERENT_IDS strategy

      • findValue

        V findValue​(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)

      • valuesEqual

        boolean valuesEqual​(Collection<V> matchValues,
                    @Nullable
                    @Nullable Comparator<V> comparator)
        Returns:
        true if the values of this item match the "matchValues" collection, under given comparator. If comparator is null the default equals(..) comparison is used.

      • diff

        default ItemDelta<V,​D> diff​(Item<V,​D> other)
        Computes a difference (delta) with the specified item using IGNORE_METADATA_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.

      • normalize

        void normalize()

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

      • clone

        Item clone()
        Literal clone.

      • createImmutableClone

        Item 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

        boolean isRaw()
        Returns true is all the values are raw.

      • hasRaw

        boolean hasRaw()
        Returns true is at least one of the values is raw.

      • isEmpty

        default boolean isEmpty()

      • hasNoValues

        default boolean hasNoValues()

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

      • setPrismContext

        void setPrismContext​(PrismContext prismContext)

      • getHighestId

        Long getHighestId()