How to Connect to Cache

After successfully configuring NCache, you can start developing applications utilizing NCache by embedding NCache API calls. In order to do that, you need to connect to the cache. Single as well as multiple caches can be connected in a single application. Moreover, cache can be connected with security credentials.

Pre-Requisites

Include the following namespaces in your application:
- Alachisoft.NCache.Client
- Alachisoft.NCache.Runtime.Exceptions
The caches being connected must be configured and running.
For API details, refer to: ICache, CacheManager, GetCache, CacheConnectionOptions.
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 caches being connected must be configured and running.
For API details, refer to: Cache, CacheManager, getCache, CacheConnectionOptions.

Connect to Single Cache

NCache provides ICache interface to get an instance of a NCache’s cache. Moreover, the CacheManager class lets you connect to the cache instance via GetCache method.

Important

The cache being connected must be configured and running.

The following example connects to a cache named myPartitionedCache which is in running state.

try
{
    // Specify the cache name
    string cacheName = "myPartitionedCache";

    // Connect to cache
    ICache cache = CacheManager.GetCache(cacheName);
}
catch (OperationFailedException ex)
{
      // NCache specific exception
      if (ex.ErrorCode == NCacheErrorCodes.NO_SERVER_AVAILABLE)
      {
            // Make sure NCache Service and cache is running
      }
      else
      {
            // Exception can occur due to:
            // Connection Failures
            // Operation Timeout
            // Operation performed during state transfer
      }
}
catch (ConfigurationException ex)
{
      if(ex.ErrorCode == NCacheErrorCodes.SERVER_INFO_NOT_FOUND)
      {     
            // client.ncconf must have server information
      }
}
catch (Exception ex)
{
      // Any generic exception like ArgumentNullException or ArgumentException
      // Argument exception occurs in case of empty string name
      // Make sure TLS is enabled on both client and server
}

try {
      // Connect to cache
      cache = CacheManager.getCache(cacheName);
      } catch (OperationFailedException exception) {

      // NCache specific exception
      if (exception.getErrorCode() == NCacheErrorCodes.NO_SERVER_AVAILABLE) {
            // Make sure NCache service and cache are running
      } else {
            // Exception can occur due to:
            // Connection failures
            // Operation timeout
            // Operation performed during state transfer
      }
      } catch (ConfigurationException exception) {
      if (exception.getErrorCode() == NCacheErrorCodes.SERVER_INFO_NOT_FOUND) {
            // client.ncconf must have server information
      }
      } catch (Exception exception) {
            // Any generic exception
      }

// This is an async method
try {
      // Specify the cache name
      let cacheName = "myPartitionedCache";

      // Connect to cache
      let cache = await ncache.CacheManager.getCache(cacheName);
      } catch (error) {
      // Handle any exceptions
      }

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Connect to Multiple Caches

Using the GetCache method, you can connect to multiple caches within a single application. This will help you manage the data of multiple caches using one application.

Important

The caches being connected must be configured and running.

Following example connects to two caches, myPartitionedCache and myReplicatedCache from the same client.

try
{             
    // Specify cache names
    string cacheName1 = "myPartitionedCache";
    string cacheName2 = "myReplicatedCache";

    // Connect to the caches
    ICache cache1 = CacheManager.GetCache(cacheName1);
    ICache cache2 = CacheManager.GetCache(cacheName2);
}
catch (OperationFailedException ex)
{
      // NCache specific exception
      if (ex.ErrorCode == NCacheErrorCodes.NO_SERVER_AVAILABLE)
      {
            // Make sure NCache Service and cache is running
      }
      else
      {
            // Exception can occur due to:
            // Connection Failures
            // Operation Timeout
            // Operation performed during state transfer
      }
}
catch (ConfigurationException ex)
{
      if(ex.ErrorCode == NCacheErrorCodes.SERVER_INFO_NOT_FOUND)
      {     
            // client.ncconf must have server information
      }
}
catch (Exception ex)
{
      // Any generic exception like ArgumentNullException or ArgumentException
      // Argument exception occurs in case of empty string 
      // Make sure TLS is enabled on both client and server
}

