Package com.yahoo.document.update

Class FieldUpdate

java.lang.Object
com.yahoo.document.update.FieldUpdate
public class FieldUpdate extends 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:

  • Field Details

  • Constructor Details

  • Method Details

    • getDocumentType

      public DocumentType getDocumentType()

    • 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:
      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:
      IllegalArgumentException - if the data type of the value update is not equal to the data type of this field

    • addValueUpdates

      public FieldUpdate addValueUpdates(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:
      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:
      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:
      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:
      IndexOutOfBoundsException - if index is out of range

    • getValueUpdates

      public 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 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:
      IllegalArgumentException - If the Field of the given FieldUpdate does not match this.

    • serialize

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

    • serialize

      public void serialize(DocumentUpdateWriter data)

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class 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:

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

    • 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:
      IllegalArgumentException - if the runtime type of newValue does not match the type required by field
      UnsupportedOperationException - if the field type is not array or weighted set
      See Also:

    • createAdd

      public static FieldUpdate createAdd(Field field, FieldValue key, 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:
      IllegalArgumentException - if the runtime type of key does not match the type required by field
      UnsupportedOperationException - if the field type is not array or weighted set
      See Also:

    • createAddAll

      public static FieldUpdate createAddAll(Field field, 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:
      IllegalArgumentException - if the runtime type of values does not match the type required by field
      UnsupportedOperationException - if the field type is not array or weighted set
      See Also:

    • 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:
      IllegalArgumentException - if the runtime type of values does not match the type required by field
      UnsupportedOperationException - if the field type is not weighted set or array
      See Also:

    • createIncrement

      public static FieldUpdate createIncrement(Field field, 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:
      UnsupportedOperationException - if the data type is non-numeric
      See Also:

    • createIncrement

      public static FieldUpdate createIncrement(Field field, FieldValue key, 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:
      IllegalArgumentException - if key is not equal to the nested type of the weighted set
      See Also:

    • createDecrement

      public static FieldUpdate createDecrement(Field field, 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:
      UnsupportedOperationException - if the data type is non-numeric
      See Also:

    • createDecrement

      public static FieldUpdate createDecrement(Field field, FieldValue key, 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:
      IllegalArgumentException - if key is not equal to the nested type of the weighted set
      See Also:

    • createMultiply

      public static FieldUpdate createMultiply(Field field, 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:
      UnsupportedOperationException - if the data type is non-numeric
      See Also:

    • createMultiply

      public static FieldUpdate createMultiply(Field field, FieldValue key, 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:
      IllegalArgumentException - if key is not equal to the nested type of the weighted set
      See Also:

    • createDivide

      public static FieldUpdate createDivide(Field field, 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:
      UnsupportedOperationException - if the data type is non-numeric
      See Also:

    • createDivide

      public static FieldUpdate createDivide(Field field, FieldValue key, 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:
      IllegalArgumentException - if key is not equal to the nested type of the weighted set
      See Also:

    • 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:
      IllegalArgumentException - if the runtime type of newValue does not match the type required by field
      See Also:

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

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

    • 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:
      IllegalArgumentException - if the runtime type of newValue does not match the type required
      UnsupportedOperationException - if the field type is not array or weighted set
      See Also:

    • createRemoveAll

      public static FieldUpdate createRemoveAll(Field field, 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:
      IllegalArgumentException - if the runtime type of values does not match the type required by field
      UnsupportedOperationException - if the field type is not array or weighted set
      See Also:

    • 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:
      IllegalArgumentException - if the runtime type of values does not match the type required by field
      UnsupportedOperationException - if the field type is not array or weighted set
      See Also: