Morphium

Morphium - Java Object Mapper and Caching Layer for MongoDB


Project maintained by sboesebeck Hosted on GitHub Pages — Theme by mattgraham

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:

take a look at the wiki for more info or read the detailled documentation here

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

PS: some words about Mongodb 3.0 and WiredTiger

  • 3.0 Ready - V2.2.x works fine with mongodb 3.0, storageEnging wiredTiger is a bit slower than the standard engine in morphiums test suite. It seems like the performance on WiredTiger is a bit slower due to the access pattern morphiums test suite uses. In prooductional environments performance is as expected. Eg. writing performance is way better with wired tiger. Probably it is possible to configure WT to work as performant as MMAPV1 for morphium's test suite, but that is actually not important!
  • When using WiredTiger storage engine, make sure the settings are configured to your needs, otherwise performance might suffer