ColumnPrefixDistributedRowLock (astyanax-recipes 2.0.2 API)

java.lang.Object
- com.netflix.astyanax.recipes.locks.ColumnPrefixDistributedRowLock<K>

Type Parameters:
K -

All Implemented Interfaces:

DistributedRowLock
```
public class ColumnPrefixDistributedRowLock<K>
extends java.lang.Object
implements DistributedRowLock
```
Takes a distributed row lock for a single row. The row lock is accomplished using a sequence of read/write events to Cassandra without the need for something like zookeeper. Algorithm 1. Write a column with name _. Value is an expiration time. 2. Read back all columns with case 1) count==1 Got the lock case 2) count> 1 No lock 3. Do something in your code assuming the row is locked 4. Release the lock by deleting the lock columns Usage considerations 1. Set an expiration time (expireLockAfter) that is long enough for your processing to complete 2. Use this when the probability for contension is very low 3. Optimize by reading all columns (withIncludeAllColumn(true)) and merge the mutation into the release. This will save 2 calls to cassandra. 4. If the client fails after Step 1. A subsequent attempt to lock will automatically release these stale locks. You can turn this auto cleanup off by calling failOnStaleLock(false), handling a StaleLockException and doing manual cleanup by calling releaseExpiredLocks() 5. An optional TTL can be set on the lock columns which will ensure abandoned/stale locks will be cleaned up by compactions at some point. 6. You can customize the 'prefix' used for the lock columns. This will help with storing the lock columns with data in the same row. 7. You can customize the unique part of the lock column to include meaningful data such as the UUID row key from another column family. This can have the same effect as assigning a foreign key to the lock column and is useful for uniqueness constraint. 8. This recipe is not a transaction. Take a lock, ColumnPrefixDistributedRowLock lock = new ColumnPrefixDistributedRowLock(keyspace, columnFamily, "KeyBeingLocked"); try { lock.acquire(); } finally { lock.release(); } Read, Modify, Write. The read, modify, write piggybacks on top of the lock calls. ColumnPrefixDistributedRowLock lock = new ColumnPrefixDistributedRowLock(keyspace, columnFamily, "KeyBeingLocked"); MutationBatch m = keyspace.prepareMutationBatch(); try { ColumnMap columns = lock.acquireLockAndReadRow(); m.withRow("KeyBeingLocked") .putColumn("SomeColumnBeingUpdated", ); lock.releaseWithMutation(m); } catch (Exception e) { lock.release(); }

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`DEFAULT_LOCK_PREFIX`
`static java.util.concurrent.TimeUnit`	`DEFAULT_OPERATION_TIMEOUT_UNITS`
`static int`	`LOCK_TIMEOUT`

Constructor Summary

Constructors
Constructor and Description
`ColumnPrefixDistributedRowLock(com.netflix.astyanax.Keyspace keyspace, com.netflix.astyanax.model.ColumnFamily<K,java.lang.String> columnFamily, K key)`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`acquire()` Try to take the lock.
`com.netflix.astyanax.model.ColumnMap<java.lang.String>`	`acquireLockAndReadRow()` Take the lock and return the row data columns.
`ColumnPrefixDistributedRowLock<K>`	`expireLockAfter(long timeout, java.util.concurrent.TimeUnit unit)` Time for failed locks.
`ColumnPrefixDistributedRowLock<K>`	`failOnStaleLock(boolean failOnStaleLock)` When set to true the operation will fail if a stale lock is detected
`java.lang.String`	`fillLockMutation(com.netflix.astyanax.MutationBatch m, java.lang.Long time, java.lang.Integer ttl)` Fill a mutation with the lock column.
`void`	`fillReleaseMutation(com.netflix.astyanax.MutationBatch m, boolean excludeCurrentLock)` Fill a mutation that will release the locks.
`com.netflix.astyanax.model.ConsistencyLevel`	`getConsistencyLevel()`
`com.netflix.astyanax.model.ColumnMap<java.lang.String>`	`getDataColumns()`
`K`	`getKey()`
`com.netflix.astyanax.Keyspace`	`getKeyspace()`
`java.lang.String`	`getLockColumn()`
`java.lang.String`	`getLockId()`
`java.lang.String`	`getPrefix()`
`int`	`getRetryCount()`
`java.util.Map<java.lang.String,java.lang.Long>`	`readLockColumns()` Return a mapping of existing lock columns and their expiration times
`long`	`readTimeoutValue(com.netflix.astyanax.model.Column<?> column)` Read the expiration time from the column value
`void`	`release()` Release the lock by releasing this and any other stale lock columns
`java.util.Map<java.lang.String,java.lang.Long>`	`releaseAllLocks()` Release all locks.
`java.util.Map<java.lang.String,java.lang.Long>`	`releaseExpiredLocks()` Release all expired locks for this key.
`java.util.Map<java.lang.String,java.lang.Long>`	`releaseLocks(boolean force)` Delete locks columns.
`void`	`releaseWithMutation(com.netflix.astyanax.MutationBatch m)` Release using the provided mutation.
`boolean`	`releaseWithMutation(com.netflix.astyanax.MutationBatch m, boolean force)`
`void`	`verifyLock(long curTimeInMicros)` Verify that the lock was acquired.
`ColumnPrefixDistributedRowLock<K>`	`withBackoff(com.netflix.astyanax.retry.RetryPolicy policy)`
`ColumnPrefixDistributedRowLock<K>`	`withColumnPrefix(java.lang.String prefix)` Specify the prefix that uniquely distinguishes the lock columns from data column
`ColumnPrefixDistributedRowLock<K>`	`withConsistencyLevel(com.netflix.astyanax.model.ConsistencyLevel consistencyLevel)` Modify the consistency level being used.
`ColumnPrefixDistributedRowLock<K>`	`withDataColumns(boolean flag)` If true the first read will also fetch all the columns in the row as opposed to just the lock columns.
`ColumnPrefixDistributedRowLock<K>`	`withLockId(java.lang.String lockId)` Override the autogenerated lock column.
`ColumnPrefixDistributedRowLock<K>`	`withTtl(java.lang.Integer ttl)` This is the TTL on the lock column being written, as opposed to expireLockAfter which is written as the lock column value.
`ColumnPrefixDistributedRowLock<K>`	`withTtl(java.lang.Integer ttl, java.util.concurrent.TimeUnit units)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - LOCK_TIMEOUT
```
public static final int LOCK_TIMEOUT
```
    See Also:
    Constant Field Values
  - DEFAULT_OPERATION_TIMEOUT_UNITS
```
public static final java.util.concurrent.TimeUnit DEFAULT_OPERATION_TIMEOUT_UNITS
```
  - DEFAULT_LOCK_PREFIX
```
public static final java.lang.String DEFAULT_LOCK_PREFIX
```
    See Also:
    Constant Field Values
- Constructor Detail
  - ColumnPrefixDistributedRowLock
```
public ColumnPrefixDistributedRowLock(com.netflix.astyanax.Keyspace keyspace,
                              com.netflix.astyanax.model.ColumnFamily<K,java.lang.String> columnFamily,
                              K key)
