Overview

h2zero is an easy to use object relationship mapper (ORM) code generator for Java and MySQL.

Background - i.e. the one source of truth

After using (and sometimes abusing) various ORMs, the decision was made that rather than starting with the model and letting the model drive the database schema and interactions, to start with the database schema that would then drive the model.

When starting with the model, (and using annotations, and/or some hybrid SQL-like language), the generated code would work fine, the schema would be set up, and the hybrid-SQL would be made. Eventually there would be performance problems and you would then have to go in and try and replace the non-performing hybrid SQL with better SQL. Or you would have to re-annotate classes to force the underlying system to create the meaning that you would want. (i.e. the implicit meaning would) have to be made more explicit

When starting with the schema, the meaning is explicit, every SQL statement is explicit, and the model conforms to exactly what you require.

No..

  1. boring hand generation of POJOs to map to the database
  2. ugly and inefficient SQL queries
  3. exceptions (unless you want them)

The code that is generated does not change with each generation (unless of course you change the h2zero file). In fact - you could just use one of the plugins and generate it at build time

Yes..

  1. Automatically generated POJOs
  2. Finders for finding subsets of the table
  3. Updaters for updating subsets of the table
  4. Deleters for deleting subsets of the table
  5. Inserters for inserting subsets of the table
  6. Counters When you just want a simple count of the subset (or all) of the table
  7. Questions When you just want a simple boolean response to a question
  8. Validation to ensure that the majority of errors are caught before runtime

The little things

Beautiful code generation... Because:

  • spacing is important,
  • new-lines are important,
  • comments,
  • tabs,
  • ordering is important

it is probably the smallest of things. However the generated code, not only has to work, we believe that it also has to look the part as well. As they say "The cloth maketh the man".

If nothing changes... nothing changes

No more file changes for generation. If the h2zero file generation is the same, you won't see any file differences (unless you update to a newer version of h2zero that is) - we don't put dates, change-able comments or anything else in it

How do I change it?

We tell you what file was used to generate the code - we use the templar templating language, which is open source and easily modifiable.

Easy editing of the templar files. If you don't like the way that we generate the file, you are free to modify it any way that suits you. Let's be honest though, you are not looking for something which you can get into the code, and modify and all that malarky - so raise an issue on github and we will look into it for you.

Exceptions

Exceptions, darn those Exceptions. Whilst we based h2zero generation on the EJB model (and yes, people still use these things) - we felt that sometimes you just don't need to throw an exception if you already have an expectation of what you want. The classic example is the login page.

  1. User logs in with email address and password
  2. You try to find the user by email address and password
  3. Couldn't find it - EXCEPTION, EXCEPTION, EXCEPTION
  4. you can just choose to return null (by using the *Silent method signature) - in the above case this means that you couldn't find the user and happily display an error message, rather than littering your code with try/catch/finally code everywhere.

Key Concepts

For those that are looking to dive straight into the code, there are two simple key concepts that need to be understood within the h2zero framework. Throughout the documentation there is references made to:

the model
This is the plain old java object (POJO) which maps to a single row in a database table. They come in two flavours, namely 'regular' (the main usage) and 'constant' (for very narrow usage).
regular
A regular model - which contains all of the CRUD updates required for the SQL interaction
constant
A constant model - which does not interact with the database at all. The underlying values are contained within the database, but hard coded into the java classes for usage.
interactions
Interactions refer to any of the generated code that interacts with the database tables, this includes:
  • finders,
  • updaters,
  • deleters,
  • inserters,
  • counters, and
  • questions.

Background

There are so many object relational mappers (ORMs) out there that do what h2zero does. It isn't special, it just provides a link between your database and generates your Java code to be able to use it.

Unlike other ORMs, you have full control of the SQL that is generated. So, if you

  • use MySQL
  • use Java
  • optionally use tomcat (JSPs/Tag Libraries/Servlets)

Then this may be the ORM for you.

Unlike other ORMs, most (not all, but most) of the SQL must be hand-crafted by you, no horrible best-effort code generation, no horrific un-parseable SQL statements in the logs. Just pure SQL that was hand-crafted by you to get the best performance out of the database.

You have complete control over the SQL statements that are executed meaning that you can optimise your statements the way you want them, not the way that the generator thinks you should.

Your database, just the way that you designed it.

Requirements

  • Java
  • MySQL
  • c3p0
  • Ant, ~or~
  • Gradle, ~or~
  • Command Line Interface