NamedCacheInsert Method (Byte, Object, CreatePolicy, Boolean, Boolean)

ScaleOut Software NamedCache API
Inserts a serializable object to a named cache. If an object with the same ID already exists in the cache then it can optionally be updated.

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

public void Insert(
	byte[] id,
	Object obj,
	CreatePolicy createPolicy,
	bool updateIfExists,
	bool lockAfterInsert
)

Parameters

id
Type: SystemByte
Object identifier (must be either 16 or 32 bytes in length).
obj
Type: SystemObject
Serializable object to store in the cache. The argument cannot be null.
createPolicy
Type: Soss.ClientCreatePolicy
CreatePolicy instance containing extended cache policy information for the object.
updateIfExists
Type: SystemBoolean
Determines behavior if the object already exists in the cache. If true, the object will be updated; if false, an ObjectExistsException will be thrown if the object already exists.
lockAfterInsert
Type: SystemBoolean
If true, StateServer will atomically create and lock the object so that additional updates may be performed under a StateServer lock. If false, StateServer will create the object but leave it unlocked, allowing other clients to lock the object.
Exceptions

ExceptionCondition
ObjectLockedExceptionThrown if the object is already in the cache and is locked by another client.
ObjectExistsExceptionThrown if the object exists and the updateIfExists parameter is false.
StateServerExceptionThrown if ScaleOut StateServer is unavailable or has experienced an internal error.
ArgumentNullExceptionThrown if obj or createPolicy is null.
Remarks

Passing null into the obj parameter is not allowed; use Remove(Byte) to delete an object from the cache.

If updateIfExists is true, and a cache object is being updated instead of inserted, then the policy settings in the createPolicy parameter will not be applied to the updated object; instead, the object will continue use the CreatePolicy policies that were in effect when the object was originally added to the cache. The object must be explicitly removed and re-inserted into the cache for new CreatePolicy policies to take effect.

Objects added to the cache with a PreemptionPriority of Normal will only be removed under low memory situations if LRU functionality is enabled in StateServer. Edit the soss_params.txt file in the StateServer installation directory to enable this feature: the lru_threshold parameter should be set to a percentage of the max_memory parameter. Eligible objects will be deleted using a least recently used algorithm once memory usage has passed the threshold.

Examples

using System;
using Soss.Client;

class Program
{
    static void Main(string[] args)
    {
        NamedCache cache = CacheFactory.GetCache("Sample Cache");

        // There are 3 ways to add an object to a cache: an indexer, the Add() method, or the Insert() method.

        // Approach 1: Indexer - can be used to add or update objects in the cache using DefaultCreatePolicy rules:
        cache["key1"] = "This is the first item in the cache.";

        // Approach 2: Add() method - functionally identical to using an indexer to add or update objects in the cache:
        cache.Add("key2", "This is the second item in the cache.");

        // Approach 3: Insert() method - allows objects to be added to the cache with specific CreatePolicy rules and locking options:
        CreatePolicy policy = new CreatePolicy();
        policy.TimeoutMinutes = 10;
        policy.IsAbsoluteTimeout = true;
        policy.Dependencies = new object[] { "key1", "key2" };

        cache.Insert("key3", "This is the third item in the cache", policy, false, false);

        // Remove the first object and confirm the third is removed because of its dependency relationship:
        cache["key1"] = null;
        System.Diagnostics.Debug.Assert(cache["key3"] == null);
    }
}
See Also

Reference