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.
  • 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 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. For Java, NCache provides the getCache method to connect to cache.

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
}

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
}

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.

For Java, CacheConnectionOptions allows specifying the values of cache properties while connecting to the cache.

Warning

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

Refer to the API Documentation for more details on properties of CacheConnectionOptions class.

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
}

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. For Java, it uses the initializeCache method to connect to cache.

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
}

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
}

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: Alachsioft.NCache.Service.exe.config located in %NCHOME%/bin/service
  • .NET Core Windows: Alachsioft.NCache.Service.dll.config located in %NCHOME%/bin/service
  • .NET Core Linux: Alachsioft.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.

See Also

Cache Keys and Data Overview
Basic Operations for Caching Data
Error Handling in Cache
Management Operations on Cache