The BlazingCache server is the process who coordinates clients.

The main purpose of this coordination is to propagate mutations (invalidations and updates) from one client to other clients. The coordinator is also in charge of handling distributed locks and in general to guarantee the consistency of the state of the clients.

If a client issues a fetch then is the server who will proxy the fetch request of the client to other clients, in order to find and up-to-date value for the requested entry.

Each clients keeps only a TCP connection open to the cache server, on the server side connections are managed using non blocking IO using Netty. There is no thread dedicated to specific clients and the protocol is totally asynchronous: this design lets a single cache server manage hundreds of clients without problems.

The server mantains in memory the list of keys known by each client and using this information it can route requests only to interested clients; this way the memory used by the cache server is minimal and notifications are sent only to useful clients reducing dramatically the network load.

The server takes care of the coordination of entry expiration, and so it has to keep in memory for each mortal entry the expected expiration deadline. Expiration uses a dedicated thread which runs at a configurable period of time.


You can start as many servers you want but actually only one, the leader, will work. Other servers will be in backup status and will replace the leader immediately in case of failure in order to keep the system up.

In fact without a live connection to a CacheServer the CacheClient keeps its local cache empty and blocks activities for every mutation to the entry set.

In production you will most likely be running at most two or three servers. It is optimal to have the hardware and software configuration of each server equal to each others, because in case of failover the backup server will immediately take on all the traffic of the previous leader.

Cache servers do not talk to each other, they only elect a leader using a Zookeeper ensemble.


In the standard binary package the configuration is stored in "conf/".
In order to apply new configuration you have to restart the service.
Usually you will update backup servers, restart it and then do the same to the leader, which in turn will become a backup.


  • **clustering.mode**: unique id of the task (java 64bit signed long).
    •  **singleserver** disables replication, no need for zookeeper, but client will need to be configured using the address of this server.
    •  **clustered**  enable replication, you will need a zookeeper ensemble, client will discover the leader from zookeeper.
  • ****:  Local address to listen for connection. This is the same name advertised on zookeeper for clients.
  • **server.port**: Local TCP port to listen on. Default value is 1025.
  • **server.ssl**: true/false. Enable/disable SSL.
  • **server.ssl.certificatefile**: Path of a PKCS12 file which contains the SSL certificate for the SSL endpoint. If not provided a self-signed certificate will be generated at every boot.
  • **server.ssl.certificatechainfile**: Path of the Certificate Chain File supporting the SSL certificate, it may be left blank.
  • **server.ssl.certificatefilepassword**: Password for the SSL certificate
  • **server.ssl.ciphers**: Limit the list of SSL Ciphers to use, leave blank to let the JVM + Netty decide for you.
  • **server.jmx**. Enable registration on JMX of the MBean providing server status values. Default value is true. 
  • **zk.address**: Zookeeper connection string (only for clustered mode). It defaults to localhost:1281. See Zookeeper docs for more info.
  • **zk.sessiontimeout**: Zookeeper initial session timeout. It defaults to 40000 (ms). See Zookeeper docs for more info.
  • **zk.path**: Base path of Zookeeper filesystem. It defaults to */blazingcache*. Usually you are not going to change this value.
  • **sharedsecret**: Shared secret that clients need to use to access the server, and so receive data from other clients or push data to them. It defaults to *blazingcache*. You **MUST** change this value in production.
  • **io.worker.threads**: Number of Netty worker threads. It default to 16 which we discovered to be a good value for any purpose. If you set io.worker.threads to 0 Netty will use its defaults.
  • **netty.callback.threads**: Size of the internal thread pool for handling callbacks on netty channels. It defaults to 64. If you set netty.callback.threads to 0 the system will use an unlimited thread pool.
  • **channelhandlers.threads**: Size of the internal thread pool for handling callbacks. It defaults to 64. If you set channelhandlers.threads to 0 the system will use an unlimited thread pool.