mirror of
https://github.com/moparisthebest/JdbcMapper
synced 2024-11-14 21:25:08 -05:00
235 lines
11 KiB
Markdown
235 lines
11 KiB
Markdown
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. Currently there are different packages for java6 and java8+, these are built from the same
|
|
source with a bit of sed-like magic, when the documentation refers to classes only available in java8+ just know these
|
|
are obviously unavailable if you use the java6 version.
|
|
|
|
Why
|
|
---
|
|
|
|
The [java.sql](https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html) API is horrible, [ResultSet.wasNull()](https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html#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
|
|
------------------------
|
|
|
|
All decisions as to which ResultSet method(s) to call are based on the Java type being mapped to, because we have no
|
|
knowledge of any database schema. These mappings rarely if ever need changed, they can be overridden with QueryMapper
|
|
but not currently at compile-time with JdbcMapper.
|
|
|
|
If you are thinking 'shut up and show me the code already' refer to [ResultSetUtil.java](https://github.com/moparisthebest/JdbcMapper/blob/master/common/src/main/java/com/moparisthebest/jdbc/util/ResultSetUtil.java)
|
|
which contains the implementations actually called.
|
|
|
|
For the purposes of this mapping, consider 'rs' an instance of ResultSet, and 'index' an int index of a ResultSet column.
|
|
|
|
### numeric primitives
|
|
if the SQL value is NULL, 0 is returned for these, and no exception is thrown
|
|
##### byte
|
|
```java
|
|
return rs.getByte(index);
|
|
```
|
|
##### short
|
|
```java
|
|
return rs.getShort(index);
|
|
```
|
|
##### int
|
|
```java
|
|
return rs.getInt(index);
|
|
```
|
|
##### long
|
|
```java
|
|
return rs.getLong(index);
|
|
```
|
|
##### float
|
|
```java
|
|
return rs.getFloat(index);
|
|
```
|
|
##### double
|
|
```java
|
|
return rs.getDouble(index);
|
|
```
|
|
### numeric objects
|
|
these wrapper types are retrieved using the same function returning their primitives above, except null is returned
|
|
if the SQL value is NULL instead of 0
|
|
```java
|
|
x ret = rs.getX(index);
|
|
return rs.wasNull() ? null : ret;
|
|
```
|
|
##### java.math.BigDecimal
|
|
```java
|
|
return rs.getBigDecimal(index);
|
|
```
|
|
### boolean
|
|
in all cases of SQL NULL being returned, if primitive boolean is requested an SQLException is thrown, if Object Boolean
|
|
is requested then null is returned.
|
|
|
|
boolean has special handling due to many popular databases not actually having a boolean type (hi Oracle!),
|
|
forcing application level workarounds.
|
|
|
|
0/1 numeric types convert to boolean using the standard ResultSet API, but many systems use char/varchar of Y/N or T/F,
|
|
which we default to Y/N but can be set via system properties:
|
|
|
|
ResultSetUtil.TRUE=Y
|
|
ResultSetUtil.FALSE=N
|
|
|
|
First the standard ResultSet API is attempted:
|
|
```java
|
|
return rs.getBoolean(index);
|
|
```
|
|
If this does not throw an SQLException, it is returned directly
|
|
If SQLException is thrown, then we try to compare as a String:
|
|
```java
|
|
String bool = rs.getString(index);
|
|
boolean ret = ResultSetUtil.TRUE.equals(bool);
|
|
if (!ret && !ResultSetUtil.FALSE.equals(bool))
|
|
throw new SQLException(String.format("Implicit conversion of database string to boolean failed on column '%d'. Returned string needs to be '%s' or '%s' and was instead '%s'.", index, ResultSetUtil.TRUE, ResultSetUtil.FALSE, bool));
|
|
return ret;
|
|
```
|
|
The returned string MUST be either TRUE or FALSE (or null, for Object Boolean) or an exception will be thrown
|
|
### Misc Objects
|
|
For all of these, when SQL NULL is returned, it maps to null
|
|
##### String
|
|
```java
|
|
return rs.getString(index);
|
|
```
|
|
##### byte[]
|
|
```java
|
|
return rs.getBytes(index);
|
|
```
|
|
##### java.sql.Ref
|
|
```java
|
|
return rs.getRef(index);
|
|
```
|
|
##### java.sql.Blob
|
|
```java
|
|
return rs.getBlob(index);
|
|
```
|
|
##### java.sql.Clob
|
|
```java
|
|
return rs.getClob(index);
|
|
```
|
|
##### java.sql.Array
|
|
```java
|
|
return rs.getArray(index);
|
|
```
|
|
##### java.sql.Struct
|
|
```java
|
|
return rs.getObject(index);
|
|
```
|
|
##### *
|
|
If nothing else fits, we call getObject and cross our fingers with QueryMapper at runtime, this is a compile-time error
|
|
with JdbcMapper. todo: is this actually a compile-time error? it *should* be, check...
|
|
```java
|
|
return rs.getObject(index);
|
|
```
|
|
todo: finish documenting this
|
|
|
|
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<Person> getPeople(String lastName) throws SQLException; // all rows in any Collection<T> (like Set<T>, LinkedList<T> etc), T[], ResultSetIterable<T> or Stream<T> (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>(), String.class, "Person")); // [Person{personNo=0,birthDate=null,firstName=First,lastName=Person}, Person{personNo=1,birthDate=null,firstName=Second,lastName=Person}]
|
|
}
|
|
```
|
|
|
|
TODO
|
|
----
|
|
|
|
* DOCUMENTATION!!!!!
|
|
* sql other than select return boolean, int > 0 ?
|
|
* @RunInTransaction void support
|
|
* QueryMapper mapping errors should be clearer, especially if a .finish(ResultSet) throws an error |