| < Previous page | Next page > |
Getting Started Guide
Here are some basic steps you should follow to ensure a smooth installation, configuration, and use of NCache.
1. Install NCache on Cache Server and Remote Client Machines
Install NCache on all remote client and cache server machines. If you have a separate caching tier, you'll have remote clients. Otherwise, cache will be hosted on your application server.
You can install either 32-bit or 64-version of NCache. 64-bit cache servers work fine with 32-bit clients.
2. Configure Servers for Multiple Network Cards (optional)
If your cache servers (including your app servers if you're hosting cache on them) have multiple network cards, then you must bind NCache to a specific card. You need to specify the following in "Alachisoft.NCache.Service.exe.config" in "NCache/bin/service" folder:
<appSettings>
...
<add key="NCacheServer.BindToClusterIP" value="20.200.20.200" />
<add key="NCacheServer.BindToClientServerIP" value="20.200.20.200" />
...
</appSettings>
NOTE: Anytime you modify "Alachisoft.NCache.Service.exe.config", you must restart NCache Service. You can do this through following commands:
C:/Users/Administrator>net stop ncachesvc
C:/Users/Administrator>net start ncachesvc
You can also bind Client/Server communication to a different network card than the Clustering network card, if you have multiple network cards. Or, you can bind both to the same card (as shown above).
3. Open Firewall TCP Port for Clients (optional)
If there is a firewall between your remote clients and the cache servers, then you must open a TCP port (default 9800) for the remote clients to talk to the cache servers. If you want to change this from 9800 to another port, then you must make changes in all remote client and all cache server machines. On the remote clients, you need to change the "port" value in "client.ncconf" as following:
<configuration>
<ncache-server port = "9800" client-request-timeout = "90" connection-retries = "1" retry-interval = "0" connection-timeout = "5"/>
</configuration>
And, you need to change the "NCacheServer.Port" value in "Alachisoft.NCache.Service.exe.config" file located in "NCache/bin/service" folder on all cache servers as following:
<appSettings>
...
<add key="NCacheServer.Port" value="9800" />
...
</appSettings>
NOTE: Anytime you modify "Alachisoft.NCache.Service.exe.config", you must restart NCache Service (as described above).
All remote clients by default talk to NCache servers on TCP port 9800. So, if there is a firewall between the remote clients and the cache server, then you must open TCP port 9800 in your firewall.
4. Open Firewall TCP Port for Cache Cluster (optional)
If you have a situation where there is a firewall between the cache servers and the cluster must be formed across this firewall, then you must open at least two TCP ports (bi-directional) in this firewall. This port is the Cluster Port specified by you while creating a new clustered cache. For example:
Cluster Port: 7800
Port Range: 1
Open ports 7800. If Port Range is 2, then open 7800 and 7801.
5. Create New Clustered Cache
Run NCache Manager from ONLY ONE location (preferably from one of your cache servers), and create a new clustered cache. You can choose to create one of the following type of caches:
For starters, we recommend to create a Replicated Cache. Later on, you can decide whether a different caching topology meets your requirements better or not. For now, we want to go through the entire process quickly.
6. Test Cache Cluster from Statistics Window
Once you have created a clustered cache, you need to test to make it sure that it works fine. Here are the steps to test the cluster from within NCache Manager.
7. Remote Client Machines
NCache provides remote client management through NCache Manager. By right click on Client Nodes, context menu will appear having "Add Node" option as shown in figure. By using this option you can add and configure single or multiple client nodes in a clustered cache.
8. Ensure All Objects are Serializable
Whether you're using NCache for Java Sessions or for object caching, you must ensure that all Java objects are serializable. This is true even for those Java objects that you're storing in your Session. Here is how to ensure that:
import java.io.Serializable;
public class Customers implements Serializable
{
...
}
9. Defining Filters for Java Session Module
To ensure the correct caching of sessions, you must apply this filter as the first filter in your deployment descriptor. Filters are executed in the order they are defined in deployment descriptor.
Deployment descriptor is XML file named 'web.xml' located in the WEB-INF directory under the application root directory. The class file containing the filter implementation is 'com.alachisoft.ncache.web.sessionstate.NSessionStoreProvider '.
To create a filter, you must define it first under the <filter> tag and then provide a URL mapping for the filter using <filter-mapping> tag. The following filter configuration means that the filter will be applied to all the URLs in a web application.
<filter>
<filter-name> NCacheSessionProvider </filter-name>
<filter-class> com.alachisoft.ncache.web.sessionstate.NSessionStoreProvider </filter-class>
</filter>
<filter-mapping>
<filter-name> NCacheSessionProvider </filter-name>
<url-pattern> /* </url-pattern>
</filter-mapping>
NCache Session filter can be configured with a number of initialization parameters. The following are the required parameters.
<init-param>
<description> Name of running cache that will be used to persist session state.</description>
<param-name> cacheName </param-name>
<param-value> mycache </param-value>
</init-param>
<init-param>
<description> configPath is used to load the client.ncconf </description>
<param-name> configPath </param-name>
<param-value> %INSTALL_PATH%/config/ </param-value>
</init-param>
%INSTALL_PATH% is the location where NCache is installed.
Following is example of how the deployment descriptor should look like after defining the filter.
<session-config>
<session-timeout> 30 </session-timeout>
</session-config>
<filter>
<filter-name> NCacheSessionProvider </filter-name>
<filter-class> com.alachisoft.ncache.web.sessionstate.NSessionStoreProvider</filter-class>
<init-param>
<description> Name of running cache that will be used to persist session state.</description>
<param-name> cacheName </param-name>
<param-value> mycache </param-value>
</init-param>
<init-param>
<description> configPath is used to load the client.ncconf </description>
<param-name> configPath </param-name>
<param-value> C:/Program Files/NCache/config/ </param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name> NCacheSessionProvider </filter-name>
<url-pattern> /* </url-pattern>
</filter-mapping>
<welcome-file-list>
<welcome-file> index.jsp </welcome-file>
</welcome-file-list>
</web-app>
10. Deploying application
11. Configure Java Project for Object Caching
If you're using NCache for Java Sessions only, then you do not need to do anything here. However, if you're using NCache for object caching where you'll be making NCache API calls, then you need to do the following in your Java project.
1. Reference following files in your project:
• NCClient.jar
• NCacheSessionProvider.jar
• NCRuntime.jar
• NCSerialization.jar
• javassist.jar
2. Incude "javaReg.Properties" file into the CLASSPATH of your project.
3. Use import com.alachisoft.ncache.web.caching.*; in your project.
You can test NCache using the following code example:
Cache _cache = NCache.initializeCache("myCache");
_cache.add("Customer:David:1001", customer);
_cache.get("Customer:David:1001");
_cache.Dispose();
12. Run Application and Monitor from NCache Manager
You're now ready to run your application. Once you do, you can watch the cache performance from the Statistics window in NCache Manager. Below is an example:
 |