RelMongo | Java relationship-enabled domain model persistence framework for MongoDB

View project on GitHub

the RelMongo project logo

License badge Maven badge Build badge Coverage badge GitHub release (latest by date) Join the chat at https://gitter.im/relmongo/general

The RelMongo Java framework provides relationships mapping of MongoDB domain model objects. The framework provides annotations like OneToMany, OneToOne and ManyToOne as an alternative for DBRef and allows cascade operations and lazy loading. RelMongo uses Spring data mongodb and manual references which make lookup aggregations work properly and overcomes DBRef limitations.

Features

  • @EnableRelMongo to enable RelMongo engine
  • @OneToMany annotation to address 1..N relations
  • @OneToOne annotation to address 1..1 relations
  • Two fetching methods ( LAZY and EAGER)
  • Cascading operations
  • Bidirectional mapping using the mappedBy attribute

To get more details please see the release notes.

Wiki

Take a tour in the RelMongo wiki

Binaries

  • Maven
     <dependency>
        <groupId>io.github.kaiso.relmongo</groupId>
        <artifactId>relmongo</artifactId>
        <version>x.y.z</version>
     </dependency>
    

    Compatibility Matrix

See compatibility on wiki

Usage

RelMongo is very simple to use.
given two concepts with “one to *” relation

  __________________                         __________________
 |    Person        |                       |    Car           |
 |__________________| 1                  *  |__________________|
 |  name (string)   |---------------------->|   ....           |
 |  cars (list )    |                       |                  |
 |                  |                       |                  |
 |__________________|                       |__________________|

on your Person mongo entity simply add the following annotations from RelMongo :

    @OneToMany(fetch=FetchType.EAGER, cascade = CascadeType.PERSIST)
    @JoinProperty(name="cars")
    private List<Car> cars;

and on your Spring App config class simply add @EnableRelMongo annotation:

    ... Other Annotations
    @EnableRelMongo
    public Class AppConfig
    

test your code :

        Car car = new Car();
        car.setColor(Color.BLUE);
        String manufacturer = "BMW";
        car.setManufacturer(manufacturer);
        Person person = new Person();
        person.setName("person");
        person.setEmail("person@mail.com");
        person.setCars(Arrays.asList(new Car[] {car}));
        repository.save(person);
        Optional<Person> retreivedPerson = repository.findById(person.getId().toString());
        assertFalse(retreivedPerson.get().getCars().isEmpty());
        assertTrue(retreivedPerson.get().getCars().get(0).getColor().equals(Color.BLUE));
        

database layout when executing this test :

  • cars collection :
    {
      _id : ObjectId(5afaff0e2557db3a140d0f85),
      manufacturer : BMW,
      color : BLUE
    }
    
  • persons collection
    {
      _id : ObjectId(5afaff0e2557db3a140d0f86),
      name : person,
      email : person@mail.com,
      cars : [ 
          {
              _id : ObjectId(5afaff0e2557db3a140d0f85)
              _relmongo_target: cars
          }
      ]
    }
    

    Strengths

  • Based on Spring framework and derivatives
  • Simple to use
  • Ready to use on existing database with few changes and in many cases with no changes
  • Bidirectional mapping

    Notes

  • RelMongo may be an alternative for DBREF which allow to use $lookup querries in mongodb while it is not possible with DBREF.
  • MongoDB is a document oriented database and is not suitable for relations, if you are using relations massively you may have a design or technical choice problems.
  • RelMongo does not garantee integrity in the database since it is not implemented by MongoDB

LICENSE

© Copyright 2020 Kais OMRI.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.