Cache Management Operations on Cache

The NCache Management API is a set of programmable method calls that enable the user to perform basic management operations on OutProc caches without using either the NCache Management Center or Command Line Tools. This Management API is usually self-sufficient when executing a request.

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: CacheConnection, CacheManager, CacheConnectionOptions, CacheClientConnectivityChanged, CacheClientConnectivityChangedCallback, ClientInfo, ConnectedClientList, GetCacheHealth, StartCache, StopCache, GetCache.

Start Cache Using API Calls

The StartCache method enables the user to start an OutProc cache on the specified server.

Start Cache

The cache starts using the StartCache method by using the server IP and cache name. In this example, the user must specify the cache and server IP to start a node.

// Specify cache name and server info
string cacheName = "demoCache";
string serverIp = "20.200.20.40";

// Provide server info to CacheConnection
var connection = new CacheConnection(serverIp);

// Use CacheConnection to start cache
CacheManager.StartCache(cacheName, connection);

// Initialize cache name and server info
String cacheName = "demoCache";
String serverIp = "20.200.20.40";

// Provide server info to CacheConnection
CacheConnection connection = new CacheConnection(serverIP, port);

// Use CacheConnection to start cache
CacheManager.startCache(cacheName, connection);
System.out.println("Cache started successfully.");

// Precondition: Cache has been registered but not initialized.
string cacheName = "mycache";
string serverName = "...."; // specify the server where cache is registered

CacheManager.StartCache(cacheName, serverName);

Start Cache with Security Enabled

If management level security is enabled, the user needs to provide the user credentials to perform any management operations on the cache. The StartCache method lets you start a cache with user credentials. The following example starts a cache with security enabled on it.

.NET
Java

// Provide user credentials to CacheConnection
connection.UserCredentials = new Credentials("your-username", "your-password");

// Start cache with the security credentials
CacheManager.StartCache(cacheName, connection);

// Initialize security credentials
String userName = "john_smith";
String password = "12345";

// Initialize cache name and server info
String cacheName = "demoCache";

// Provide user credentials to CacheConnection
Credentials credentials = new Credentials(userName, password);
CacheConnection connection = new CacheConnection(serverIP, port);
connection.setUserCredentials(credentials);

// Start cache with security enabled
CacheManager.startCache(cacheName, connection);
System.out.println("Cache started successfully with security credentials.");

Stop Cache Using API Calls

The StopCache method stops a cache on a particular server. If users don't specify a server, the method reads information from the client configuration file. If called from the client node, the first server listed in the client configuration file associated with the cache stops. You can stop a cache with enabled as well as disabled security. Moreover, the cache may also stop gracefully by setting the gracefullyShutDownNode flag as true.

Stop Cache

This example stops the cache on an already started node. The cache name and server IP to stop on a given node needs to be specified.

// Use CacheConnection to stop cache
CacheManager.StopCache(cacheName, connection);

// Stop cache
CacheManager.stopCache(cacheName, connection, true);
System.out.println("Cache stopped successfully.");

CacheManager.StopCache(cacheName, serverName);

Stop Cache With Enabled Security

The following example shows how to stop a cache on a particular server with enabled security by providing it with user credentials.

.NET
Java

// Provide user credentials to CacheConnection
connection.UserCredentials = new Credentials("your-username", "your-password");

// Stop cache with the security credentials
CacheManager.StopCache(cacheName, connection);

// Provide user credentials to CacheConnection
Credentials credentials = new Credentials(userName, password);
connection.setUserCredentials(credentials);

// Stop cache with security credentials
CacheManager.stopCache(cacheName, connection, true);
System.out.println("Cache stopped successfully with security enabled.");

Viewing Cache Status Using API calls

Note

Make sure that you have included the following namespace in your program: Alachisoft.NCache.Runtime.CacheManagement.

The GetCacheHealth method enables users to view the cache server node status. This method call returns a CacheHealth object against every call. You can specify the cache name, the server node, and the management port to get the cache health information. The following example gets the cache-health for the cache demoCache, registered on the server node specified, and listens on port number 9803.

// Get cache health on the specified node
CacheHealth cacheHealth = CacheManager.GetCacheHealth(cacheName, connection);

Console.WriteLine($"Cache : {cacheHealth.CacheName}\nNode : {serverIp}\nTopology : {cacheHealth.Topology}\nNode Status : {cacheHealth.Status}");

// get cache health of the specified cache
CacheHealth cacheHealth = new CacheHealth();
cacheHealth.setCacheName(cacheName);
CacheStatus status = cacheHealth.getStatus();

CacheHealth cacheHealth = CacheManager.GetCacheHealth(cacheName);

Monitoring Clients Connected to Cache

