Cache Connectivity

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

Note

This feature is also available in NCache Professional.

Prerequisites for Cache Connectivity

To learn about the standard prerequisites required to work with all NCache client-side features including cache connectivity, 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 NCache’s cache. Moreover, the CacheManager class lets you connect to the cache instance via the GetCache method.

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

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

// Connect to cache
ICache cache = CacheManager.GetCache(cacheName);

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

// Connect to cache
cache = CacheManager.getCache(cacheName);

# Specify the cache name
cache_name = "demoCache"

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

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

// Connect to cache
let cache = await ncache.CacheManager.getCache(cacheName);

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.

The following example connects to two caches, demoCache and demoClusteredCache from the same client.

// Specify cache names
string cacheName1 = "demoCache";
string cacheName2 = "demoClusteredCache";

// Connect to the caches
ICache cache1 = CacheManager.GetCache(cacheName1);
ICache cache2 = CacheManager.GetCache(cacheName2);

// Specify cache names
String cacheName1 = "demoCache";
String cacheName2 = "demoClusteredCache";

// Connect to the caches
Cache cache1 = CacheManager.getCache(cacheName1);
Cache cache2 = CacheManager.getCache(cacheName2);

# Specify cache names
cache_name_1 = "demoCache"
cache_name_2 = "demoClusteredCache"

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

// Specify cache names
let cacheName1 = "demoCache";
let cacheName2 = "demoClusteredCache";

// Connect to the caches
let cache1 = await ncache.CacheManager.getCache(cacheName1);
let cache2 = await ncache.CacheManager.getCache(cacheName2);

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 the RetryInterval, ConnectionRetries, EnableKeepAlive, and KeepAliveInterval properties can be changed. For this application, these values will be used instead of the ones specified in the client configuration file.

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

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

# 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)

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

Connect to Cache Using CacheConnectionOptions for Load Balancer

Often, application deployments employ load balancers to prevent requests from overwhelming servers, i.e., prevent clients from accessing the servers directly. In such circumstances, to ensure that your cluster connects to all the servers, NCache offers the IsLoadBalancer API, as demonstrated below:

.NET

CacheConnectionOptions cacheConnectionOptions = new CacheConnectionOptions();
cacheConnectionOptions.ServerList = new List<ServerInfo>()
{
    new ServerInfo("20.200.20.40", 9800, true)
};
ICache cache = CacheManager.GetCache("demoCache", cacheConnectionOptions);

Note

Learn more about how NCache deals with these load balancers here.

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 the local cache is connected to the Client Cache, serialization must be the same as that of the clustered cache. Both caches must be configured previously and must be in a running state.

The following example connects to two caches using the GetCache method.

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

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

# 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)

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

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.

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

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

# 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)

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

Troubleshooting

Port is Not Accessible

Sometimes clients may be unable to connect to a cache due to your firewall configurations.

Workaround

Use the details in our getting started guide to change your firewall settings.

Unable to Find client.ncconf

Sometimes a client may be unable to find the client.ncconf file while connecting to the cache. This happens when NCache directory (%NCHOME%) is not set.

Workaround

If %NCHOME% is not set, follow the steps below to set the environment variable for it:

Right-click on the Start button and select System.
In the right pane, click on Advanced System Settings.
In the System Properties window, go to the Advanced tab and click on the Environment Variables button.
In the Environment Variables window, under System Variables, click on New.
For Variable Name enter %NCHOME%.
For Variable Value enter C:\Program Files\NCache.
Click OK.
Now to update the system path in the same Environment Variables window, find the Path variable and click Edit.
In the Edit Environment Variable window, click New and add %NCHOME%\bin to the list. This makes sure that the tools are available globally.
Click OK to close each of the windows.

No server available to process request

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

Workaround

Make sure that the Client/Server port (at which NCache Service starts and accepts different client connections) is not blocked by a firewall. The 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 a firewall.

Error: "Unable to communicate with server node"

Workaround

See if your firewall is allowing the Client/Server and Cluster port. A cluster port is a port at which nodes in a cluster communicate. You can change the default value of these ports from NCache Management Center. If you have specified a port range in the NCache Management Center, unblock all ports in the 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:

Windows .NET 4.8: Alachisoft.NCache.Service.exe.config located in %NCHOME%\bin\service
Windows .NET: Alachisoft.NCache.Service.dll.config located in %NCHOME%\bin\service
Linux .NET: Alachisoft.NCache.Daemon.dll.config located in /opt/ncache/bin/service
Windows Java: Alachisoft.NCache.Service.dll.config located in %NCHOME%\bin\service
Linux Java: 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 of 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 the bulk of events is fired even in case the bulk count does not reach the EventBulkCount that the user has specified. The 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 the 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 the client-side.

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

Cache Connectivity

Note

Prerequisites for Cache Connectivity

Connect to Single Cache

Note

Connect to Multiple Caches

Connect to Cache Using CacheConnectionOptions

Note

Connect to Cache Using CacheConnectionOptions for Load Balancer

Note

Connect to Clustered and Client Cache

Note

Note

Connect to Cache with Security Credentials

Troubleshooting

Port is Not Accessible

Workaround

Unable to Find client.ncconf

Workaround

No server available to process request

Workaround

Unable to communicate with server node

Workaround

Client Socket Deadlock

Workaround

See Also

Contact Us