Jdbi: Document SqlObject mixins and how to use them

[Shujito]

The lack of documentation on that makes me wonder

[qualidafial]

Hi @Shujito,

A mixin is an interface that you can implement/extend in your SQL Object types, to add extra methods to your SQL object. There are two mixins, GetHandle, and Transactional.

GetHandle provides a single method Handle getHandle(). If you have a more complicated query than can be accomplished with annotations (e.g. multi-table joins with folds), then implement/extend GetHandle, and make your SQL method a concrete/default method. Inside the method you can call getHandle() to get the Handle associated with the SQL object.

interface ContactDao extends GetHandle {
  default List<Contact> getFullContacts() {
    return getHandle().createQuery(
        "select * from contact c left join phones p on c.id = p.contactId")
        .fold(new LinkedHashMap<Integer,Contact>(), (map, rs, ctx) -> {
          // etc
        })
        .values()
        .stream()
        .collect(toList());
}

Transactional provides several methods for managing transactions:

interface ContactDao extends Transactional {
  default void createFullContact(Contact contact) {
    begin();
    try {
      int contactId = createContact(contact.getName());
      createPhones(contact.getPhones());
      commit();
    }
    catch (Exception e) {
      rollback();
    }
  }

  @SqlUpdate("insert into contact(id, name) values (nextval('contact_seq'), :name)")
  @GetGeneratedKeys
  int createContact(@BindBean Contact contact);

  @SqlBatch("insert into phone(id, contact_id, phone_type, phone_number) " +
      "values (nextval('phone_seq'), :contactId, :phoneType, :phoneNumber)")
  void createPhones(@BindBean List<Phone> phones);
}

[Shujito]

So, with these then I can query for more complex objects.
For this example here I can get contacts along with as many phones they have, right?

[qualidafial]

That's the idea, yes. It all depends on how you formulate your query though.

[Shujito]

That makes it all clear now, I'll abuse this feature as soon as I see the need of it.
It'd be good to fill in here by the way: http://jdbi.org/sql_object_mixins/
Thanks

[qualidafial]

Tracked in #802