Getting Started

This page will help you get started with BlazingCache.

In order to use BlazingCache in a simple application you have to build up a client and put data in it.
If you are using Maven add the following dependency:

XML

<dependency>
   <groupId>org.blazingcache</groupId>
   <artifactId>blazingcache-jcache</artifactId>
   <version>VERSION</version>
</dependency>

Then you have to get a Cache object:

Java

import java.util.Properties;
import javax.cache.Cache;
import javax.cache.CacheManager;
import javax.cache.Caching;
import javax.cache.configuration.MutableConfiguration;
import javax.cache.spi.CachingProvider;

 public static void main(String ... args) {
        CachingProvider provider = Caching.getCachingProvider();
        Properties properties = new Properties();
        try (CacheManager cacheManager = provider.getCacheManager(provider.getDefaultURI(), provider.getDefaultClassLoader(), properties)) {
            MutableConfiguration<String, String> cacheConfiguration = new MutableConfiguration<>();
            Cache<String, String> cache = cacheManager.createCache("example", cacheConfiguration);
            cache.put("foo", "bar");
            String result = cache.get("foo");
            System.out.println("result:" + result);
        }
    }

This example will start the full stack of BlazingCache on your JVM (a client and a server) and it will let you "play" with all the JSR107 functions.

Distributed setup

A more interesting case is when you want to run a distributed setup: in this case you will need a standalone CacheServer running outside of you JVM.
The simplest way of achieving this i to download the BlazingCache package and start a server, this is quite simple, just follow these steps:

1. Download the latest binary package // Where can this be found => Add a link to the binary package, please.
2. Ensure to have a JDK 8 installed on your machine and that JAVA_HOME is configured
3. Create a directory:
   mkdir blazingcache
4. Unzip the package:
   cd blazingcache
   unzip blazingcache-*.zip
5. Start the server:
   bin/service start

The server will listen on localhost:1025 in plain mode (not SSL)

Now you need to change the example code in order to configure mode=static:

Java

import java.util.Properties;
import javax.cache.Cache;
import javax.cache.CacheManager;
import javax.cache.Caching;
import javax.cache.configuration.MutableConfiguration;
import javax.cache.spi.CachingProvider;

 public static void main(String ... args) {
        CachingProvider provider = Caching.getCachingProvider();
        Properties properties = new Properties();
        properties.put("blazingcache.mode","static");
        properties.put("blazingcache.jmx","false"); //default value
        properties.put("blazingcache.server.host","localhost"); // default value
        properties.put("blazingcache.server.port","1025"); // default value
        properties.put("blazingcache.server.ssl","false"); // default value
        try (CacheManager cacheManager = provider.getCacheManager(provider.getDefaultURI(), provider.getDefaultClassLoader(), properties)) {
            MutableConfiguration<String, String> cacheConfiguration = new MutableConfiguration<>();
            Cache<String, String> cache = cacheManager.createCache("example", cacheConfiguration);
            cache.put("foo", "bar");
            String result = cache.get("foo");
            System.out.println("result:" + result);
        }
    }

This example will work as before but you will see in server.log the connection from your client.

Using a separate server will let you share your data between clients.

High Availability

Another step is to replicate the server in order to achieve high availability. This is very simple, but you will need an Apache Zookeeper server running (in a real environment you will probably run at least three zookeeper servers).

In order to boot more that one server unzip the package in two directories and perform these steps:

1. Change the "mode" parameter from "singleserver" to "clustered" in conf/server.properties
2. In one of the two servers (if running on the same machine) change the "port" from 1025 to another (higher) value
3. Start the Zookeeper server on one machine. You can use for demo/testing purpose the provided script, but remember to use an official Zookeeper distribution on production:
   bin/service startzookeeper

By default the provided Zookeeper script will run ZK in standalone mode on localhost:1281

Your client will now look like this:

Java

import java.util.Properties;
import javax.cache.Cache;
import javax.cache.CacheManager;
import javax.cache.Caching;
import javax.cache.configuration.MutableConfiguration;
import javax.cache.spi.CachingProvider;

 public static void main(String ... args) {
        CachingProvider provider = Caching.getCachingProvider();
        Properties properties = new Properties();
        properties.put("blazingcache.mode","clustered");        
        properties.put("blazingcache.zookeeper.connectstring","localhost:1281");
        properties.put("blazingcache.zookeeper.sessiontimeout","40000");        
        properties.put("blazingcache.zookeeper.path","/blazingcache");           
        try (CacheManager cacheManager = provider.getCacheManager(provider.getDefaultURI(), provider.getDefaultClassLoader(), properties)) {
            MutableConfiguration<String, String> cacheConfiguration = new MutableConfiguration<>();
            Cache<String, String> cache = cacheManager.createCache("example", cacheConfiguration);
            cache.put("foo", "bar");
            String result = cache.get("foo");
            System.out.println("result:" + result);
        }
    }

Your client will now use Zookeeper for server discovery, then it will connect to the LEADER server.
If you shutdown the LEADER the client will reconnect automatically to the other server, which in turn will became the new LEADER.

Since version 1.12.0 you can start a CacheServer embedded into every client but just using blazingcache.mode="server".
This way you will be able to run any number of client without the need of running a CacheServer.
This setup is very useful for little clusters (2-3 machine at max).
Beware that in this mode every client will run a copy of the server and in turn will act as the cache coordinator.
In this modo every client must be able to connect to other peers and every client will open a TCP listening endpoint.

Java

import java.util.Properties;
import javax.cache.Cache;
import javax.cache.CacheManager;
import javax.cache.Caching;
import javax.cache.configuration.MutableConfiguration;
import javax.cache.spi.CachingProvider;

 public static void main(String ... args) {
        CachingProvider provider = Caching.getCachingProvider();
        Properties properties = new Properties();
        properties.put("blazingcache.mode","server");        
        properties.put("blazingcache.zookeeper.connectstring","localhost:1281");
        properties.put("blazingcache.zookeeper.sessiontimeout","40000");        
        properties.put("blazingcache.zookeeper.path","/blazingcache"); 
        properties.put("blazingcache.zookeeper.writeacls","false"); 
        properties.put("blazingcache.zookeeper.host","my-public-hostname"); 
        properties.put("blazingcache.zookeeper.port","7000"); 
        properties.put("blazingcache.zookeeper.ssl","false"); 
    
        try (CacheManager cacheManager = provider.getCacheManager(provider.getDefaultURI(), provider.getDefaultClassLoader(), properties)) {
            MutableConfiguration<String, String> cacheConfiguration = new MutableConfiguration<>();
            Cache<String, String> cache = cacheManager.createCache("example", cacheConfiguration);
            cache.put("foo", "bar");
            String result = cache.get("foo");
            System.out.println("result:" + result);
        }
    }