BRCache

BRCache
Developer(s)	Brandao
Initial release	April 21, 2015
Stable release	1.0 B2 / 26 January 2016; 10 years ago
Written in	Java
Engine
Operating system	Cross-platform
Platform	Java Virtual Machine
Type	Cache
License	Apache License 2.0
Website	brcache.brandao.org

Search BRCache on Amazon.

The BRCache is a general-purpose caching system written in Java. It is free and open-source software, licensed under an Apache open source license. It can be used embedded in an application, as a framework, or run in standalone mode.

The org.brandao.brcache package is the base of BRCache. In the package is the class Cache, which has mechanisms to storing and retrieving data.

Getting the BRCache

Getting the package

The BRCache team provides release bundles hosted on the SourceForge File Release System, in ZIP. Each release bundle contains JARs, documentation, source code, and other information. You can download releases of BRCache from the list at http://sourceforge.net/projects/brcache/files/.

Maven Repository Artifacts

The artifacts are produced under the org.brandao groupId.

brcache

Single artifact, necessary for handling the data in the cache.

The official repository is http://brcache.brandao.org/maven/2.

Overview

Write and read operations in the cache are made by the class org.brandao.brcache.Cache. Usually only one instance is required for an application, but not limited to just one.

Architecture

A cache is divided into three buffers of limited size. They are called nodes, index and date. Each buffer is divided into pages, and this is subdivided into blocks.

The node buffer is local for storing the nodes of the tree of the key. Its block size is fixed, 576 bytes. It has to use at least 9% of the total memory used by the cache. Not being less than 2304 bytes (4x576 bytes). The swap factor should be between 0.1 and 0.3. If the swap factor stays above or below the limit, you can leave the slow cache. The swap is made by page.

The index buffer is local for storing the index of the keys. Its block size is fixed, 82 bytes. It has to use at least 3% of the total memory used by the cache. Not being less than 328 bytes (4x82 bytes). The swap factor should be between 0.1 and 0.3. If the swap factor stays above or below the limit, you can leave the slow cache. The swap is made by page.

The data buffer is local for storing the values. Its block size is variable and can be configured. It has to use at least 88% of the total memory used by the cache. The swap factor should be between 0.1 and 0.3. If the swap factor stays above or below the limit, you can leave the slow cache. The swap is made by page.

The cache

A cache is represented by the class org.brandao.brcache.Cache. Usually only one instance is required for an application, but not limited to just one. Each cache instance needs a limited quantity of memory that can be configured.

public class Cache implements Serializable{
    
    public void putObject(String key, long maxAliveTime, Object item) 
	throws StorageException{...}

    public Object getObject(String key) throws RecoverException{...}

    public void put(String key, long maxAliveTime, InputStream inputData) 
	throws StorageException{...}

    public InputStream get(String key) throws RecoverException{...}
    
    public boolean remove(String key) throws RecoverException{...} 
    
    public long getCountRead(){...}

    public long getCountWrite(){...}

    public long getCountRemoved() {...}

    public long getCountReadData() {...}
    
    public long getCountWriteData() {...}

    public long getCountRemovedData() {...}
    
}

putObject(): Adds or overrides an entity in the cache.
getObject(): Retrieve an entity from the cache. If it does not exist, returns null.
put(): Adds or overrides an entity in the cache from a byte stream.
get(): Retrieves a byte stream from the cache. If it does not exist, returns null.
remove(): Remove an entity from the cache.
getCountRead(): Gets the number of recovered items.
getCountWrite(): Gets the number of stored items.
getCountRemoved(): Gets the number of items removed.
getCountReadData(): Gets the number of bytes recovered.
getCountWriteData(): Gets the number of stored bytes.
getCountRemovedData(): Gets the number of bytes removed

Storing items in the cache

Storing items in a cache can be done by the method putObject() or put(), and there is a limit to the size of the key and value.

The item can be removed after a certain time, if you inform the maxAliveTime. If maxAliveTime equals zero, the entry stays forever in the cache.

The method putObject() stores a particular object, but before storing, it is converted to a byte stream, that is to say, the object must implement the java.io.Serializable interface.

