NamedCacheAsyncExtensionsRetrieveAsync Method (NamedCache, Byte, Boolean, LockTicket, CancellationToken)

ScaleOut Software NamedCache API
Asynchronously retrieves an object from the named cache. This extension method is simply a convenience wrapper for SetMetadataAsync(CachedObjectId, ObjectMetadata, Boolean, LockTicket, CancellationToken) which initializes RetrieveOptions based on the value of acquireLock and the cache's DefaultGeoServerReadMode value and creates a CachedObjectId from the supplied id value.

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

public static Task<AsyncReadObjectResult> RetrieveAsync(
	this NamedCache cache,
	byte[] id,
	bool acquireLock,
	LockTicket lockTicket = null,
	CancellationToken cancellationToken = null
)

Parameters

cache
Type: Soss.ClientNamedCache
the NamedCache this extension method operates on.
id
Type: SystemByte
a byte that will be transformed into a CachedObjectId via CreateKey(Byte) which identifies the object in the cache.
acquireLock
Type: SystemBoolean
Indicates that the method should attempt to acquire or refresh a lock when reading the object.
lockTicket (Optional)
Type: Soss.ClientLockTicket
if specified, represents a LockTicket obtained from a previous locking call.
cancellationToken (Optional)
Type: System.ThreadingCancellationToken
An optional CancellationToken that can be used to cancel the asynchronous operation.

Return Value

Type: TaskAsyncReadObjectResult
an AsyncReadObjectResult instance. If the object is successfully read from the cache, it will available via Object. Otherwise, Object will be null. If the object is locked as a result of this method, a LockTicket representing the state of the lock in the cache will be returned via LockTicket.

Usage Note

In Visual Basic and C#, you can call this method as an instance method on any object of type NamedCache. When you use instance method syntax to call this method, omit the first parameter. For more information, see Extension Methods (Visual Basic) or Extension Methods (C# Programming Guide).
Exceptions

ExceptionCondition
ArgumentNullExceptionwhen id is null
InvalidOperationExceptionThrown when attempting use a read-through operations with a NamedCache that is configured for remote store access.
ObjectLockedExceptionThrown if acquireLock parameter requests a lock but the object is locked by another client.
StateServerExceptionThrown if ScaleOut StateServer is unavailable or has experienced an internal error.
ReadThroughTimeoutExceptionThrown if backing store read-through or GeoServer pull replication is used with this NamedCache and the retrieval of the object is delayed beyond the number of retries specified by MaxReadThroughPendingAttempts.
Remarks

This method optionally locks the object in SOSS to prevent other clients from updating or removing the object. The UseLocking property is not taken into consideration by this method. If the acquireLock parameter requests a lock, this call will block until the lock is acquired or the MaxLockAttempts limit has been met (or the the asynchronous operation is cancelled via cancellationToken). The lock affects both an object and its metadata. The lock can be released through a call to one of the async methods that accept a LockTicket: ReleaseLockAsync(CachedObjectId, LockTicket, CancellationToken) or PutAsync(CachedObjectId, Object, CreatePolicy, PutOptions, LockTicket, CancellationToken) flag set.

See Also

Reference