try {
      // Connect to the caches
      Cache cache1 = CacheManager.getCache(cacheName1);
      Cache cache2 = CacheManager.getCache(cacheName2);
      } catch (OperationFailedException exception) {

      // NCache specific exceptions
      if (exception.getErrorCode() == NCacheErrorCodes.NO_SERVER_AVAILABLE) {
            // Make sure NCache service and caches are running
      } else {
            // Exception can occur due to:
            // Connection failures
            // Operation timeout
            // Operation performed during state transfer
      }
      } catch (ConfigurationException exception) {
      if (exception.getErrorCode() == NCacheErrorCodes.SERVER_INFO_NOT_FOUND) {
            // client.ncconf must have servers information
      }
      } catch (Exception exception) {
            // Any generic exception
      }

try {
      // Specify cache names
      let cacheName1 = "myPartitionedCache";
      let cacheName2 = "myReplicatedCache";

      // Connect to the caches
      let cache1 = await ncache.CacheManager.getCache(cacheInstance1);
      let cache2 = await ncache.CacheManager.getCache(cacheInstance2);
      } catch (error) {
      // Handle any exceptions
      }

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Connect to Cache Using CacheConnectionOptions

CacheConnectionOptions allows specifying values of cache properties while establishing a connection to the cache. These values are the same which can be configured through client.ncconf file.

Warning

Any configuration specified through CacheConnectionOptions will override the value in client.ncconf for that particular client.

In this example, the values of RetryInterval, ConnectionRetries, EnableKeepAlive and KeepAliveInterval properties can be changed. For this application, these values will be used instead of the ones specified in client configuration file.

Important

The cache being connected must be configured and running.

try
{
    // Create new CacheConnectionOptions instance
    var options = new CacheConnectionOptions();

    // Specify the cache connection options to be set           
    options.RetryInterval = TimeSpan.FromSeconds(5);
    options.ConnectionRetries = 2;
    options.EnableKeepAlive = true;
    options.KeepAliveInterval = TimeSpan.FromSeconds(30);

    // Specify the cache name
    string cacheName = "myPartitionedCache";

    // Connect to cache with CacheConnectionOptions
    ICache cache = CacheManager.GetCache(cacheName, options);
}
catch (OperationFailedException ex)
{
      // NCache specific exception
      if (ex.ErrorCode == NCacheErrorCodes.NO_SERVER_AVAILABLE)
      {
            // Make sure NCache Service and cache is running
      }
      else
      {
            // Exception can occur due to:
            // Connection Failures
            // Operation Timeout
            // Operation performed during state transfer
      }
}
catch (ConfigurationException ex)
{
      if(ex.ErrorCode == NCacheErrorCodes.SERVER_INFO_NOT_FOUND)
      {     
            // client.ncconf must have server information
      }
}
catch (Exception ex)
{
      // Any generic exception like ArgumentNullException or ArgumentException
      // Argument exception occurs in case of empty string name
      // Make sure TLS is enabled on both client and server
}

try {
      // Create new CacheConnectionOptions instance
      CacheConnectionOptions options = new CacheConnectionOptions();

      // Specify the cache connection options to be set
      TimeSpan retryInterval = new TimeSpan(0, 0, 5);
      options.setRetryInterval(retryInterval);
      options.setConnectionRetries(2);
      options.setEnableClientLogs(true);
      TimeSpan keepAliveInterval = new TimeSpan(0, 0, 30);
      options.setKeepAliveInterval(keepAliveInterval);

      // Specify the cache name
      String cacheName = "myPartitionedCache";

      // Connect to cache with CacheConnectionOptions
      Cache cache = CacheManager.getCache(cacheName);
      } catch (OperationFailedException exception) {
      // NCache specific exceptions
      if (exception.getErrorCode() == NCacheErrorCodes.NO_SERVER_AVAILABLE) {
            // Make sure NCache service and cache are running
      } else {
            // Exception can occur due to:
            // Connection failures
            // Operation timeout
            // Operation performed during state transfer
      }
      } catch (Exception exception) {
      // Any generic exception
      }

