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.

Prerequisites

To learn about the standard prerequisites required to work with all NCache client side features please refer to the given page on Client Side API Prerequisites.
For API details, refer to: ICache, 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.

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

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

    // 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 {
      String cacheName = "demoCache";

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

try {

   var cacheName = "demoCache";

    // Connect to cache
    val cache = CacheManager.getCache(cacheName)
}
catch 
{
      case exception: Exception =>
      // Handle any errors
}

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

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

try:
  # Specify the cache name
  cache_name = "demoCache"

  # Connect to cache
  cache = ncache.CacheManager.get_cache(cache_name)

except Exception as exp:
  # Handle any exceptions

Note

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.

Following example connects to two caches, demoCache1 and demoCache2 from the same client.

try
{             
    // Specify cache names
    string cacheName1 = "demoCache1";
    string cacheName2 = "demoCache2";

    // 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 {
      String cacheName1 = "demoCache1";
      String cacheName2 = "demoCache2";

      // 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 {
      var cacheName1 = "demoCache1";
      var cacheName2 = "demoCache2";

    // Connect to the caches// Connect to the caches
    val cache1 = CacheManager.getCache(cacheName1)
    val cache2 = CacheManager.getCache(cacheName2)
}
catch 
{
    case exception: Exception =>
    // Handle any errors
}

try {
  // Specify cache names
  let cacheName1 = "demoCache1";
  let cacheName2 = "demoCache2";

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

try:
  # Specify cache names
  cache_name_1 = "demoCache1"
  cache_name_2 = "demoCache2"

  # Connect to the caches
  cache_1 = ncache.CacheManager.get_cache(cache_name_1)
  cache_2 = ncache.CacheManager.get_cache(cache_name_2)

except Exception as exp:
  # Handle any exceptions

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.

Note

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.

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 = "demoCache";

    // 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 = "democache";

      // Connect to cache with CacheConnectionOptions
      Cache cache = CacheManager.getCache(cacheName, options);
} 
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
    // Create new CacheConnectionOptions instance

    val options = new CacheConnectionOptions

    // Specify the cache connection options to be set
    val retryInterval = new TimeSpan(0, 0, 5)

    options.setRetryInterval(retryInterval)
    options.setConnectionRetries(2)
    options.setEnableClientLogs(true)
    val keepAliveInterval = new TimeSpan(0, 0, 30)
    options.setKeepAliveInterval(keepAliveInterval)

    // Specify the cache name
    val cacheName = "demoCache"

    // Connect to cache with CacheConnectionOptions
    val cache = CacheManager.getCache(cacheName, options)
}
catch 
{
    case exception: Exception =>
    // Handle any errors
}

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 = "demoCache";

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

try:
  # Create new CacheConnectionOptions instance
  options = ncache.CacheConnectionOptions()

  # Specify the cache connection options to be set
  retry_interval = ncache.TimeSpan(0, 0, 5)
  keep_alive_interval = ncache.TimeSpan(0, 0, 30)

  options.set_retry_interval(retry_interval)
  options.set_connection_retries(2)
  options.set_enable_client_logs(True)
  options.set_keep_alive_interval(keep_alive_interval)

  # Specify the cache name
  cache_name = "demoCache"

  # Connect to cache with CacheConnectionOptions
  cache = ncache.CacheManager.get_cache(cache_name, options)

except Exception as exp:
  # Handle any exceptions

Connect to Clustered and Client Cache

Note

Using the GetCache method to connect to clustered and client cache in a single call is not a recommended approach.

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 = "demoCache";
    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 = "demoCache";
      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

    val clusteredCache = "demoCache"
    val clientCache = "myClientCache"

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

    // Create and set CacheConnectionOptions for client cache
    val 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
    val cache = CacheManager.getCache(clusteredCache, cacheConnectionOptions, clientCache, clientCacheConnectionOptions)
}
catch 
{
    case exception: Exception =>
    // Handle any errors
}

try {
  // Specify cache names
  let clusteredCache = "demoCache";
  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
}

try:
  # Specify cache names
  clustered_cache = "demoCache"
  client_cache = "myClientCache"

  # Create and set CacheConnectionOptions for clustered cache
  cache_connection_options = ncache.CacheConnectionOptions()
  cache_connection_options.set_load_balance(True)
  cache_connection_options.set_connection_retries(5)

  # Create and set CacheConnectionOptions for client cache
  client_cache_connection_options = ncache.CacheConnectionOptions()
  client_cache_connection_options.set_load_balance(True)
  client_cache_connection_options.set_connection_retries(5)
  client_cache_connection_options.set_isolation_level(ncache.IsolationLevel.OUT_PROC)

  # Connect to both of the caches in a single call
  # CacheConnectionOptions can be null if not required
  cache = ncache.CacheManager.get_cache(clustered_cache, cache_connection_options, client_cache, client_cache_connection_options)

except Exception as exp:
  # Handle any exceptions
      print(exp)

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 =  "demoCache";
    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 = "demoCache";

      // 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

    val userId = "UserId"
    val password = "UserPassword"
    val cacheName = "demoCache"

    // Use CacheConnectionOptions to provide credentials
    val options = new CacheConnectionOptions

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

    // Connecting to cache with security credentials
    val cache = CacheManager.getCache(cacheName, options)
}
catch 
{
    case exception: Exception =>
    // Handle any errors
}

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

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

try:
  # Initialize credentials
  user_id = "UserId"
  password = "UserPassword"
  cache_name = "demoCache"

  # Use CacheConnectionOptions to provide credentials
  options = ncache.CacheConnectionOptions()

  # Use UserCredentials property to assign credentials
  credentials = ncache.Credentials(user_id, password)     options.set_user_credentials(credentials)

  # Connecting to cache with security credentials
  cache = ncache.CacheManager.get_cache(cache_name, options)

except Exception as exp:
  # Handle any exceptions

Troubleshooting

No server available to process request

Sometimes a client maybe unable to connect to cache because Client/Server Port is blocked by firewall.

Workaround

Make sure that the Client/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 or Alachisoft.NCache.Service.dll.config file.

Unable to communicate with server node

Cluster nodes can also be unable to communicate with each other because of Cluster Ports being blocked by firewall.

Error: "Unable to communicate with server node"

Workaround

See if your firewall is allowing the Client/Server and 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

Prerequisites

Connect to Single Cache

Note

Connect to Multiple Caches

Connect to Cache Using CacheConnectionOptions

Note

Connect to Clustered and Client Cache

Note

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