Package org.apache.accumulo.core.data

Class Mutation

  • All Implemented Interfaces:
    org.apache.hadoop.io.Writable
    Direct Known Subclasses:
    ConditionalMutation, LocalityGroupUtil.PartitionedMutation
    public class Mutation
extends Object
implements org.apache.hadoop.io.Writable
    Mutation represents an action that manipulates a row in a table. A mutation holds a list of column/value pairs that represent an atomic set of modifications to make to a row.

    Convenience methods which takes columns and value as CharSequence (String implements CharSequence) are provided. CharSequence is converted to UTF-8 by constructing a new Text object.

    When always passing in the same data as a CharSequence/String, it's probably more efficient to call the Text put methods. This way the data is only encoded once and only one Text object is created.

    All of the put methods append data to the mutation; they do not overwrite anything that was previously put. The mutation holds a list of all columns/values that were put into it.

    The putDelete() methods do not remove something that was previously added to the mutation; rather, they indicate that Accumulo should insert a delete marker for that row column. A delete marker effectively hides entries for that row column with a timestamp earlier than the marker's. (The hidden data is eventually removed during Accumulo garbage collection.)

    This class has many overloaded put and putDelete methods. These were added to support different subset of fields and types. The functionality of all of these put methods and more is provided by the new fluent at() method added in 2.0.

    • Constructor Detail

      • Mutation

        public Mutation​(byte[] row)
        Creates a new mutation. A defensive copy is made.
        Parameters:
        row - row ID
        Since:
        1.5.0

      • Mutation

        public Mutation​(byte[] row,
                int initialBufferSize)
        Creates a new mutation. A defensive copy is made.
        Parameters:
        row - row ID
        initialBufferSize - the initial size, in bytes, of the internal buffer for serializing
        Since:
        1.7.0

      • Mutation

        public Mutation​(byte[] row,
                int start,
                int length)
        Creates a new mutation. A defensive copy is made.
        Parameters:
        row - byte array containing row ID
        start - starting index of row ID in byte array
        length - length of row ID in byte array
        Throws:
        IndexOutOfBoundsException - if start or length is invalid
        Since:
        1.5.0

      • Mutation

        public Mutation​(byte[] row,
                int start,
                int length,
                int initialBufferSize)
        Creates a new mutation. A defensive copy is made.
        Parameters:
        row - byte array containing row ID
        start - starting index of row ID in byte array
        length - length of row ID in byte array
        initialBufferSize - the initial size, in bytes, of the internal buffer for serializing
        Throws:
        IndexOutOfBoundsException - if start or length is invalid
        Since:
        1.7.0

      • Mutation

        public Mutation​(org.apache.hadoop.io.Text row)
        Creates a new mutation. A defensive copy is made.
        Parameters:
        row - row ID

      • Mutation

        public Mutation​(org.apache.hadoop.io.Text row,
                int initialBufferSize)
        Creates a new mutation. A defensive copy is made.
        Parameters:
        row - row ID
        initialBufferSize - the initial size, in bytes, of the internal buffer for serializing
        Since:
        1.7.0

      • Mutation

        public Mutation​(CharSequence row)
        Creates a new mutation.
        Parameters:
        row - row ID

      • Mutation

        public Mutation​(CharSequence row,
                int initialBufferSize)
        Creates a new mutation.
        Parameters:
        row - row ID
        initialBufferSize - the initial size, in bytes, of the internal buffer for serializing
        Since:
        1.7.0

      • Mutation

        public Mutation()
        Creates a new mutation.

      • Mutation

        public Mutation​(TMutation tmutation)
        Creates a new mutation from a Thrift mutation.
        Parameters:
        tmutation - Thrift mutation

      • Mutation

        public Mutation​(Mutation m)
        Creates a new mutation by copying another.
        Parameters:
        m - mutation to copy

    • Method Detail

      • getRow

        public byte[] getRow()
        Gets the row ID for this mutation. Not a defensive copy.
        Returns:
        row ID

      • put

        public void put​(org.apache.hadoop.io.Text columnFamily,
                org.apache.hadoop.io.Text columnQualifier,
                Value value)
        Puts a modification in this mutation. Column visibility is empty; timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        value - cell value
        See Also:
        at()

      • put

        public void put​(org.apache.hadoop.io.Text columnFamily,
                org.apache.hadoop.io.Text columnQualifier,
                ColumnVisibility columnVisibility,
                Value value)
        Puts a modification in this mutation. Timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        value - cell value
        See Also:
        at()

      • put

        public void put​(org.apache.hadoop.io.Text columnFamily,
                org.apache.hadoop.io.Text columnQualifier,
                long timestamp,
                Value value)
        Puts a modification in this mutation. Column visibility is empty. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        timestamp - timestamp
        value - cell value
        See Also:
        at()

      • put

        public void put​(org.apache.hadoop.io.Text columnFamily,
                org.apache.hadoop.io.Text columnQualifier,
                ColumnVisibility columnVisibility,
                long timestamp,
                Value value)
        Puts a modification in this mutation. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        timestamp - timestamp
        value - cell value
        See Also:
        at()

      • putDelete

        public void putDelete​(org.apache.hadoop.io.Text columnFamily,
                      org.apache.hadoop.io.Text columnQualifier)
        Puts a deletion in this mutation. Matches empty column visibility; timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        See Also:
        at()

      • putDelete

        public void putDelete​(org.apache.hadoop.io.Text columnFamily,
                      org.apache.hadoop.io.Text columnQualifier,
                      ColumnVisibility columnVisibility)
        Puts a deletion in this mutation. Timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        See Also:
        at()

      • putDelete

        public void putDelete​(org.apache.hadoop.io.Text columnFamily,
                      org.apache.hadoop.io.Text columnQualifier,
                      long timestamp)
        Puts a deletion in this mutation. Matches empty column visibility. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        timestamp - timestamp
        See Also:
        at()

      • putDelete

        public void putDelete​(org.apache.hadoop.io.Text columnFamily,
                      org.apache.hadoop.io.Text columnQualifier,
                      ColumnVisibility columnVisibility,
                      long timestamp)
        Puts a deletion in this mutation. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        timestamp - timestamp
        See Also:
        at()

      • put

        public void put​(CharSequence columnFamily,
                CharSequence columnQualifier,
                Value value)
        Puts a modification in this mutation. Column visibility is empty; timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        See Also:
        at()

      • put

        public void put​(CharSequence columnFamily,
                CharSequence columnQualifier,
                ColumnVisibility columnVisibility,
                Value value)
        Puts a modification in this mutation. Timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        value - cell value
        See Also:
        at()

      • put

        public void put​(CharSequence columnFamily,
                CharSequence columnQualifier,
                long timestamp,
                Value value)
        Puts a modification in this mutation. Column visibility is empty. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        timestamp - timestamp
        value - cell value
        See Also:
        at()

      • put

        public void put​(CharSequence columnFamily,
                CharSequence columnQualifier,
                ColumnVisibility columnVisibility,
                long timestamp,
                Value value)
        Puts a modification in this mutation. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        timestamp - timestamp
        value - cell value
        See Also:
        at()

      • putDelete

        public void putDelete​(CharSequence columnFamily,
                      CharSequence columnQualifier)
        Puts a deletion in this mutation. Matches empty column visibility; timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        See Also:
        at()

      • putDelete

        public void putDelete​(CharSequence columnFamily,
                      CharSequence columnQualifier,
                      ColumnVisibility columnVisibility)
        Puts a deletion in this mutation. Timestamp is not set. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        See Also:
        at()

      • putDelete

        public void putDelete​(CharSequence columnFamily,
                      CharSequence columnQualifier,
                      long timestamp)
        Puts a deletion in this mutation. Matches empty column visibility. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        timestamp - timestamp
        See Also:
        at()

      • putDelete

        public void putDelete​(CharSequence columnFamily,
                      CharSequence columnQualifier,
                      ColumnVisibility columnVisibility,
                      long timestamp)
        Puts a deletion in this mutation. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        timestamp - timestamp
        See Also:
        at()

      • put

        public void put​(CharSequence columnFamily,
                CharSequence columnQualifier,
                CharSequence value)
        Puts a modification in this mutation. Column visibility is empty; timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        value - cell value
        See Also:
        at()

      • put

        public void put​(CharSequence columnFamily,
                CharSequence columnQualifier,
                ColumnVisibility columnVisibility,
                CharSequence value)
        Puts a modification in this mutation. Timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        value - cell value
        See Also:
        at()

      • put

        public void put​(CharSequence columnFamily,
                CharSequence columnQualifier,
                long timestamp,
                CharSequence value)
        Puts a modification in this mutation. Column visibility is empty. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        timestamp - timestamp
        value - cell value
        See Also:
        at()

      • put

        public void put​(CharSequence columnFamily,
                CharSequence columnQualifier,
                ColumnVisibility columnVisibility,
                long timestamp,
                CharSequence value)
        Puts a modification in this mutation. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        timestamp - timestamp
        value - cell value
        See Also:
        at()

      • put

        public void put​(byte[] columnFamily,
                byte[] columnQualifier,
                byte[] value)
        Puts a modification in this mutation. Column visibility is empty; timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        value - cell value
        Since:
        1.5.0
        See Also:
        at()

      • put

        public void put​(byte[] columnFamily,
                byte[] columnQualifier,
                ColumnVisibility columnVisibility,
                byte[] value)
        Puts a modification in this mutation. Timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        value - cell value
        Since:
        1.5.0
        See Also:
        at()

      • put

        public void put​(byte[] columnFamily,
                byte[] columnQualifier,
                long timestamp,
                byte[] value)
        Puts a modification in this mutation. Column visibility is empty. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        timestamp - timestamp
        value - cell value
        Since:
        1.5.0
        See Also:
        at()

      • put

        public void put​(byte[] columnFamily,
                byte[] columnQualifier,
                ColumnVisibility columnVisibility,
                long timestamp,
                byte[] value)
        Puts a modification in this mutation. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        timestamp - timestamp
        value - cell value
        Since:
        1.5.0
        See Also:
        at()

      • putDelete

        public void putDelete​(byte[] columnFamily,
                      byte[] columnQualifier)
        Puts a deletion in this mutation. Matches empty column visibility; timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        Since:
        1.5.0
        See Also:
        at()

      • putDelete

        public void putDelete​(byte[] columnFamily,
                      byte[] columnQualifier,
                      ColumnVisibility columnVisibility)
        Puts a deletion in this mutation. Timestamp is not set. All parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        Since:
        1.5.0
        See Also:
        at()

      • putDelete

        public void putDelete​(byte[] columnFamily,
                      byte[] columnQualifier,
                      long timestamp)
        Puts a deletion in this mutation. Matches empty column visibility. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        timestamp - timestamp
        Since:
        1.5.0
        See Also:
        at()

      • putDelete

        public void putDelete​(byte[] columnFamily,
                      byte[] columnQualifier,
                      ColumnVisibility columnVisibility,
                      long timestamp)
        Puts a deletion in this mutation. All appropriate parameters are defensively copied.
        Parameters:
        columnFamily - column family
        columnQualifier - column qualifier
        columnVisibility - column visibility
        timestamp - timestamp
        Since:
        1.5.0
        See Also:
        at()

      • at

        public Mutation.FamilyOptions at()
        Fluent API for putting or deleting to a Mutation that makes it easy use different types (i.e byte[], CharSequence, etc) when specifying the family, qualifier, value, etc.

        Methods are optional but must follow this order: family, qualifier, visibility, timestamp.

        The put and delete methods end the chain and add the modification to the Mutation.

        The following is an example if using at() to put and delete. Notice how the example mixes String and byte[]. 

         
   Mutation m = new Mutation("row0017");
   m.at().family("001").qualifier(new byte[] {0,1}).put("v99");
   m.at().family("002").qualifier(new byte[] {0,1}).delete();
        Returns:
        a new FamilyOptions object, starting the method chain
        Since:
        2.0.0

      • getUpdates

        public List<ColumnUpdate> getUpdates()
        Gets the modifications and deletions in this mutation. After calling this method, further modifications to this mutation are ignored. Changes made to the returned updates do not affect this mutation.
        Returns:
        list of modifications and deletions

      • newColumnUpdate

        protected ColumnUpdate newColumnUpdate​(byte[] cf,
                                       byte[] cq,
                                       byte[] cv,
                                       boolean hasts,
                                       long ts,
                                       boolean deleted,
                                       byte[] val)

      • numBytes

        public long numBytes()
        Gets the total number of bytes in this mutation.
        Returns:
        length of mutation in bytes

      • estimatedMemoryUsed

        public long estimatedMemoryUsed()
        Gets an estimate of the amount of memory used by this mutation. The estimate includes data sizes and object overhead.
        Returns:
        memory usage estimate

      • size

        public int size()
        Gets the number of modifications / deletions in this mutation.
        Returns:
        the number of modifications / deletions

      • addReplicationSource

        public void addReplicationSource​(String peer)
        Add a new element to the set of peers which this Mutation originated from
        Parameters:
        peer - the peer to add
        Since:
        1.7.0

      • setReplicationSources

        public void setReplicationSources​(Set<String> sources)
        Set the replication peers which this Mutation originated from
        Parameters:
        sources - Set of peer names which have processed this update
        Since:
        1.7.0

      • getReplicationSources

        public Set<String> getReplicationSources()
        Return the replication sources for this Mutation
        Returns:
        An unmodifiable view of the replication sources

      • readFields

        public void readFields​(DataInput in)
                throws IOException
        Specified by:
        readFields in interface org.apache.hadoop.io.Writable
        Throws:
        IOException

      • droppingOldTimestamp

        protected void droppingOldTimestamp​(long ts)

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • equals

        public boolean equals​(Mutation m)
        Checks if this mutation equals another. Two mutations are equal if they target the same row and have the same modifications and deletions, in order. This method may be removed in a future API revision in favor of equals(Object). See ACCUMULO-1627 for more information.
        Parameters:
        m - mutation to compare
        Returns:
        true if this mutation equals the other, false otherwise

      • toThrift

        public TMutation toThrift()
        Creates a TMutation object containing this Mutation's data. Note that this method will move the Mutation into a "serialized" state that will prevent users from adding more data via Mutation#put().
        Returns:
        a thrift form of this Mutation

      • getSerializedFormat

        protected Mutation.SERIALIZED_FORMAT getSerializedFormat()
        Gets the serialization format used to (de)serialize this mutation.
        Returns:
        serialization format