From dca6249667b7f009efc34f775e80d3704fff153d Mon Sep 17 00:00:00 2001 From: moparisthebest Date: Mon, 19 Jun 2017 23:50:59 -0400 Subject: [PATCH] Add first go at readme --- readme.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 readme.md diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..a6d9f7c --- /dev/null +++ b/readme.md @@ -0,0 +1,116 @@ +JdbcMapper is an ORM (Object Relational Mapper) that enables you to write normal SQL queries and use them to select +POJOs (Plain Old Java Objects) from the database in different types of collections quickly and easily. Type safety is +enforced throughout so neither casting nor ignoring warnings is required. + +There are 2 different approaches to accomplish this. JdbcMapper generates code at compile time, QueryMapper does +everything at runtime. + +Why +--- + +The java.sql API is horrible, ResultSet.wasNull() ?, enough said. Hibernate is black magic that generates some truly +awful SQL queries. Everything in between insists on writing your queries and/or forcing you to fully annotate all your +POJOs with information on how to map them from SQL, making them some combination of too verbose, too slow, or too much +unknown magic. + +Goals +----- + +1. Write as little code as possible +2. Have it run as fast as possible +3. Have it check and error out on everything it possibly can at compile time +4. Be runnable and testable inside or outside of containers easily +5. No surprises, as little magic as possible + +Column to Object Mapping +------------------------ + +todo: explain how individual columns are mapped to simple objects + +Row to Object Mapping +--------------------- + +todo: explain how rows are mapped to POJOs + +JdbcMapper +---------- + +Write an interface or abstract class with methods that make sense for accessing your database, annotate the methods with +SQL, and on compilation an annotation processor will generate the required java.sql API code to execute your query and +return what you wanted. This code is guaranteed to be the fastest code possible because hand written code would look +the same, just more error prone and harder to maintain. The annotation processor also checks that the SQL queries are +valid, have all the right bind parameters, and can bind the result columns to all the correct fields on the result object. +If anything is wrong it's a compile error pointing you to the exact problem. + +Example: + +``` +@JdbcMapper.Mapper(jndiName = "java:/comp/env/jdbc/testPool") // omit jndiName and you must send in a java.sql.Connection +public interface PersonDAO extends Closeable { // Closeable is optional but must have a 'void close()' method to use cachePreparedStatements or jndiName + + @JdbcMapper.SQL("CREATE TABLE person (person_no NUMERIC, first_name VARCHAR(40), last_name VARCHAR(40), birth_date TIMESTAMP)") + void createTablePerson(); + + @JdbcMapper.SQL("INSERT INTO person (person_no, birth_date, last_name, first_name) VALUES ({personNo}, {birthDate}, {firstName}, {lastName})") + int insertPerson(long personNo, Date birthDate, String firstName, String lastName); + + @JdbcMapper.SQL("UPDATE person SET first_name = {firstName} WHERE person_no = {personNo}") + int setFirstName(String firstName, long personNo); // returning int will return number of rows modified, can also return void + + @JdbcMapper.SQL("SELECT first_name FROM person WHERE person_no = {personNo}") + String getFirstName(long personNo) throws SQLException; // can map directly to simple types + + @JdbcMapper.SQL("SELECT person_no, first_name, last_name, birth_date FROM person WHERE person_no = {personNo}") + Person getPerson(long personNo) throws SQLException; // or multiple fields, set methods, or constructor parameters on a POJO + + @JdbcMapper.SQL("SELECT person_no, first_name, last_name, birth_date FROM person WHERE last_name = {lastName}") + List getPeople(String lastName) throws SQLException; // all rows in any Collection (like Set, LinkedList etc), T[], ResultSetIterable or Stream (java8+) works too +} + +// code: +try(PersonDAO personDao = JdbcMapperFactory.create(PersonDAO.class)) { + personDao.createTablePerson(); + System.out.println(personDao.insertPerson(0, null, "First", "Person")); // 1 + System.out.println(personDao.insertPerson(1, null, "First", "Person")); // 1 + System.out.println(personDao.setFirstName("Second", 1)); // 1 + + System.out.println(personDao.getFirstName(0)); // First + System.out.println(personDao.getFirstName(1)); // Second + + System.out.println(personDao.getPerson(0)); // Person{personNo=0,birthDate=null,firstName=First,lastName=Person} + System.out.println(personDao.getPerson(1)); // Person{personNo=1,birthDate=null,firstName=Second,lastName=Person} + + System.out.println(personDao.getPeople("Person")); // [Person{personNo=0,birthDate=null,firstName=First,lastName=Person}, Person{personNo=1,birthDate=null,firstName=Second,lastName=Person}] +} +``` + +QueryMapper +----------- + +Need to generate SQL dynamically or just execute some queries quickly and easily? Mapping is done using reflection in +ResultSetMapper or code is dynamically generated, compiled, instantiated, and cached at runtime to do the mapping using +CompilingResultSetMapper. + +Example: + +``` +// CompilingResultSetMapper is an alternative to ResultSetMapper, default is ResultSetMapper +try(QueryMapper qm = new QueryMapper("java:/comp/env/jdbc/testPool", new ResultSetMapper())) { // or send in java.sql.Connection + // executeUpdate returns int + qm.executeUpdate("CREATE TABLE person (person_no NUMERIC, first_name VARCHAR(40), last_name VARCHAR(40), birth_date TIMESTAMP)"); + System.out.println(qm.executeUpdate("INSERT INTO person (person_no, birth_date, last_name, first_name) VALUES (?, ?, ?, ?)", 0, null, "First", "Person")); // 1 + System.out.println(qm.executeUpdate("INSERT INTO person (person_no, birth_date, last_name, first_name) VALUES (?, ?, ?, ?)", 1, null, "First", "Person")); // 1 + System.out.println(qm.executeUpdate("UPDATE person SET first_name = ? WHERE person_no = ?", "Second", 1)); // 1 + + // can map directly to simple types + System.out.println(qm.toObject("SELECT first_name FROM person WHERE person_no = ?", String.class, 0)); // First + System.out.println(qm.toObject("SELECT first_name FROM person WHERE person_no = ?", String.class, 1)); // Second + + // or multiple fields, set methods, or constructor parameters on a POJO + System.out.println(qm.toObject("SELECT person_no, first_name, last_name, birth_date FROM person WHERE person_no = ?", String.class, 0)); // Person{personNo=0,birthDate=null,firstName=First,lastName=Person} + System.out.println(qm.toObject("SELECT person_no, first_name, last_name, birth_date FROM person WHERE person_no = ?", String.class, 1)); // Person{personNo=1,birthDate=null,firstName=Second,lastName=Person} + + // instead of toCollection can use toList, toArray, toResultSetIterable, toStream (java8+) + System.out.println(qm.toCollection("SELECT person_no, first_name, last_name, birth_date FROM person WHERE last_name = ?", new ArrayList(), String.class, "Person")); // [Person{personNo=0,birthDate=null,firstName=First,lastName=Person}, Person{personNo=1,birthDate=null,firstName=Second,lastName=Person}] +} +``` \ No newline at end of file