```
- Method Detail
  - withConsistencyLevel
```
public ColumnPrefixDistributedRowLock<K> withConsistencyLevel(com.netflix.astyanax.model.ConsistencyLevel consistencyLevel)
```
    Modify the consistency level being used. Consistency should always be a variant of quorum. The default is CL_QUORUM, which is OK for single region. For multi region the consistency level should be CL_LOCAL_QUORUM. CL_EACH_QUORUM can be used but will Incur substantial latency.
    
    Parameters:
    consistencyLevel -
  - withColumnPrefix
```
public ColumnPrefixDistributedRowLock<K> withColumnPrefix(java.lang.String prefix)
```
    Specify the prefix that uniquely distinguishes the lock columns from data column
    
    Parameters:
    prefix -
  - withDataColumns
```
public ColumnPrefixDistributedRowLock<K> withDataColumns(boolean flag)
```
    If true the first read will also fetch all the columns in the row as opposed to just the lock columns.
    
    Parameters:
    flag -
  - withLockId
```
public ColumnPrefixDistributedRowLock<K> withLockId(java.lang.String lockId)
```
    Override the autogenerated lock column.
    
    Parameters:
    lockId -
  - failOnStaleLock
```
public ColumnPrefixDistributedRowLock<K> failOnStaleLock(boolean failOnStaleLock)
```
    When set to true the operation will fail if a stale lock is detected
    
    Parameters:
    failOnStaleLock -
  - expireLockAfter
```
public ColumnPrefixDistributedRowLock<K> expireLockAfter(long timeout,
                                                java.util.concurrent.TimeUnit unit)
```
    Time for failed locks. Under normal circumstances the lock column will be deleted. If not then this lock column will remain and the row will remain locked. The lock will expire after this timeout.
    
    Parameters:
    timeout -
    unit -
  - withTtl
```
public ColumnPrefixDistributedRowLock<K> withTtl(java.lang.Integer ttl)
```
    This is the TTL on the lock column being written, as opposed to expireLockAfter which is written as the lock column value. Whereas the expireLockAfter can be used to identify a stale or abandoned lock the TTL will result in the stale or abandoned lock being eventually deleted by cassandra. Set the TTL to a number that is much greater tan the expireLockAfter time.
    
    Parameters:
    ttl -
  - withTtl
```
public ColumnPrefixDistributedRowLock<K> withTtl(java.lang.Integer ttl,
                                        java.util.concurrent.TimeUnit units)
```
  - withBackoff
```
public ColumnPrefixDistributedRowLock<K> withBackoff(com.netflix.astyanax.retry.RetryPolicy policy)
```
  - acquire
```
public void acquire()
             throws java.lang.Exception
```
    Try to take the lock. The caller must call .release() to properly clean up the lock columns from cassandra
    
    Specified by:
    
    acquire in interface DistributedRowLock
    
    Throws:
    
    java.lang.Exception
  - acquireLockAndReadRow
```
public com.netflix.astyanax.model.ColumnMap<java.lang.String> acquireLockAndReadRow()
                                                                             throws java.lang.Exception
