Read/Write Cache Data with Streams

Note

This feature is only available in NCache Enterprise Edition.

GetCacheStream API with different overloads is used to open a stream. GetCacheStream API opens the stream of specified key with provided streaming mode. It returns the handle of the opened stream as an object of CacheStream class.

CacheStream is derived from System.IO.Stream. It is designed to read/write BLOB using standard Stream interface. However, it does not support 'seeking' which is the querying and modifying the current position within a stream.

• .NET/.NET Core
• Java

Pre-Requisites

• Include the following namespaces in your application:
  • Alachisoft.NCache.Runtime.Caching
  • Alachisoft.NCache.Client
  • Alachisoft.NCache.Runtime.Exceptions
• Cache must be running.
• Make sure that the data being added is serializable.
• To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Reading from Stream

This mode is used for acquiring read-only access to the stream. With the help of the example given below, a stream can be opened with read-only property on provided key.

• .NET/.NET Core
• Java

try
{
    // Pre-condition: Cache is already connected
    // Generate a unique cache key
    string key = "StreamKey";

    // Initialize CacheStream object
    CacheStream cacheStream = null;

    // Set StreamMode object to Read mode
    StreamMode streamMode = StreamMode.Read;

    // Provide the streamMode object to cachestreamAttributes object 
    var streamAttributes = new CacheStreamAttributes(streamMode);

    // Use GetCacheStream to set streamAttributes against the specified key 
    cacheStream = cache.GetCacheStream(key, streamAttributes);
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // handle exception
    // This includes StreamException
}

Now data can be read from this CacheStream object. GetCacheStream with Read mode throws StreamException if no data exists in the cache with the specified key.

Reading from Stream without Lock

This mode is useful when write and read operations are to be performed in parallel. The following example explains how to get stream object with ReadWithoutLock property. The method used for reading from stream without lock is getCacheStream For Java.

• .NET/.NET Core
• Java

try
{
    // Pre-condition: Cache is already connected
    // Generate a unique cache key
    string key = "StreamKey";

    // Initialize CacheStream object
    CacheStream cacheStream = null;

    // Set StreamMode object to ReaddWithoutLock mode
    StreamMode streamMode = StreamMode.ReadWithoutLock;

    // Provide the streamMode object to cachestreamAttributes object 
    var streamAttributes = new CacheStreamAttributes(streamMode);

    // Use GetCacheStream to set streamAttributes against the specified key 
    cacheStream = cache.GetCacheStream(key, streamAttributes);
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // handle exception
    // This includes StreamException
}

Data can be read from this CacheStream object. GetCacheStream with ReadWithoutLock mode throws StreamException if no data exists in the cache with the specified key.

Writing to a Stream

In write mode only a single write operation can be performed on a stream. It will throw an exception if stream is already in use by another application.

• .NET/.NET Core
• Java

try
{
    // Pre-condition: Cache is already connected
    // Generate a unique cache key
    string key = "StreamKey";

    // Initialize CacheStream object
    CacheStream cacheStream = null;

    // Set StreamMode object to Write mode
    StreamMode streamMode = StreamMode.Write;

    // Provide the streamMode object to cachestreamAttributes object 
    var streamAttributes = new CacheStreamAttributes(streamMode);

    // Use GetCacheStream to set streamAttributes against the specified key 
    cacheStream = cache.GetCacheStream(key, streamAttributes);
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}
catch (Exception ex)
{
    // handle exception
    // This includes StreamException
}

Now data can be written to this CacheStream object.

Using GetBufferedStream

Buffered stream is the set of bytes used for storing the data up to the certain limit before reading or writing it to the cache. The following code shows how to use GetBufferedStream:

• .NET/.NET Core
• Java

try
{
    // Pre-condition: Cache is already connected
    // Generate a unique cache key
    string key = "StreamKey";

    // Set 'Write' property for StreamMode object
    StreamMode streamMode = StreamMode.Write;

    // Provide the streamMode object to cachestreamAttributes object 
    var streamAttributes = new CacheStreamAttributes(streamMode);

    // ReadAllBytes returns the stream from the provided path in a byte Array
    byte[] writeBuffer = System.IO.File.ReadAllBytes("C:\\ncache-manual.pdf");

    // Set buffer length
    int length = writeBuffer.length;

    // Set GetBufferedStream property for cache stream
    System.IO.Stream wstream = cache.GetCacheStream(key, streamAttributes).GetBufferedStream(length);

    // Write data in buffer
    wstream.Write(writeBuffer, 0, length / 2);

    // Data is written in cache because buffer is full now
    wstream.Write(writeBuffer, length / 2, length / 2);

    //...Close the stream
}
catch (OperationFailedException ex)
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
}   
catch (Exception ex)
{
    // handle exception
    // This includes StreamException
}

Additional Resources

NCache provides sample application for streaming at:

• GitHub
• Shipped with NCache: %NCHOME%\samples\dotnet\Streaming

See Also

Continuous Query
Add and Update Data with Streams
Retrieving Data from Streams
Closing a Stream
Security and Encryption