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);
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);
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);
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:
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);
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);
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.
See Also
.NET: Alachisoft.NCache.Client namespace.
Java: com.alachisoft.ncache.client namespace.
Node.js: Cache class.
Python: ncache.client class.