Jolo

Short for jOOQ Loader. A utility library to add basic object-relation mapping to your jOOQ code.

How to Install

Artifacts are hosted on Maven's Central Repository:

Gradle

dependencies {
    compile 'tech.picnic.jolo:jolo:0.0.1'
}

Maven

<dependency>
    <groupId>tech.picnic.jolo</groupId>
    <artifactId>jolo</artifactId>
    <version>0.0.1</version>
</dependency>

Features

• Easy specification of relations between entities using a chaining API.
• Object instantiation using jOOQ's native "into" method; the loader can additionally call setters to instantiate relationships between entities.
• Performs foreign key checks to see whether the defined relationships make sense.
• Extra checks on field names of returned records to prevent loading fields from one table as fields of another (no implicit conversion of FOO.FIELD to BAR.FIELD).
• Supports circular references.
• Supports adding extra (non-table) fields to entities.

Limitations

• Only primary / foreign keys of (Java) type long are supported. We have no intention to support composite foreign keys for the time being. For keys of different types (e.g. String) we would accept pull requests, but only if this does not further complicate the interface of the library (no long type parameter lists).
• Relation mapping does not work yet for entities that are not based on a table in the DB schema.

Example usage

Let's assume we are working with the following table structure:

CREATE TABLE Dog (
  id bigserial PRIMARY KEY,
  name text,
  weight int
);

CREATE TABLE Flea (
  id bigserial PRIMARY KEY,
  dog_id bigint REFERENCES Dog,
  weight int
)

And in Java you have modelled your dogs and fleas using POJOs that are serialisable using standard jOOQ functionality:

class Dog {
  private long id;
  private String name;
  private int weight;
  private List<Flea> fleas;

  /* Getters and setters for ID, name & weight. */

  @Transient
  public List<Flea> getFleas() {
    return fleas;
  }

  public void setFleas(List<Flea> fleas) {
    this.fleas = fleas;
  }
}

class Flea {
  private long id;
  private int weight;

  /* Getters and setters. */
}

Using this library, you can specify how to instantiate the relationship between those POJOs (i.e., how to fill the fleas property of Dog):

LoaderFactory<Dog> createLoaderFactory() {
  var dog = new Entity<>(Tables.DOG, Dog.class);
  var flea = new Entity<>(Tables.FLEA, Flea.class);
  return LoaderFactory.create(dog)
      .oneToMany(dog, flea)
      .setManyLeft(Dog::setFleas)
      .build();
}

Then in the code that executes the query, you can use the loader to instantiate and link POJO classes:

class Repository {
  private static final LoaderFactory<Dog> LOADER_FACTORY = createLoaderFactory();

  private final DSLContext context;

  void dogLog() {
    List<Dog> dogs = context.select()
      .from(DOG)
      .leftJoin(FLEA)
      .on(FLEA.DOG_ID.eq(DOG.ID))
      .fetchInto(LOADER_FACTORY.newLoader())
      .get();

    for (Dog dog : dogs) {
      int fleaWeight = dog.getFleas().stream().mapToInt(Flea::getWeight).sum();
      LOG.info("%s is %.0f%% fleas",
               dog.getName(),
               fleaWeight * 100.0 / dog.getWeight());
    }
  }
}

Contributing

Contributions are welcome! Feel free to file an issue or open a pull request.

When submitting changes, please make every effort to follow existing conventions and style in order to keep the code as readable as possible. New code must be covered by tests. As a rule of thumb, overall test coverage should not decrease. (There are exceptions to this rule, e.g. when more code is deleted than added.)