Morphium - Java Object Mapper and Caching Layer for MongoDB

NEW: Join us at SLACK

Morphium is a POJO Object mapper for Accessing Mongodb. Some of the main Features of Morphium:

• actively developed
• used by a number of projects (including holidayinsider.com)
• Transparent access to mongo db
• Transparent declarative (Annotation based) caching
• Annotation based definition of mappings
• Cluster Awareness
• Cache synchronization between cluster nodes
• Asynchronous and Buffered write access
• blazing fast Mongodb based Messaging - used for CacheSynchronization - with support for broadcast messages, that are only processed by one node (exclusive messages). Roundtrip in Production environment about 20ms!
• fluent interface for querying mongodb
• support for the mongodb aggrgator framework
• support for complex queries
• support inheritence and polymorphism
• support for javax.validation annotations
• lifecycle method of pojos
• Iterator support for iterating over large collections. Including threadsafe access and support for prefetching (V2.2.5)
• polymorphism support
• nearly every aspect of morphium can be replaced by own implementation (e.g. Query-Object, CacheImplementation...)
• Spport for References, including lazy loaded references
• Support for partial updated objects (when writing, only the changes of the object are transferred)
• Morphium is internally implemented asynchronous capable. That means, almost any operation you call via morphium can be executed asynchronously. If there is a AsyncOperaionListener that can be passed on as an argument to the function, you will receive the result via the callback, not directly as return value (or, when it is an update, you will get the exception or the sucess notification)

Morphium 3.0 overview

New MorphiumDriver API

With 3.0 we introduced the MorphiumDriver API into morphium. This abstracts the whole connection process to the driver layer. Everything is encapsulated - and due to this encapsulation, you can also connect to different things, not only Mongo.

there are different implementation of the MorphiumDriver interface already part of the project. There is the "default"-Driver, which uses the official Mongodb implementation to connect to mongo, then there are some Test Implementations of own Drivers (SingleConnectDriver, SingleConnectDriverThreadded and one Driver called MetaDriver) and an InMemoryDriver, which is really helpful when testing things.

In future, there will be more drivers in different projects, like here. This is a MorphiumDriver implementation for InfluxDB.

Quick Start

before accessing mongo via morphium, you need to configure morphium. this is done by preparing a MorphiumConfig Object:

  MorphiumConfig cfg = new MorphiumConfig();
  cfg.setDatabase("testdb");
  cfg.addHost("localhost", 27017);

you can also configure morphium using properties: new MorphiumConfig(properties); or a json-String: MorphiumConfig cfg = MorphiumConfig.createFromJson(json);

After that, you just need to instancieate morphium:

  Morphium m=new Morphium(cfg);

then you are good to go:

  Query<MyEntity> q=m.createQueryFor(MyEntity.class).f("a_field").eq("a value");
  List<MyEntity> lst=q.asList();
  MyEntity ent=q.get();
  ...
  m.store(ent);

Defining an Entity is quite simple as well:

  @Entity(translateCamelCase = true)
  @Cache
  public class MyEntity {
    @Id
    private ObjectId myId; 

    private String aField;

    private EmbeddedObject emb;

    @Reference
    private MyEntity otherEntity;

   ...
  }

  @Embedded
  public class EmbeddedObject {
   ...
  }

All entities need to have an @Id field. If the type is org.bson.types.ObjectId, it will be created by mongo, if not - you need to take care of that. References only work to other entities (of course). You can also use Maps, Lists or Arrays, all may also include other Entities or Embedded types.

Use enum instead of strings for queries

As using strings to query your object might be a bit error prone, you also can use enums instead of field name strings:

   Query<MyEntity> q=m.createQueryFor(MyEntity.class).f(MyEntity.Fields.aField).eq("a value");

of course, these enums need to be created. have a look at https://github.com/sboesebeck/intelliJGenPropertyEnumsPlugin for a plugin for generating those automatically in our example, the result would look like this:

  @Entity(translateCamelCase = true)
  @Cache
  public class MyEntity {
    @Id
    private ObjectId myId; 

    private String aField;

    private EmbeddedObject emb;

    @Reference
    private MyEntity otherEntity;
    ...
    public enum Fields { myId, aField, emb, otherEntity }

  }

  @Embedded
  public class EmbeddedObject {
   ...
  }

This is a very short glance at all the features of Morphium!

For more information take a closer look at the wiki or read the detailled documentation here

Have fun,

Stephan