Package com.yahoo.document.update

Class FieldUpdate

  • public class FieldUpdate
extends java.lang.Object

    A field update holds a list of value updates that will be applied atomically to a field in a document.

    To create a field update that contains only a single value update, use the static factory methods provided by this class.

    Example:

     FieldUpdate clearFieldUpdate = FieldUpdate.createClearField(field);

    It is also possible to create a field update that holds more than one value update.

    Example:

     FieldUpdate fieldUpdate = FieldUpdate.create(field);
 ValueUpdate incrementValue = ValueUpdate.createIncrement("foo", 130d);
 ValueUpdate addValue = ValueUpdate.createAdd("bar", 100);
 fieldUpdate.addValueUpdate(incrementValue);
 fieldUpdate.addValueUpdate(addValue);

    Note that the addValueUpdate() method returns a reference to itself to support chaining, so the last two lines could be written as one:

     fieldUpdate.addValueUpdate(incrementValue).addValueUpdate(addValue);

    Note also that the second example above is equivalent to:

     FieldUpdate fieldUpdate = FieldUpdate.createIncrement(field, "foo", 130d);
 ValueUpdate addValue = ValueUpdate.createAdd("bar", 100);
 fieldUpdate.addValueUpdate(addValue);

    Note that even though updates take fields as arguments, those fields are not necessarily a field of a document type - any name/value pair which existing in an updatable structure can be addressed by creating the Fields as needed. For example: 

     FieldUpdate field=FieldUpdate.createIncrement(new Field("myattribute",DataType.INT),130);
    Author:
    Einar M R Rosenvinge
    See Also:
    ValueUpdate, DocumentUpdate

    • Field Detail

      • field

        protected Field field

      • valueUpdates

        protected java.util.List<ValueUpdate> valueUpdates

    • Method Detail

      • getField

        public Field getField()
        Returns the field that this field update applies to

      • setField

        public void setField​(Field field)
        Sets the field this update applies to. Note that this does not need to be a field of the document type in question - a field is just the name and type of some value to be updated.

      • applyTo

        public FieldUpdate applyTo​(Document doc)
        Applies this field update.
        Parameters:
        doc - the document to apply the update to
        Returns:
        a reference to itself

      • addValueUpdate

        public FieldUpdate addValueUpdate​(ValueUpdate valueUpdate)
        Adds a value update to the list of value updates.
        Parameters:
        valueUpdate - the ValueUpdate to add
        Returns:
        a reference to itself
        Throws:
        java.lang.IllegalArgumentException - if the data type of the value update is not equal to the data type of this field

      • addValueUpdate

        public FieldUpdate addValueUpdate​(int index,
                                  ValueUpdate valueUpdate)
        Adds a value update to the list of value updates.
        Parameters:
        index - the index where this value update should be added
        valueUpdate - the ValueUpdate to add
        Returns:
        a reference to itself
        Throws:
        java.lang.IllegalArgumentException - if the data type of the value update is not equal to the data type of this field

      • addValueUpdates

        public FieldUpdate addValueUpdates​(java.util.List<ValueUpdate> valueUpdates)
        Adds a list of value updates to the list of value updates.
        Parameters:
        valueUpdates - a list containing the value updates to add
        Returns:
        a reference to itself
        Throws:
        java.lang.IllegalArgumentException - if the data type of the value update is not equal to the data type of this field

      • removeValueUpdate

        public ValueUpdate removeValueUpdate​(int index)
        Removes the value update at the specified position in the list of value updates.
        Parameters:
        index - the index of the ValueUpdate to remove
        Returns:
        the ValueUpdate previously at the specified position
        Throws:
        java.lang.IndexOutOfBoundsException - if index is out of range

      • setValueUpdate

        public ValueUpdate setValueUpdate​(int index,
                                  ValueUpdate update)
        Replaces the value update at the specified position in the list of value updates with the specified value update.
        Parameters:
        index - index of value update to replace
        update - value update to be stored at the specified position
        Returns:
        the value update previously at the specified position
        Throws:
        java.lang.IndexOutOfBoundsException - if index out of range (index < 0 || index >= size())

      • size

        public int size()
        Get the number of value updates in this field update.
        Returns:
        the size of the List of FieldUpdates

      • clearValueUpdates

        public void clearValueUpdates()
        Removes all value updates from the list of value updates.

      • getValueUpdate

        public ValueUpdate getValueUpdate​(int index)
        Get the value update at the specified index in the list of value updates.
        Parameters:
        index - the index of the ValueUpdate to return
        Returns:
        the ValueUpdate at the specified index
        Throws:
        java.lang.IndexOutOfBoundsException - if index is out of range

      • getValueUpdates

        public java.util.List<ValueUpdate> getValueUpdates()
        Get an unmodifiable list of all value updates that this field update specifies.
        Returns:
        a list of all ValueUpdates in this FieldUpdate

      • getValueUpdates

        public java.util.List<ValueUpdate> getValueUpdates​(ValueUpdate.ValueUpdateClassID classID)
        Get value updates with the specified valueUpdateClassID. The caller gets ownership of the returned list, and subsequent modifications to the list does not change the state of this object.
        Parameters:
        classID - the classID of ValueUpdates to return
        Returns:
        a List of ValueUpdates of the specified classID (possibly empty, but not null)

      • hasValueUpdate

        public boolean hasValueUpdate​(ValueUpdate.ValueUpdateClassID classID)
        Returns whether this field update contains (at least) one update of the given type
        Parameters:
        classID - the classID of ValueUpdates to check for
        Returns:
        true if there is at least one value update of the given type in this

      • isEmpty

        public boolean isEmpty()
        Returns whether or not this field update contains any value updates.
        Returns:
        True if this update is empty.

      • addAll

        public void addAll​(FieldUpdate update)
        Adds all the ValueUpdates of the given FieldUpdate to this. If the given FieldUpdate refers to a different Field than this, this method throws an exception.
        Parameters:
        update - The update whose content to add to this.
        Throws:
        java.lang.IllegalArgumentException - If the Field of the given FieldUpdate does not match this.

      • serialize

        public final void serialize​(com.yahoo.io.GrowableByteBuffer buf)

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • create

        public static FieldUpdate create​(Field field)
        Creates a new, empty field update with no encapsulated value updates. Use this method to add an arbitrary set of value updates using the FieldUpdate.addValueUpdate() method.
        Parameters:
        field - the Field to alter
        Returns:
        a new, empty FieldUpdate
        See Also:
        ValueUpdate, addValueUpdate(ValueUpdate)

      • createClearField

        public static FieldUpdate createClearField​(Field field)
        Creates a new field update that clears the field. This operation removes the value/field completely.
        Parameters:
        field - the Field to clear
        Returns:
        a FieldUpdate specifying the clearing
        See Also:
        createClear(Field)

      • createAdd

        public static FieldUpdate createAdd​(Field field,
                                    FieldValue value)
        Creates a new field update, with one encapsulated value update specifying an addition of a value to an array or a key to a weighted set (with default weight 1).
        Parameters:
        field - the Field to add a value to
        value - the value to add to the array, or key to add to the weighted set
        Returns:
        a FieldUpdate specifying the addition
        Throws:
        java.lang.IllegalArgumentException - if the runtime type of newValue does not match the type required by field
        java.lang.UnsupportedOperationException - if the field type is not array or weighted set
        See Also:
        ValueUpdate.createAdd(FieldValue)

      • createAdd

        public static FieldUpdate createAdd​(Field field,
                                    FieldValue key,
                                    java.lang.Integer weight)
        Creates a new field update, with one encapsulated value update specifying an addition of a key (with a specified weight) to a weighted set. If this method is used on an array data type, the weight will be omitted.
        Parameters:
        field - the Field to a add a key to
        key - the key to add
        weight - the weight to associate with the given key
        Returns:
        a FieldUpdate specifying the addition
        Throws:
        java.lang.IllegalArgumentException - if the runtime type of key does not match the type required by field
        java.lang.UnsupportedOperationException - if the field type is not array or weighted set
        See Also:
        ValueUpdate.createAdd(FieldValue,Integer)

      • createAddAll

        public static FieldUpdate createAddAll​(Field field,
                                       java.util.List<? extends FieldValue> values)
        Creates a new field update, with encapsulated value updates, specifying an addition of all values in a given list to an array. If this method is used on a weighted set data type, the default weights will be 1.
        Parameters:
        field - the Field to add an array of values to
        values - a List containing the values to add
        Returns:
        a FieldUpdate specifying the addition
        Throws:
        java.lang.IllegalArgumentException - if the runtime type of values does not match the type required by field
        java.lang.UnsupportedOperationException - if the field type is not array or weighted set
        See Also:
        ValueUpdate.createAddAll(java.util.List), ValueUpdate.createAdd(FieldValue)

      • createAddAll

        public static FieldUpdate createAddAll​(Field field,
                                       WeightedSet<? extends FieldValue> set)
        Creates a new field update, with encapsulated value updates, specifying an addition of all key/weight pairs in a weighted set to a weighted set. If this method is used on an array data type, the weights will be omitted.
        Parameters:
        field - the Field to add the key/weight pairs in a weighted set to
        set - a WeightedSet containing the key/weight pairs to add
        Returns:
        a FieldUpdate specifying the addition
        Throws:
        java.lang.IllegalArgumentException - if the runtime type of values does not match the type required by field
        java.lang.UnsupportedOperationException - if the field type is not weighted set or array
        See Also:
        ValueUpdate.createAdd(FieldValue, Integer), ValueUpdate.createAddAll(com.yahoo.document.datatypes.WeightedSet)

      • createIncrement

        public static FieldUpdate createIncrement​(Field field,
                                          java.lang.Number increment)
        Creates a new field update, with one encapsulated value update that increments a value. Note that the data type must be a numeric type.
        Parameters:
        field - the field to increment the value of
        increment - the number to increment by
        Returns:
        a FieldUpdate specifying the increment
        Throws:
        java.lang.UnsupportedOperationException - if the data type is non-numeric
        See Also:
        ValueUpdate.createIncrement(Number)

      • createIncrement

        public static FieldUpdate createIncrement​(Field field,
                                          FieldValue key,
                                          java.lang.Number increment)
        Creates a new field update, with one encapsulated value update that increments a weight in a weighted set.
        Parameters:
        field - the field to increment one of the weights of
        key - the key whose weight in the weighted set to increment
        increment - the number to increment by
        Returns:
        a FieldUpdate specifying the increment
        Throws:
        java.lang.IllegalArgumentException - if key is not equal to the nested type of the weighted set
        See Also:
        ValueUpdate.createIncrement(Number), ValueUpdate.createMap(FieldValue, ValueUpdate)

      • createDecrement

        public static FieldUpdate createDecrement​(Field field,
                                          java.lang.Number decrement)
        Creates a new field update, with one encapsulated value update that decrements a value. Note that the data type must be a numeric type.
        Parameters:
        field - the field to decrement the value of
        decrement - the number to decrement by
        Returns:
        a FieldUpdate specifying the decrement
        Throws:
        java.lang.UnsupportedOperationException - if the data type is non-numeric
        See Also:
        ValueUpdate.createDecrement(Number)

      • createDecrement

        public static FieldUpdate createDecrement​(Field field,
                                          FieldValue key,
                                          java.lang.Number decrement)
        Creates a new field update, with one encapsulated value update that decrements a weight in a weighted set.
        Parameters:
        field - the field to decrement one of the weights of
        key - the key whose weight in the weighted set to decrement
        decrement - the number to decrement by
        Returns:
        a FieldUpdate specifying the decrement
        Throws:
        java.lang.IllegalArgumentException - if key is not equal to the nested type of the weighted set
        See Also:
        ValueUpdate.createDecrement(Number), ValueUpdate.createMap(FieldValue, ValueUpdate)

      • createMultiply

        public static FieldUpdate createMultiply​(Field field,
                                         java.lang.Number factor)
        Creates a new field update, with one encapsulated value update that multiplies a value. Note that the data type must be a numeric type.
        Parameters:
        field - the field to multiply the value of
        factor - the number to multiply by
        Returns:
        a FieldUpdate specifying the multiplication
        Throws:
        java.lang.UnsupportedOperationException - if the data type is non-numeric
        See Also:
        ValueUpdate.createMultiply(Number)

      • createMultiply

        public static FieldUpdate createMultiply​(Field field,
                                         FieldValue key,
                                         java.lang.Number factor)
        Creates a new field update, with one encapsulated value update that multiplies a weight in a weighted set.
        Parameters:
        field - the field to multiply one of the weights of
        key - the key whose weight in the weighted set to multiply
        factor - the number to multiply by
        Returns:
        a FieldUpdate specifying the multiplication
        Throws:
        java.lang.IllegalArgumentException - if key is not equal to the nested type of the weighted set
        See Also:
        ValueUpdate.createMultiply(Number), ValueUpdate.createMap(FieldValue, ValueUpdate)

      • createDivide

        public static FieldUpdate createDivide​(Field field,
                                       java.lang.Number divisor)
        Creates a new field update, with one encapsulated value update that divides a value. Note that the data type must be a numeric type.
        Parameters:
        field - the field to divide the value of
        divisor - the number to divide by
        Returns:
        a FieldUpdate specifying the division
        Throws:
        java.lang.UnsupportedOperationException - if the data type is non-numeric
        See Also:
        ValueUpdate.createDivide(Number)

      • createDivide

        public static FieldUpdate createDivide​(Field field,
                                       FieldValue key,
                                       java.lang.Number divisor)
        Creates a new field update, with one encapsulated value update that divides a weight in a weighted set.
        Parameters:
        field - the field to divide one of the weights of
        key - the key whose weight in the weighted set to divide
        divisor - the number to divide by
        Returns:
        a FieldUpdate specifying the division
        Throws:
        java.lang.IllegalArgumentException - if key is not equal to the nested type of the weighted set
        See Also:
        ValueUpdate.createDivide(Number), ValueUpdate.createMap(FieldValue, ValueUpdate)

      • createAssign

        public static FieldUpdate createAssign​(Field field,
                                       FieldValue newValue)
        Creates a new field update, with one encapsulated value update, that assigns a new value, completely overwriting the previous value. Note that it is possible to pass newValue=null to this method to remove the value completely.
        Parameters:
        field - the Field to assign a new value to
        newValue - the value to assign
        Returns:
        a FieldUpdate specifying the assignment
        Throws:
        java.lang.IllegalArgumentException - if the runtime type of newValue does not match the type required by field
        See Also:
        ValueUpdate.createAssign(FieldValue)

      • createClear

        public static FieldUpdate createClear​(Field field)
        Creates a new field update, with one encapsulated value update, that clears the value; see documentation for ClearValueUpdate to see behavior for the individual data types. Note that clearing the value is not the same clearing the field; this method leaves an empty value, whereas clearing the field will completely remove the value.
        Parameters:
        field - the field to clear the value of
        Returns:
        a FieldUpdate specifying the clearing
        See Also:
        ClearValueUpdate, ValueUpdate.createClear(), createClearField(com.yahoo.document.Field)

      • createMap

        public static FieldUpdate createMap​(Field field,
                                    FieldValue value,
                                    ValueUpdate update)
        Creates a new field update, with one encapsulated value update, which is able to map an update to a value to a subvalue in an array or a weighted set. If this update is to be applied to an array, the value parameter must be an integer specifying the index in the array that the update parameter is to be applied to, and the update parameter must be compatible with the sub-datatype of the array. If this update is to be applied on a weighted set, the value parameter must be the key in the set that the update parameter is to be applied to, and the update parameter must be compatible with the INT data type.
        Parameters:
        field - the field to modify the subvalue of
        value - the index in case of array, or key in case of weighted set
        update - the update to apply to the target sub-value
        Returns:
        a FieldUpdate specifying the sub-update
        Throws:
        java.lang.IllegalArgumentException - in case data type is an array type and value is not an Integer; in case data type is a weighted set type and value is not equal to the nested type of the weighted set; or the encapsulated update throws such an exception
        java.lang.UnsupportedOperationException - if superType is a single-value type, or anything else than array or weighted set; or the encapsulated update throws such an exception
        See Also:
        ValueUpdate.createMap(FieldValue, ValueUpdate)

      • createRemove

        public static FieldUpdate createRemove​(Field field,
                                       FieldValue value)
        Creates a new field update, with one encapsulated value update, specifying the removal of a value from an array or a key/weight from a weighted set.
        Parameters:
        field - the field to remove a value from
        value - the value to remove from the array, or key to remove from the weighted set
        Returns:
        a FieldUpdate specifying the removal
        Throws:
        java.lang.IllegalArgumentException - if the runtime type of newValue does not match the type required
        java.lang.UnsupportedOperationException - if the field type is not array or weighted set
        See Also:
        ValueUpdate.createRemove(FieldValue)

      • createRemoveAll

        public static FieldUpdate createRemoveAll​(Field field,
                                          java.util.List<? extends FieldValue> values)
        Creates a new field update, with encapsulated value updates, specifying the removal of all values in a given list from an array or weighted set. Note that this method is just a convenience method, it simply iterates through the list and creates value updates by calling createRemove() for each element.
        Parameters:
        field - the field to remove values from
        values - a List containing the values to remove
        Returns:
        a FieldUpdate specifying the removal
        Throws:
        java.lang.IllegalArgumentException - if the runtime type of values does not match the type required by field
        java.lang.UnsupportedOperationException - if the field type is not array or weighted set
        See Also:
        ValueUpdate.createRemoveAll(java.util.List)

      • createRemoveAll

        public static FieldUpdate createRemoveAll​(Field field,
                                          WeightedSet<? extends FieldValue> values)
        Creates a new field update, with encapsulated value updates, specifying the removal of all values in a given list from an array or weighted set. Note that this method is just a convenience method, it simply iterates through the list and creates value updates by calling createRemove() for each element.
        Parameters:
        field - the field to remove values from
        values - a List containing the values to remove
        Returns:
        a FieldUpdate specifying the removal
        Throws:
        java.lang.IllegalArgumentException - if the runtime type of values does not match the type required by field
        java.lang.UnsupportedOperationException - if the field type is not array or weighted set
        See Also:
        ValueUpdate.createRemoveAll(java.util.List)