```
    Take the lock and return the row data columns. Use this, instead of acquire, when you want to implement a read-modify-write scenario and want to reduce the number of calls to Cassandra.
    
    Throws:
    
    java.lang.Exception
  - verifyLock
```
public void verifyLock(long curTimeInMicros)
                throws java.lang.Exception,
                       BusyLockException,
                       StaleLockException
```
    Verify that the lock was acquired. This shouldn't be called unless it's part of a recipe built on top of ColumnPrefixDistributedRowLock.
    
    Parameters:
    curTimeInMicros -
    
    Throws:
    
    BusyLockException
    
    java.lang.Exception
    
    StaleLockException
  - release
```
public void release()
             throws java.lang.Exception
```
    Release the lock by releasing this and any other stale lock columns
    
    Specified by:
    
    release in interface DistributedRowLock
    
    Throws:
    
    java.lang.Exception
  - releaseWithMutation
```
public void releaseWithMutation(com.netflix.astyanax.MutationBatch m)
                         throws java.lang.Exception
```
    Release using the provided mutation. Use this when you want to commit actual data when releasing the lock
    
    Parameters:
    m -
    
    Throws:
    
    java.lang.Exception
  - releaseWithMutation
```
public boolean releaseWithMutation(com.netflix.astyanax.MutationBatch m,
                          boolean force)
                            throws java.lang.Exception
```
    Throws:
    
    java.lang.Exception
  - readLockColumns
```
public java.util.Map<java.lang.String,java.lang.Long> readLockColumns()
                                                               throws java.lang.Exception
```
    Return a mapping of existing lock columns and their expiration times
    
    Throws:
    
    java.lang.Exception
  - releaseAllLocks
```
public java.util.Map<java.lang.String,java.lang.Long> releaseAllLocks()
                                                               throws java.lang.Exception
```
    Release all locks. Use this carefully as it could release a lock for a running operation.
    
    Returns:
    Map of previous locks
    
    Throws:
    
    java.lang.Exception
  - releaseExpiredLocks
```
public java.util.Map<java.lang.String,java.lang.Long> releaseExpiredLocks()
                                                                   throws java.lang.Exception
```
    Release all expired locks for this key.
    
    Returns:
    map of expire locks
    
    Throws:
    
    java.lang.Exception
  - releaseLocks
```
public java.util.Map<java.lang.String,java.lang.Long> releaseLocks(boolean force)
                                                            throws java.lang.Exception
```
    Delete locks columns. Set force=true to remove locks that haven't expired yet. This operation first issues a read to cassandra and then deletes columns in the response.
    
    Parameters:
    force - - Force delete of non expired locks as well
    
    Returns:
    Map of locks released
    
    Throws:
    
    java.lang.Exception
  - fillLockMutation
```
public java.lang.String fillLockMutation(com.netflix.astyanax.MutationBatch m,
                                java.lang.Long time,
                                java.lang.Integer ttl)
```
    Fill a mutation with the lock column. This may be used when the mutation is executed externally but should be used with extreme caution to ensure the lock is properly released
    
    Parameters:
    m -
    time -
    ttl -
  - readTimeoutValue
```
public long readTimeoutValue(com.netflix.astyanax.model.Column<?> column)
```
    Read the expiration time from the column value
    
    Parameters:
    column -
  - fillReleaseMutation
```
public void fillReleaseMutation(com.netflix.astyanax.MutationBatch m,
                       boolean excludeCurrentLock)
```
    Fill a mutation that will release the locks. This may be used from a separate recipe to release multiple locks.
    
    Parameters:
    m -
  - getDataColumns
```
public com.netflix.astyanax.model.ColumnMap<java.lang.String> getDataColumns()
```
  - getKey
```
public K getKey()
```
  - getKeyspace
```
public com.netflix.astyanax.Keyspace getKeyspace()
```
  - getConsistencyLevel
```
public com.netflix.astyanax.model.ConsistencyLevel getConsistencyLevel()
```
  - getLockColumn
```
public java.lang.String getLockColumn()
```
  - getLockId
```
public java.lang.String getLockId()
```
  - getPrefix
```
public java.lang.String getPrefix()
```
  - getRetryCount
```
public int getRetryCount()
```

Class ColumnPrefixDistributedRowLock<K>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LOCK_TIMEOUT

DEFAULT_OPERATION_TIMEOUT_UNITS

DEFAULT_LOCK_PREFIX

Constructor Detail

ColumnPrefixDistributedRowLock

Method Detail

withConsistencyLevel

withColumnPrefix

withDataColumns

withLockId

failOnStaleLock

expireLockAfter

withTtl

withTtl

withBackoff

acquire

acquireLockAndReadRow

verifyLock

release

releaseWithMutation

releaseWithMutation

readLockColumns

releaseAllLocks

releaseExpiredLocks

releaseLocks

fillLockMutation

readTimeoutValue

fillReleaseMutation

getDataColumns

getKey

getKeyspace

getConsistencyLevel

getLockColumn

getLockId

getPrefix

getRetryCount