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.

Install the following NuGet packages in your application:
- Alachisoft.NCache.SDK
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.
For API details, refer to: ICache, CacheStream, StreamMode, CacheStreamAttributes.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

Add the following Maven dependencies in your pom.xml file:

<dependency>
      <groupId>com.alachisoft.ncache</groupId>
      <artifactId>ncache-client</artifactId>
      <version>5.2.0</version>
</dependency>

Include the following namespaces in your application:
- import com.alachisoft.ncache.client.*;
- import com.alachisoft.ncache.runtime.exceptions.*;
The application must be connected to cache before performing the operation.
Cache must be running.
Make sure that the data being added is serializable.
For API details, refer to: Cache, CacheStream, StreamMode, CacheStreamAttributes.
To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.
To handle any unseen exceptions, refer to the Troubleshooting section.

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
}

try 
{
    // Precondition: Cache is already connected

    // Generate a unique cache key
    String key = "StreamKey";

    // Initialize cache stream object
    CacheStream cacheStream = null;

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

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

    // Use GetCacheStream to set streamAttributes against the specified key
    cacheStream = cache.getCacheStream(key, streamAttributes);

} 
catch (OperationFailedException exception) 
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
} 
catch (Exception exception) 
{
    // Generic exception like IllegalArgumentException or NullPointerException
}

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.

.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
}

try 
{
    // Precondition: cache is already connected

    // Generate a unique key
    String key = "StreamKey";

    // Initialize CacheStream object
    CacheStream cacheStream = null;

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

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

    // Use GetCacheStream to set streamAttributes against the specified key
    cacheStream = cache.getCacheStream(key, streamAttributes);
} 
catch (OperationFailedException exception) 
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
} 
catch (Exception exception) 
{
    // Generic exception like IllegalArgumentException or NullPointerException
}

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
}

try 
{
    // Precondition: 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
    CacheStreamAttributes streamAttributes = new CacheStreamAttributes(streamMode);

    // Use GetCacheStream to set streamAttributes against the specified key
    cacheStream = cache.getCacheStream(key, streamAttributes);
} 
catch (OperationFailedException exception) 
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
} 
catch (Exception exception) 
{
    // Generic exception like IllegalArgumentException or NullPointerException
}

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
}

try 
{
    // Precondition: cache is already connected

    // Generate a unique cache key

    String key = "StreamKey";

    // Set write mode for StreamMode object
    StreamMode streamMode = StreamMode.Write;

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

    // ReadAllBytes returns the stream from the provided path in a byte array
    Path path = FileSystems.getDefault().getPath("test", "test.txt");
    byte[] writeBuffer = Files.readAllBytes(path);

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

    // Set GetBufferedStream property for cache stream
    BufferedOutputStream wStream = cache.getCacheStream(key, streamAttributes).getBufferedOutputStream(length);

    // Write data in buffer
    wStream.write(writeBuffer, 0, length);

    // Data is written in cache because buffer is full
    wStream.write(writeBuffer, length / 2, length / 2);

    // Close the stream
    wStream.close();
} 
catch (OperationFailedException exception) 
{
    // Exception can occur due to:
    // Connection Failures
    // Operation Timeout
    // Operation performed during state transfer
} 
catch (Exception exception) 
{
    // Generic exception like IllegalArgumentException or NullPointerException
}

Additional Resources

NCache provides sample application for streaming on GitHub.