try {
      // Create new CacheConnectionOptions instance
      let options = new ncache.CacheConnectionOptions();

      // Specify the cache connection options to be set
      let retryInterval = new ncache.TimeSpan(0, 0, 5);
      options.setRetryInterval(retryInterval);
      options.setConnectionRetries(2);
      options.setEnableClientLogs(true);
      let keepAliveInterval = new ncache.TimeSpan(0, 0, 30);
      options.setKeepAliveInterval(keepAliveInterval);

      // Specify the cache name
      let cacheName = "myPartitionedCache";

      // Connect to cache with CacheConnectionOptions
      let cache = await ncache.CacheManager.getCache(cacheName);
      } catch (error) {
      // Handle any exceptions
      }

Recommendation: To ensure the operation is fail safe, it is recommended to handle any potential exceptions within your application, as explained in Handling Failures.

Connect to Clustered and Client Cache

One can connect to clustered and client cache in a single call using the GetCache method. This will initialize both the caches within a single application hence helping you manage the data of multiple caches through one application.

Note

If local cache is connected as client cache, serialization must be the same as of clustered cache. Both caches must be configured previously and must be in a running state.

Following example connects to two caches using GetCache method.

try
{               
    // Specify the cache names
    string clusteredCache = "myClusteredCache";
    string clientCache = "myClientCache";

    CacheConnectionOptions cacheConnectionOptions = new CacheConnectionOptions();
    cacheConnectionOptions.LoadBalance = true;
    cacheConnectionOptions.ConnectionRetries = 5;

    CacheConnectionOptions clientCacheConnectionOptions = new CacheConnectionOptions();
    clientCacheConnectionOptions.LoadBalance = true;
    clientCacheConnectionOptions.ConnectionRetries = 5;
    clientCacheConnectionOptions.Mode = IsolationLevel.OutProc;

    // Connect to the caches in a single call
    // CacheConnectionOptions which can be null if not required
    ICache cache = CacheManager.GetCache(clusteredCache, cacheConnectionOptions, clientCache, clientCacheConnectionOptions);

}
catch (OperationFailedException ex)
{
      // NCache specific exception
      if (ex.ErrorCode == NCacheErrorCodes.NO_SERVER_AVAILABLE)
      {
            // Make sure NCache Service and cache is running
      }
      else
      {
            // Exception can occur due to:
            // Connection Failures
            // Operation Timeout
            // Operation performed during state transfer
      }
}
catch (ConfigurationException ex)
{
      if(ex.ErrorCode == NCacheErrorCodes.SERVER_INFO_NOT_FOUND)
      {     
            // client.ncconf must have server information
      }
}
catch (Exception ex)
{
      // Any generic exception like ArgumentNullException or ArgumentException
      // Argument exception occurs in case of empty string name
      // Make sure TLS is enabled on both client and server
}

try {
      // Specify cache names
      String clusteredCache = "myClusteredCache";
      String clientCache = "myClientCache";

      // Create and set CacheConnectionOptions for clustered cache
      CacheConnectionOptions cacheConnectionOptions = new CacheConnectionOptions();
      cacheConnectionOptions.setLoadBalance(true);
      cacheConnectionOptions.setConnectionRetries(5);

      // Create and set CacheConnectionOptions for client cache
      CacheConnectionOptions clientCacheConnectionOptions = new CacheConnectionOptions();
      clientCacheConnectionOptions.setLoadBalance(true);
      clientCacheConnectionOptions.setConnectionRetries(5);
      clientCacheConnectionOptions.setIsolationLevel(IsolationLevel.OutProc);

      // Connect to caches in single call
      // CacheConnectionOptions which can be null if not required
      Cache cache = CacheManager.getCache(clusteredCache, cacheConnectionOptions, clientCache, clientCacheConnectionOptions);
      } catch (OperationFailedException exception) {
      // NCache specific exception
      if (exception.getErrorCode() == NCacheErrorCodes.NO_SERVER_AVAILABLE) {
            // Make sure NCache service and caches are running
      } else {
            // Exception can occur due to:
            // Connection failures
            // Operation timeout
            // Operation performed during state transfer
      }
      } catch (Exception exception) {
      // Any generic exception
      }

