Chameleon is a JPA and MongoDB mapping library based on Hibernate and MongoDB Java Driver.
image:chameleon-logo.jpg[logo, 180, 120]
== JPA and MongoDB JPA (Jarkata Persistence API) is an SQL persistence contract aiming to bridge the gap between Java OOP (Object Oriented Programming) paradigm and relational database model. Hibernate library as the reference implementation of JPA is the de facto ORM (Object Relational Mapping) framework in which Java developer could interact with POJOs whereas ORM library takes care of boilerplate JDBC processing automatically.
MongoDB is a document NoSQL database, so seemingly JPA could not be applied directly, though the similar ORM spirit is still highly attractive to Java developers. Furthermore, MongoDB provides many features aligning with SQL databases (e.g. transaction, table joining simulation by view, etc.), so it seems a natural candidate to enjoy some benefits of ORM framework. Let us call it OMM (Object MongoDB Mapping) then.
=== Existing Open Source Libraries (active or not) It is not surprising that Hibernate once started an ambitious project to generalize Hibernate ORM features to all NoSQL databases. They call it https://github.com/hibernate/hibernate-ogm[Hibernate OGM] (Object Grid Mapping) as a big umbrella including Infinitispan, MongoDB, Neo4j, etc. However, it lacks some basic JPA features (e.g. Criteria and Filter) and ceased to be actively maintained any more. It is based on outdated Hibernate v5 core library models. Given the leap of faith of Hibernate v6 release, it is extremely challenging to revive it by integrating with v6's new query model, if possible.
Spring Data MongoDB (https://spring.io/projects/spring-data-mongodb) is a good choice for CRUD tasks, but it is a sibling project to Spring Data JPA, not a super set, thus lacking many important JPA features. For instance:
There used to be lesser known libraries aiming Mongodb mapping exclusively every now and again, but usually they are not actively maintained and phased out quickly.
== Chameleon: a new OMM library The author of this library is an experienced Hibernate contributor and participated actively in both v5 and v6 development. He humbly proposed a new OMM idea and this github project is the end result. The idea is simple and boils down to the following principles:
=== Implementation Details Since Hibernate v6, a unified SQM (Semantic Query Model) was created for both JP-QL and Criteria. It is not only an elegant tech design but also streamlines vendor specific SQL or NoSQL statement generation. In Chameleon, we could easily create parameterized Mongodb Bson command string ready to be run by Mongodb java driver. The virtual JDBC driver will pass the JSON string instead of SQL between Hibernate and Mongodb server. No need to overwrite or bypass Hibernate's core workflow for vendor specific SQL rendering is a standardized core feature of Hibernate, and ultimately Hibernate sits on top of JDBC layer invariably. Our "Virtual JDBC Driver" will act as an adapter between JDBC contract and MongoDB, so the customization is outside of Hibernate's scope.
=== Some Caveats Obviously we can't anticipate all JPA features (entity class and JPA annotations, JP-QL or HQL statements) has one-to-one counterpart in MongoDB, but luckily MongoDB provides counterparts or simulation to great extent, e.g.:
$lookup and $unwind stages of aggregate pipeline)== Mongodb Integration Unit Testing
A locally running MongoDB server should have been running (at the default port of 27017).
Default connection string is mongodb://localhost/chameleon-test.
Currently all the collections in the testing database will be dropped before unit testing case is run.