Getting Started

Mache is designed to work in two main ways:

• Embedded and instantiated within your Java programs
• As a standalone REST service that expects to receive and persists values in the cache as Json documents (this allows Mache to work with any language stack for which there is a REST client api).

Instantiating your first mache

Mache makes extensive use of the builder pattern. Each of the platform-specific plugins (i.e. messaging, or databases), provide their own specific parts of the builder to enable custom configuration for each plugin. Broadly speaking, the procedure to embed Mache within your application is as follows:

1. Add mache-core.jar to the classpath
2. Add the chosen in memory cache provider jar to the classpath; mache-caffeine.jar, mache-guava.jar or mache-chroniclemap.jar
3. Add the chosen data store provider jar to the classpath; mache-cassandra.jar, mache-couchbase.jar or mache-mongo.jar
4. If you require eventing, add mache-observable.jar to the classpath, then add the suitable messaging provider; mache-activemq.jar, mache-kafka.jar or mache-rabbit.jar

The released Mache artifacts are housed at jcenter, so for instance if you wanted a Mache backed by Cassandra leveraging ActiveMQ for the eventing, you will require the following in your build.gradle:

repositories {
    jcenter()
}
dependencies {
  compile 'com.excelian.mache:mache-core:0.6.1'
  compile 'com.excelian.mache:mache-cassandra:0.6.1'
  compile 'com.excelian.mache:mache-observable:0.6.1'
  compile 'com.excelian.mache:mache-activemq:0.6.1'

Once you have the appropriate jars in your classpath you can then construct a Mache using the builder interface. This will present you with appropriate choices given the service providers you have installed. Examples of how these are constructed can be found in the mache-example component

• mache-example/src/examples/java/com/excelian/mache/examples/cassandra/CassandraExample.java
• mache-example/src/examples/java/com/excelian/mache/examples/couchbase/CouchbaseExample.java
• mache-example/src/examples/java/com/excelian/mache/examples/mongo/MongoExample.java

End-to-end example code

The following example will instantiate a Mache instance using the builder, and then use it to store TestEntity instances. To compile the following example, the following Mache dependencies will be required:

• mache-core
• mache-caffeine
• mache-mongo

@Document
public static class TestEntity {
    @Id
    String pkString;
    
    private int firstInt = 1;
    
    @Field(value = "differentName")
    private double aDouble = 1.0;
    
    @Indexed
    private String aString = "some-other-attribute";
    
    public TestEntity(String pkString) {
        this.pkString = pkString;
    }
    
    public static void main(String [] args){
        final String keySpace = "my_mongo_keyspace_name";        
        Mache<String, TestEntity> mache = mache(String.class, TestEntity.class)
                        .cachedBy(caffeine())
                        .storedIn(mongodb()
                                .withConnectionContext(mongoConnectionContext(new ServerAddress("1.2.3.4", 27017)))
                                .withDatabase(keySpace)
                                .withSchemaOptions(SchemaOptions.CREATE_AND_DROP_SCHEMA)
                                .build())
                        .withNoMessaging()
                        .macheUp()
        mache.put("test-1", new TestEntity("some-value-to-store"));
        TestEntity retrieved = mache.get("test-1");
        assertEquals("some-value-to-store", retrieved.pkString);
    }
}