try {
      // Specify cache names
      let clusteredCache = "myClusteredCache";
      let clientCache = "myClientCache";

      // Create and set CacheConnectionOptions for clustered cache
      let cacheConnectionOptions = new ncache.CacheConnectionOptions();
      cacheConnectionOptions.setLoadBalance(true);
      cacheConnectionOptions.setConnectionRetries(5);

      // Create and set CacheConnectionOptions for client cache
      let clientCacheConnectionOptions = new ncache.CacheConnectionOptions();
      clientCacheConnectionOptions.setLoadBalance(true);
      clientCacheConnectionOptions.setConnectionRetries(5);
      clientCacheConnectionOptions.setIsolationLevel(ncache.IsolationLevel.OutProc);

      // Connect to caches in single call
      // CacheConnectionOptions which can be null if not required
      let cache = await ncache.CacheManager.getCache(clusteredCache, cacheConnectionOptions, clientCache, clientCacheConnectionOptions);
      } catch (error) {
      // Handle any exceptions
      }

Connect to Cache with Security Credentials

If security has been enabled, you need to provide the security credentials while connecting to the caches so that the authorized user can perform the operation. For more details on using security in NCache, see NCache Security.

try
{
    // Specify cache name and user credentials 
    string cacheName =  "myPartitionedCache";
    string userId = "userid";
    string password = "mypassword";

    // Initialize the CacheConnectionOptions
    var options = new CacheConnectionOptions();

    // Enter the credentials
    options.UserCredentials = new Credentials(userId, password);

    // Connect to the cache using the security credentials
    ICache cache = CacheManager.GetCache(cacheName, options);
}
catch (SecurityException ex)
{
    // The user does not have permissions to access the cache                 
}
catch (OperationFailedException ex)
{
      // NCache specific exception
      if (ex.ErrorCode == NCacheErrorCodes.NO_SERVER_AVAILABLE)
      {
            // Make sure NCache Service and cache is running
      }
      else
      {
            // Exception can occur due to:
            // Connection Failures
            // Operation Timeout
            // Operation performed during state transfer
      }
}
catch (ConfigurationException ex)
{
      if(ex.ErrorCode == NCacheErrorCodes.SERVER_INFO_NOT_FOUND)
      {     
            // client.ncconf must have server information
      }
}
catch (Exception ex)
{
      // Any generic exception like ArgumentNullException or ArgumentException
      // Argument exception occurs in case of empty string name
      // Make sure TLS is enabled on both client and server
}

try {
      // Initialize credentials
      String userId = "UserId";
      String password = "UserPassword";
      String cacheName = "demoClusteredCache";

      // Use CacheConnectionOptions to provide credentials
      CacheConnectionOptions options = new CacheConnectionOptions();

      // Use UserCredentials property to assign credentials
      Credentials credentials = new Credentials(userId, password);
      options.setUserCredentials(credentials);

      // Connecting to cache with security credentials
      Cache cache = CacheManager.getCache(cacheName, options);
      } catch (OperationFailedException exception) {
      // NCache specific exception
      if (exception.getErrorCode() == NCacheErrorCodes.NO_SERVER_AVAILABLE) {
            // Make sure NCache service and cache are running
      } else {
            // Exception can occur due to:
            // Connection failures
            // Operation timeout
            // Operation performed during state transfer
      }
      } catch (ConfigurationException exception) {
      if (exception.getErrorCode() == NCacheErrorCodes.SERVER_INFO_NOT_FOUND) {
            // client.ncconf must have server information
      }
      } catch (Exception exception) {
      // Any generic exception
      }

try {
      // Initialize credentials
      let userId = "UserId";
      let password = "UserPassword";
      let cacheName = "demoClusteredCache";

      // Use CacheConnectionOptions to provide credentials
      let options = new ncache.CacheConnectionOptions();

      // Use UserCredentials property to assign credentials
      let credentials = new ncache.Credentials(userId, password);
      options.setUserCredentials(credentials);

      // Connecting to cache with security credentials
      let cache = await ncache.CacheManager.getCache(cacheName, options);
      } catch (error) {
      // Handle any exceptions
      }

Troubleshooting

"No server available to process request"