String key = "myKey";
String value = "Valor";
cache.putObject(key, 0, value);

The put() method stores a stream of bytes.

String key = "myKey";
String value = "Valor";

//convert object to byte stream.
ByteArrayOutputStream bout = new ByteArrayOutputStream();
ObjectOutputStream oout = new ObjectOutputStream(bout);
oout.writeObject(item);
oout.flush();

//stores the byte stream.
cache.put(key, 0, new ByteArrayInputStream(bout.toByteArray()));

Retrieving items from the cache

Recovering items from the cache can be done by the getObject or get methods. The method getObject gets the item data and converts them into an object.

String key = "myKey";
String value = (String)cache.getObject(key);

The method get returns the byte stream of the item. To get the object, you must convert the byte stream into an object.

String key = "myKey";
InputStream valueStream = cache.get(key);

ObjectInputStream in = new ObjectInputStream(valueStream);
String value = (String)in.readObject();

Removing items from the cache

Removing items from the cache can be done by the remove() method. If the item is removed from the cache, it will return true. Otherwise, it returns false.

String key = "myKey";
if(cache.remove(key)){
    System.out.println(“The item ” + key + “ was removed from the cache”).
}
else{
    System.out.println(“The item ” + key + “ does not exist in the cache”).
}

BRCache server

The BRCache server is a cache that allows storing key/value pairs. It can be used in any application. It supports storing in memory and on disk.

To start the server, execute the below command:

<java> -Xmx<mem> -cp brcache.jar org.brandao.brcache.server.Main

java: jvm.
mem: maximum memory allocation pool for a Java Virtual Machine. The value should be greater than the cache consumer.

Configuration

On startup, the BRCache attempts to read the brcache.conf file that should be located in the same server run folder. It must contain the following variables:

port: port that the server will listen on. The default value is 8084.
max_connections: maximum simultaneous connections that are allowed. The default value is 1024.
swapper_thread: number of swapper threads.
timeout_connection: timeout connection. The default value is 0.
reuse_address: allow reuse the allocated connections. The default value is false.
compress_stream: enable or disable data compression. The default value is false.
data_path: folder where the server will do the swap data when the memory limit is reached. The default value is /var/brcache.
nodes_buffer_size: node buffer size. The default value is 16m.
nodes_page_size: node buffer page size. The default value is 16k.
nodes_swap_factor: node swap factor. The default value is 0.3.
index_buffer_size: index buffer size. The default value is 1m.
index_page_size: index buffer page size. The default value is 16k.
index_swap_factor: index swap factor. The default value is 0.3.
data_buffer_size: data buffer size. The default value is 64m
data_page_size: data buffer page size. The default value is 16k.
data_block_size: data block size. The default value is 512 bytes.
data_swap_factor: data swap factor. The default value is 0.3.
write_buffer_size: write buffer size. The default value is 16k.
read_buffer_size: read buffer size. The default value is 16k.
max_size_entry: max size item in bytes. The default value is 1m.
max_size_key: max key size in bytes. The default value is 48.

Storage Command

The storage command is put. The syntax of it is:

put <key> <flags> <exptime> <size>\r\n
<data>\r\n
END\r\n

key: is the key associated with data.
flags: is an arbitrary 16-bit unsigned integer. It will be recovered with the value.
exptime: is expiration time. If it's 0, the item never expires.
size: is the number of bytes in the data without the delimiting \r\n.
data: is the data of the item. The length is defined in the size.

If the command succeeds, the server returns the message OK\r\n. Otherwise the server returns the error message.

Retrieval command

The retrieval command is get. The syntax of it is:

get <key>\r\n

key: is the key associated with data.

If the command succeeds, the server returns the message below. Otherwise the server returns the error message.

VALUE <key> <size> <flags>\r\n
<data>\r\n
END\r\n

key: is the key associated with data.
flags: is an arbitrary 16-bit unsigned integer informed in the storage command.
size: is the number of bytes in the data without the delimiting \r\n.
data: is the data of the item.

Deletion command

The deletion command is remove. The syntax of it is:

remove <key>\r\n

key: is the key associated with data.