NamedCacheUpdate Method (Byte, Object, UpdateOptions)

ScaleOut Software NamedCache API
Updates an object in the named cache.

Namespace:  Soss.Client
Assembly:  soss_namedcache (in soss_namedcache.dll) Version: 6.1.0.0
Syntax

public void Update(
	byte[] id,
	Object obj,
	UpdateOptions options
)

Parameters

id
Type: SystemByte
Object identifier. The argument must be an array of either 16 or 32 bytes.
obj
Type: SystemObject
The new value for the object in the shared cache. The argument must be serializable, and it cannot be null.
options
Type: Soss.ClientUpdateOptions

UpdateOptions used when performing the update operation. The LockingMode property controls locking behavior of the Update call.

If the LockingMode is None and the object is locked, the lock will be retained by the caller. If the object is not locked by this instance of the NamedCache then the option is ignored.

If the LockingMode is UnlockAfterUpdate and the object is locked, the lock will be released by the caller upon completion of the update. If the object is not locked by this instance of the NamedCache then the option is ignored.

If the LockingMode is UpdateIfSameVersion, an optimistic locking update will be performed. The update will succeed only if the version sent by the client matches the current version in the StateServer--otherwise an OptimisticLockException will be thrown. If a pessimistic lock is being held by this instance of the NamedCache then this option will cause an InvalidOperationException to be thrown. Objects that use the UpdateIfSameVersion option must implement the IOptimisticConcurrencyVersionHolder interface.

Exceptions

ExceptionCondition
ObjectNotFoundExceptionThrown if the object to update does not exist in the cache.
StateServerExceptionThrown if ScaleOut StateServer is unavailable or has experienced an internal error.
ArgumentNullExceptionThrown if obj is null.
OptimisticLockExceptionThrown if an optimistic locking update is performed and the version sent to the server is stale (indicating that another client updated the object in the interval after this client accessed the object).
ArgumentExceptionThrown if an optimistic locking update is attempted but the obj argument does not implement the IOptimisticConcurrencyVersionHolder interface.
InvalidOperationExceptionThrown if an optimistic locking update is attempted on an object when the NamedCache instance already holds a pessimistic lock for the object.
Remarks

The Update(CachedObjectId, Object, Boolean) method updates an object in the named cache and allows for fine-grained control over locking of the object. Unlike the ItemCachedObjectId accessor, the Update(CachedObjectId, Object, Boolean) method does not honor the UseLocking property. The AcquireLock(CachedObjectId) or Retrieve(CachedObjectId, Boolean) methods must be called prior to Update(CachedObjectId, Object, Boolean) if the object needs to be locked pessimistically.

Care should be taken when performing unlocked updates on objects. An unlocked update will not block for locks held by another clients, so other clients may have the object data changed underneath them despite the locks they hold.

In situations where collisions are infrequent (for example, when objects in the cache are updated rarely), an optimistic locking approach can be taken with updates. Set the options parameter's LockingMode property to UpdateIfSameVersion when performing the update. Objects that use optimistic locking must implement the IOptimisticConcurrencyVersionHolder interface.

See Also

Reference