Sometimes a cluster can not be created because the Server and Cluster ports are blocked by firewall. Following error message can occur in this case:

Error: "Cannot open service control manager on computer"

Workaround

Make sure that the Server port (at which NCache Service starts and accepts different client connections) is not blocked by firewall. Default value of this port is '9800'. You can change the default value from Alachisoft.NCache.Service.exe.config file.

NCache Web Manager unable to connect with NCache Service:
If NCache Web Manager is unable to connect with NCache Service, even when it is started, then your system firewall might be blocking Service port. Unblock Service port from system firewall.

"Unable to communicate with server node"

Cluster nodes can also be unable to communicate with each other because of the aforementioned reason as well.

Error: "Unable to communicate with server node"

Workaround

See if your firewall is allowing the Cluster port. Cluster port is a port at which nodes in a cluster communicate. You can change the default value of these ports from NCache Web Manager. If you have specified a port range in NCache Web Manager, unblock all ports in range.

Client Socket Deadlock

You may experience a deadlock situation on your client socket because of a long wait for a response from the cache server. This may also result in a lot of waiting threads that may cause performance issues.

Workaround

Step1: Changes on Server Side

Go to the service configuration file:

.NET: Alachisoft.NCache.Service.exe.config located in %NCHOME%/bin/service
.NET Core Windows: Alachisoft.NCache.Service.dll.config located in %NCHOME%/bin/service
.NET Core Linux: Alachisoft.NCache.Daemon.dll.config located in /opt/ncache/bin/service

Add the following lines in the configuration file:

<add key ="NCacheServer.EnableBadClientDetection" value = "true" />

The value "true" indicates that BadClientDetection is enabled on your client socket. This means that now if a deadlock situation arises on your client socket, the socket will be reset. The default value of this property is "false".

<add key ="NCacheServer.ClientSocketSendTimeout" value = "10" />

When you have enabled BadClientDetection, you can specify the time interval after which the socket is reset in case of a deadlock. The default value of this property is "10" and this value can not be less than 1.

A few other properties have also been introduced in Alachisoft.NCache.Service.exe.config to help with this issue. Please configure these properties as follows:

<add key ="NCacheServer.EventPriorityRatio" value="30"/>

On the server-side a priority queue is used for events and cache operations. You can configure a ratio of events and cache operations for this queue through the property called EventPriorityRatio. The default value of this property is 30 which indicates a ratio 30:70 for events and cache operations. The value of this property can not be less than 1.

<add key ="NCacheServer.EventBulkCount" value="50"/>

The cache server now sends events to clients in bulk. Through this property you can set the number of items to be sent in bulk. By default this value is 50 and the value can not be less than 1. This is available in client version 4124 and above.

<add key ="NCacheServer.EventBulkCollectionInterval" value="2"/>

This property is used to set the time interval, in seconds, after which bulk of events is fired even in case the bulk count does not reach the EventBulkCount that the user has specified. Default value for this property is 2 seconds and the value can not be less than 1.

Restart the NCache service for these changes to take effect.

Step2: Changes on Client Side

Please make the following changes in your App.config/Web.config file:

<configuration>
    <appSettings>
          <add key ="NCacheClient.AsynchronousEventNotification" value="true"/>
          <add key ="NCacheClient.NumberofEventProccesingThreads" value="2"/>
     </appSettings>
</configuration>

AsynchronousEventNotification: Specifies whether events will be fired asynchronously or synchronously on client side. The default value is "true" which indicates that events will be fired asynchronously. The value "false" means that events will be fired synchronously on client side.

NumberofEventProcessingThreads: When the user has configured events to be fired synchronously, this flag is used to specify the number of threads which will process these events on client side. A very large value can cause performance issues.

How to Connect to Cache

Pre-Requisites

Connect to Single Cache

Important

Connect to Multiple Caches

Important

Connect to Cache Using CacheConnectionOptions

Warning

Important

Connect to Clustered and Client Cache

Note

Connect to Cache with Security Credentials

Troubleshooting

"No server available to process request"

Workaround

"Unable to communicate with server node"

Workaround

Client Socket Deadlock

Workaround

See Also