NCache provides the feature of enabling Client Activity Events. Using these events, each client connects to a clustered cache and can subscribe to notify about the connect/disconnect events of other clients. Each client can also specify a process-level custom identifier that returns to the subscriber based on the client's requirements, it can connect to or disconnect from a clustered cache. Client Activity Events fire when a client connects to or disconnects from a specified cache. These events are registered against the specified cache and are handled in a user-defined callback method.

Connect to Cache

The AppName is a process-level unique identifier that can be assigned at the time of cache connection. For this purpose, before connecting to the cache, create an instance of CacheConnectionOptions and assign a custom identifier string to its AppName property. Thus, if this client connects or disconnects, the callbacks of all the clients who subscribed to the client will get this AppName in their ClientInfo instance.

// Create an instance of CacheConnectionOptions
var options = new CacheConnectionOptions();

// Assign the custom identifier
options.AppName = "MyApp";

// Connect to cache with custom AppName property
ICache cache = CacheManager.GetCache(cacheName, options);

// Create an instance of CacheConnectionOptions
CacheConnectionOptions options = new CacheConnectionOptions();

// Assign the custom identifier
options.setAppName("MyApp");

// Connect to cache with custom appName property
cache = CacheManager.getCache(cacheName, options);
System.out.println("Cache connected successfully");

string cacheName = "myPartitionedCache";

CacheInitParams initParams = new CacheInitParams();
initParams.AppName = "AssignedAppName"; // assign custom identifier

// initialize cache with custom AppName property
Cache cache = NCache.InitializeCache(cacheName, initParams);

Create Event Callback Method

The callback method is user-defined and is called once the clients are connected/disconnected from the cache. The method is registered against the CacheClientConnectivityChanged event property of the CacheClientConnectivityChangedCallback type in a specific cache. Hence, the method created should match the signature of the delegate:

public delegate void CacheClientConnectivityChangedCallback(string cacheId, ClientInfo client);

The created method contains the following parameters:

// User defined event callback method
static void MyClientConnectivityCallback(string cacheName, ClientInfo clientInfo)
{
    // Handle event
}

public interface cacheClientConnectivityChangedCallback {
String cacheName = "demoCache";

void invoke(String cacheName, ClientInfo clientInfo);

static void myClientConnectivityStatus(String cacheName, ClientInfo clientInfo)
}

public delegate void CacheClientConnectivityChangedCallback(string cacheId, ClientInfo client, ConnectivityStatus status);

The method created contains the following parameters:

// user defined event callback method
static void MyClientConnectivityCallback(string cacheName, ClientInfo clientInfo, ConnectivityStatus status)
{
    // handle event
}

Parameters	Description
`cacheName`	Name of the cache with which the clients are connected or disconnected. This acts as the sender of the event.
`clientInfo`	An object of the ClientInfo class containing information regarding the client which caused the event to fire.

Client Info Class

Member	Description
`AppName`	User assigned, process-level, unique identifier.
`ClientID`	Unique ID of client.
`IPAddress`	IP through which the client is connected.
`MacAddress`	Mac address of the client.
`PhysicalCores`	Available physical cores of the client.
`LogicalCores`	Available logical cores of the client.
`ProcessID`	Process ID of the client.
`MachineName`	Machine name of the client.
`Status`	The connectivity status of the cache client.
`ClientVersion`	The version of the cache client.
`IsDotNetCore`	Flag to check whether the client is .NET Core or not.
`Memory`	Available memory of the client.
`Operating System`	The operating system used by the client.

Register Event

The method is registered by appending it to the CacheClientConnectivityChanged property as an event callback. This enables the client to listen for connect/disconnect events of other clients. If another client connects to or disconnects from the specified cache, the callback method is called.

// Register method to event
cache.MessagingService.CacheClientConnectivityChanged += MyClientConnectivityCallback;

cache.getNotificationService().addCacheConnectivityChangedListener(new CacheClientConnectivityChangedImpl());

// register method to event
cache.CacheClientConnectivityChanged += MyClientConnectivityCallback;

Monitor Client Info of Connected Clients

The ClientInfo of each connected client is available locally in the form of the cache.ClientInfo property.

View List of Connected Clients

To get information on all the clients connected to the cache on demand, use the ConnectedClientList property on the cache as:

// Connect to cache with custom AppName property
ICache cache = CacheManager.GetCache(cacheName, options);

// Get list of all connected clients
IList<ClientInfo> connectedClients = cache.ConnectedClientList;

Console.WriteLine($"Following are the clients connected to '{cacheName}':");
foreach(ClientInfo clientInfo in connectedClients)
{
    Console.WriteLine($"Client ID : {clientInfo.ClientID}");
}

List<ClientInfo> connectedClients = cache.getConnectedClientList();
    for (var clientInfo : connectedClients){
        System.out.println("Client ID: " + clientInfo.getClientID());
    }

IList<ClientInfo> connectedClients = cache.GetConnectedClientsList();