Professional Documents
Culture Documents
Gray Watson
This manual is licensed by Gray Watson under the Creative Commons Attribution-Share Alike 3.0 License. Permission is granted to make and distribute verbatim copies of this manual provided the previous license notice and this permission notice are preserved on all copies.
Table of Contents
ORMLite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1 1.2 1.3 1.4 Downloading ORMLite Jar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conguring a Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conguring a DAO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2 3 3
How to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1 Setting Up Your Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1.1 Adding ORMLite Annotations . . . . . . . . . . . . . . . . . . . 5 2.1.2 Using javax.persistence Annotations . . . . . . . . . . . . . 11 2.1.3 Adding a No-Argument-Constructor . . . . . . . . . . . . 13 Persisted Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Connection Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Setting Up the DAOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Supported Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Tying It All Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Table and Schema Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.7.1 TableUtils Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.7.2 TableCreator Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Identity Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 2.8.1 Fields With id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 2.8.2 Fields With generatedId . . . . . . . . . . . . . . . . . . . . . . . . 25 2.8.3 Fields With generatedIdSequence . . . . . . . . . . . . . . . 25 DAO Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Indexing Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Issuing Raw SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 2.11.1 Issuing Raw Queries . . . . . . . . . . . . . . . . . . . . . . . . . . 29 2.11.2 Issuing Raw Update Statements . . . . . . . . . . . . . . . 31 2.11.3 Issuing Raw Execute Statements . . . . . . . . . . . . . . . 31 Foreign Object Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Foreign Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 DAO Enabled Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.8
ii
Advanced Concepts . . . . . . . . . . . . . . . . . . . . . . . 55
5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 5.9 5.10 5.11 Spring Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Class Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database Specic Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DAO Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORMLite Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . External Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Database Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conguring a Maven Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Batch Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Custom Data Type Persisters . . . . . . . . . . . . . . . . . . . . . . . . . . 55 56 57 59 65 66 67 67 69 70 70
Example Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7.1 7.2 JDBC Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Android Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
iii
8 9
Index of Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
ORMLite
6 September 2013
ORMLite
Version 4.47 September 2013 ORMLite provides a lightweight Object Relational Mapping between Java classes and SQL databases. There are certainly more mature ORMs which provide this functionality including Hibernate and iBatis. However, the author wanted a simple yet powerful wrapper around the JDBC functions, and Hibernate and iBatis are signicantly more complicated with many dependencies. ORMLite supports JDBC connections to MySQL, Postgres, H2, SQLite, Derby, HSQLDB, Microsoft SQL Server, and can be extended to additional ones relatively easily. ORMLite also supports native database calls on Android OS. There are also initial implementations for DB2, Oracle, generic ODBC, and Netezza although the author needs access to an instance of each of these databases to tune the support. Contact the author if your database is not supported. To get started quickly with ORMLite, see Chapter 1 [Getting Started], page 2. Android users should also look at the Android specic pages. See Chapter 4 [Use With Android], page 49. You can also take a look at the the examples section of the document which has various working code packages and Android applications. See Chapter 7 [Examples], page 78. There is also a HTML version of this documentation. Gray Watson http://256.com/gray/
6 September 2013
1 Getting Started
The following information should help you to get started with ORMLite. Android users should also look at the Android specic page after reading these pages here. See Chapter 4 [Use With Android], page 49.
6 September 2013
public String getName() { return name; } public void setName(String name) { this.name = name; } public String getPassword() { return password; } public void setPassword(String password) { this.password = password; } }
6 September 2013
// this uses h2 by default but change to match your database String databaseUrl = "jdbc:h2:mem:account"; // create a connection source to our database ConnectionSource connectionSource = new JdbcConnectionSource(databaseUrl); // instantiate the dao Dao<Account, String> accountDao = DaoManager.createDao(connectionSource, Account.class); // if you need to create the accounts table make this call TableUtils.createTable(connectionSource, Account.class); Once we have congured our database objects, we can use them to persist an Account to the database and query for it from the database by its ID: // create an instance of Account Account account = new Account(); account.setName("Jim Coakley"); // persist the account object to the database accountDao.create(account); // retrieve the account from the database by its id field (name) Account account2 = accountDao.queryForId("Jim Coakley"); System.out.println("Account: " + account2.getName()); // close the connection source connectionSource.close(); } } You should be able to get started using ORMLite by this point. To understand more of the functionality available with ORMLite, continue on with the next section. See Chapter 2 [Using], page 5. For more examples including working code and Android application projects see Chapter 7 [Examples], page 78.
6 September 2013
2 How to Use
This chapter goes into more detail about how to use the various features in ORMLite.
6 September 2013
@DatabaseField(canBeNull = false) private String password; ... In the above example, each row in the accounts table has 2 columns: the name column which is a string and also is the database identity (id) of the row the password column, also a string which can not be null The @DatabaseField annotation can have the following elds: columnName String name of the column in the database that will hold this eld. If not set then the eld name, with normalized case, is used instead. dataType The type of the eld as the DataType class. Usually the type is taken from Java class of the eld and does not need to be specied. This corresponds to the SQL type. See Section 2.2 [Persisted Types], page 14. defaultValue String default value of the eld when we are creating a new row in the table. Default is none. width Integer width of the eld mostly used for string elds. Default is 0 which means to take the data-type and database-specic default. For strings that means 255 characters although some databases do not support this. canBeNull Boolean whether the eld can be assigned to null value. Default is true. If set to false then you must provide a value for this eld on every object inserted into the database. id Boolean whether the eld is the id eld or not. Default is false. Only one eld can have this set in a class. Id elds uniquely identity a row and are required if you want to use the query, update, refresh, and delete by ID methods. Only one of this, generatedId, and generatedIdSequence can be specied. See Section 2.8.1 [Id Column], page 24. generatedId Boolean whether the eld is an auto-generated id eld. Default is false. Only one eld can have this set in a class. This tells the database to auto-generate a corresponding id for every row inserted. When an object with a generatedid is created using the Dao.create() method, the database will generate an id for the row which will be returned and set in the object by the create method. Some databases require sequences for generated ids in which case the sequence name will be auto-generated. To specify the name of the sequence use generatedIdSequence. Only one of this, id, and generatedIdSequence can be specied. See Section 2.8.2 [GeneratedId Column], page 25.
6 September 2013
generatedIdSequence String name of the sequence number to be used to generate this value. Same as generatedId but you can specify the sequence name to use. Default is none. Only one eld can have this set in a class. This is only necessary for databases which require sequences for generated ids. If you use generatedId instead then the code will auto-generate a sequence name. Only one of this, id, and generatedId can be specied. See Section 2.8.3 [GeneratedIdSequence Column], page 25. foreign Boolean setting which identies this eld as corresponding to another class that is also stored in the database. Default is false. The eld must not be a primitive type. The other class must have an id eld (either id, generatedId, or generatedIdSequence) which will be stored in this table. When an object is returned from a query call, any foreign objects will just have the id eld set. See Section 2.12 [Foreign Objects], page 32. useGetSet Boolean that says that the eld should be accessed with get and set methods. Default is false which instead uses direct eld access via Java reection. This may be necessary if the object you are storing has protections around it. NOTE: The name of the get method must match getXxx() where Xxx is the name of the eld with the rst letter capitalized. The get must return a class which matches the elds exactly. The set method must match setXxx(), have a single argument whose class matches the elds exactly, and return void. For example: @DatabaseField(useGetSet = true) private Integer orderCount; public Integer getOrderCount() { return orderCount; } public void setOrderCount(Integer orderCount) { this.orderCount = orderCount; } unknownEnumName If the eld is a Java enumerated type then you can specify the name of a enumerated value which will be used if the value of a database row is not found in the enumerated type. If this is not specied and a database row does contain an unknown name or ordinal value then a SQLException is thrown when the row is being read from the database. This is useful to handle backwards compatibility when handling out-of-date database values as well as forwards compatibility if old software is accessing up-to-date data or if you have to roll a release back.
6 September 2013
throwIfNull Boolean that tells ORMLite to throw an exception if it sees a null value in a database row and is trying to store it in a primitive eld. By default it is false. If it is false and the database eld is null, then the value of the primitive will be set to 0 (false, null, etc.). This can only be used on a primitive eld. persisted Set this to be false (default true) to not store this eld in the database. This is useful if you want to have the annotation on all of your elds but turn o the writing of some of them to the database. format This allows you to specify format information of a particular eld. Right now this is only applicable for the following types: DATE_STRING for specifying the format of the date string stored in the database STRING_BYTES for specifying the Charset used to encode the string as an array of bytes unique Adds a constraint to the table so that this eld that it has to be unique across all rows in the table. For example, you might have an Account class which has a generated account-id but you also want the email address to be unique across all Accounts. If more than one eld is marked as unique in a table, then each of the elds by themselves must be unique. For example, if you have the firstName and lastName elds, both with unique=true and you have "Bob", "Smith" in the database, you cannot insert "Bob", "Jones" nor "Kevin", "Smith". To have more than 1 eld that are each unique in combination, see the uniqueCombo setting. You can also use the uniqueIndexName to create an index for this eld. uniqueCombo Adds a constraint to the table so that a combination of all elds that have uniqueCombo set to true has to be unique across all rows in the table. For example, if you have the firstName and lastName elds, both with uniqueCombo=true, and you have "Bob", "Smith" in the database, you cannot insert another "Bob", "Smith" but you can insert "Bob", "Jones" and "Kevin", "Smith". To have elds be unique by themselves, see the unique setting. You can also use the uniqueIndexName to create an index for this eld. index Boolean value (default false) to have the database add an index for this eld. This will create an index with the name columnName with a " idx" sux. To specify a specic name of the index or to index multiple elds, use the indexName eld.
6 September 2013
uniqueIndex Boolean value (default false) to have the database add a unique index for this eld. Same as index but this will ensure that all of the values in the index are unique. If you just want to make sure of unique-ness then you can use the unique eld instead. indexName String value (default none) to have the database add an index for this eld with this name. You do not need to specify the index boolean as well. To index multiple elds together in one index, each of the elds should have the same indexName value. uniqueIndexName String value (default none) to have the database add a unique index for this eld with this name. Same as index but this will ensure that all of the values in the index are unique. For example, this means that you can insert ("pittsburgh", "pa") and ("harrisburg", "pa") and ("pittsburgh", "tx") but not another ("pittsburgh", "pa"). foreignAutoRefresh Set this to be true (default false) to have a foreign eld automagically refreshed when an object is queried. The default is to just have the ID eld in the object retrieved and for the caller to call refresh on the correct DAO. If this is set to true then, when the object is queried, a separate database call will be made to load of the elds of the foreign object via an internal DAO. NOTE: this will not automagically create the foreign object if you create an object that has this eld set. NOTE: This will create another DAO object internally so low memory devices may want to call refresh by hand. NOTE: To protect against recursion, there are a couple of places were autorefreshing has been limited. If you are auto-refreshing a class that itself has eld with foreignAutoRefresh set to true or if you are auto-refreshing a class with a foreign collection, in both cases the resulting eld will be set to null and not auto-refreshed. You can always call refresh on the eld directly if you need it. NOTE: If you have an auto-refreshed eld that is an object that also has an auto-refreshed eld, you may want to tune the maxForeignAutoRefreshLevel value. See below. maxForeignAutoRefreshLevel This can be used to set the maximum number of levels to congure foreign objects. For example, if you have a Question which has an foreign eld of the best Answer, and the Answer has an foreign eld to the corresponding question, then the conguration back and forth can get large. This is especially a problem with auto-refreshed elds when you lookup the Question it could cause an innite loop. By default, ORMLite only goes through 2 levels but you can decrease it to 1 (0 is not valid) or increase it. The higher the number the more database transactions happen when you load in your Question.
10
6 September 2013
In our example, the foreign elds in Question and Answer could be set to autorefresh. If this is true then with the maxForeignAutoRefreshLevel set to 1, when you query for a Question, the Answer eld will be auto-refreshed, but the Question eld on the answer will only have its id eld set. It will not be auto-refreshed. allowGeneratedIdInsert If this is set to true (default is false) then inserting an object with the ID eld already set will not override it with a generated-id. This is useful when you have a table where you are inserting items that sometimes have IDs and sometimes need them generated. This only works if the database supports this behavior and if generatedId is also true for the eld. columnDefinition If this is set with a string then it will be used to dene the column in the CREATE TABLE statement. By default the database type is used to auto-generate the SQL necessary to create the column. The column name is provided by ORMLite. For example: @DatabaseField(columnDefinition = "LONGBLOB not null", dataType = DataType.BYTE_ARRAY) public byte[] bigBunchOfBytes; foreignAutoCreate Set this to be true (default false) to have the foreign eld automatically created using an internal DAO if its ID eld is not set (null or 0). So when you call dao.create() on the parent object, any foreign eld that has this set to true will possibly generate an additional create call via an internal DAO. By default you have to create the object using its DAO directly. By default you have to create the object using its DAO directly. This only works if generatedId is also set to true. // the account field in Order has foreignAutoCreate=true Order order1 = new Order(); // account1 has not been created in the db yet, id field is null order1.account = account1; // this will create order1 in the order table _and_ // pass order1.account to the internal accountDao.create(). orderDao.create(order1); version Set this to true (default false) to have this eld be a version for the row. A version eld adds restrictions when an object is updated to the datbase that protects against data corruption when multiple entities are updating the row at the same time. This is very useful in distributed database scenarios if (for example) a utility process is updating an Account and you dont want to protect against overwriting a user update from the web-server. 1. The current-value of the version eld is read from the object 2. The update statement is augmented with a "WHERE version = currentvalue"
11
6 September 2013
3. The new-value being updated in the database is changed by ORMLite to be the current-value + 1 or the current java.util.Date 4. If the row has been updated by another entity then the update will not change the database since the current-value will not match the version column in the database and 0 rows changed will be returned by the update method 5. However, if the current-value does match the version eld in the database then the row will be updated, the objects version eld will be set by ORMLite to the new-value, 1 will be returned from update Only the following eld types are appropriate for version elds: short, integer, long, and Date elds. Date can also be stored as a string (dataType = DataType.DATE_STRING) or long (dataType = DataType.DATE_LONG). NOTE: If you dene a Date eld to be a version then you can also use it as a modication time on the row. When the object is created in the database, the version eld will be automatically inserted with the current Date. When the object is updated, the version eld will be updated with the current Date. Something like the following works well (the dataType=... is optional): @DatabaseField(version = true, dataType = DataType.DATE_LONG) private Date lastModified; foreignColumnName Name of the foreign objects eld that is tied to this table. This does not need to be specied if you are using the ID of the foreign object which is recommended. For example, if you have an Order object with a foreign Account then you may want to key o of the Account name instead of the ID. NOTE: Setting this implies foreignAutoRefresh is also set to true because there is no way to refresh the object since the id eld is not stored in the database. So when this is set, the eld will be automatically refreshed in another database query.
12
6 September 2013
@Entity(name = "accounts") public class Account { @Id private String name; @Column(nullable = false) private String password; ... The following javax.persistence annotations and elds are supported: @Entity Species that the class is stored in the database. name Used to specify the name of the associated database table. If not provided then the class name is used. @Column Species the eld to be persisted to the database. You can also just specify the @Id annotation. The following annotation elds are supported, the rest are ignored. name Used to specify the name of the associated database column. If not provided then the eld name is taken. length Species the length (or width) of the database eld. Maybe only applicable for Strings and only supported by certain database types. Default for those that do is 255. Same as the width eld in the @DatabaseField annotation. nullable Set to true to have a eld be able to be inserted into the database with a null value. Same as the canBeNull eld in the @DatabaseField annotation. unique Adds a constraint to the eld that it has to be unique across all rows in the table. Same as the unique eld in the @DatabaseField annotation. @Id Used to specify a eld to be persisted to the database as a primary row-id. If you want to have the id be auto-generated, you will need to also specify the @GeneratedValue annotation.
13
6 September 2013
@GeneratedValue Used to dene an id eld as having a auto-generated value. This is only used in addition to the @Id annotation. See the generatedId eld in the @DatabaseField annotation for more details. @OneToOne or @ManyToOne Fields with these annotations are assumed to be foreign elds. See Section 2.12 [Foreign Objects], page 32. ORMLite does not enforce the many or one relationship nor does it use any of the annotation elds. It just uses the existence of either of these annotations to indicate that it is a foreign object. @JoinColumn name Sets the column name of the eld. Same as @Column{name=...}. nullable Set to true to have a eld be able to be inserted into the database with a null value. Same as @Column{nullable=...}. @Version Using this annotation will turn short, integer, long, and Date elds into a version eld. See [version eld], page 10. If the @Column annotation is used on a eld that has a unknown type then it is assumed to be a Serializable type eld and the object should implement java.io.Serializable. See [datatype serializable], page 15.
14
6 September 2013
Account() { // all persisted classes must define a no-arg constructor // with at least package visibility } ... }
15
6 September 2013
NOTE: Certain databases only provide seconds resolution so the milliseconds will be 0. java.util.Date (DATE_STRING) You can also specify the dataType eld to the @DatabaseField annotation as a DataType.DATE_STRING in which case the date will be stored as a string in yyyy-MM-dd HH:mm:ss.SSSSSS format. You can use the format eld in DatabaseField to set the date to another format. See also DATE and DATE_ LONG. NOTE: This is a dierent class from java.sql.Date which is handled by DataType.SQL_DATE. NOTE: Certain databases only provide seconds resolution so the milliseconds will be 0. NOTE: Because of reentrant issues with SimpleDateFormat, thread locals are used to access the formatters every time a DATE_STRING date is converted to/from the database. byte or Byte (DataType.BYTE or DataType.BYTE_OBJ) Persisted as SQL type TINYINT. byte array (DataType.BYTE_ARRAY) Array of bytes (byte[]) persisted as SQL type VARBINARY. This is dierent from the DataType.SERIALIZABLE type which serializes an object as an array of bytes. NOTE: Because of backwards compatibility, any elds that are of type byte[] must be specied as DataType.BYTE_ARRAY or DataType.SERIALIZABLE using the dataType eld and will not be auto-detected. See [DatabaseField dataType], page 6. @DatabaseField(dataType = DataType.BYTE_ARRAY) byte[] imageBytes; char or Character (DataType.CHAR or DataType.CHAR_OBJ) Persisted as SQL type CHAR. NOTE: If you are using Derby you should consider using a String instead since comparisons of character elds are not allowed. short or Short (DataType.SHORT or DataType.SHORT_OBJ) Persisted as SQL type SMALLINT. int or Integer (DataType.INTEGER or DataType.INTEGER_OBJ) Persisted as SQL type INTEGER. long or Long (DataType.LONG or DataType.LONG_OBJ) Persisted as SQL type BIGINT. float or Float (DataType.FLOAT or DataType.FLOAT_OBJ) Persisted as SQL type FLOAT. double or Double (DataType.DOUBLE or DataType.DOUBLE_OBJ) Persisted as SQL type DOUBLE.
16
6 September 2013
Serializable (DataType.SERIALIZABLE) Persisted as SQL type VARBINARY. This is a special type that serializes an object as a sequence of bytes and then de-serializes it on the way back. The eld must be an object that implements the java.io.Serializable interface. Depending on the database type, there will be limits to the size of the object that can be stored. This is dierent from the DataType.BYTE_ARRAY type which stores the byte array directly. Some databases place restrictions on this eld type that it cannot be the id column in a class. Other databases do not allow you to query on this type of eld at all. If your database does support it, you may also have to use a Select Argument to query for this type. See Section 3.6 [Select Arguments], page 46. NOTE: To use this type, you must specify DataType.SERIALIZABLE using the dataType eld. It will not be auto-detected. See [DatabaseField dataType], page 6. // image is an object that implements Serializable @DatabaseField(dataType = DataType.SERIALIZABLE) Image image; enum or Enum (DataType.ENUM_STRING) Persisted by default as the enumerated values string name as a VARCHAR type. The string name is the default (and recommended over ENUM INTEGER) because it allows you to add additional enums anywhere in the list without worrying about having to convert data later. You can also also specify an unknownEnumName name with the @DatabaseField annotation which will be used if an unknown value is found in the database. See [unknownEnumName], page 7. enum or Enum (DataType.ENUM_INTEGER) You specify the dataType eld (from the @DatabaseField annotation) as a DataType.ENUM_INTEGER in which case the ordinal of the enum value will be stored as an INTEGER. The name (ENUM STRING) is the default (and recommended) because it allows you to add additional enums anywhere in the list without worrying about having to convert data later. If you insert (or remove) an enum from the list that is being stored as a number, then old data will be un-persisted incorrectly. You can also also specify an unknownEnumName name with the @DatabaseField annotation which will be used if an unknown value is found in the database. See [unknownEnumName], page 7. UUID (DataType.UUID) The java.util.UUID class persisted as a VARCHAR type. It saves it as the uuid.toString() and used the UUID.fromString(String) method to convert it back again. You can also mark a UUID eld as being generated-id in which case whenever it is inserted, java.util.UUID.randomUUID() is called and set on the eld. See Section 2.8.2 [GeneratedId Column], page 25.
17
6 September 2013
BigInteger (DataType.BIG_INTEGER) The java.math.BigInteger class persisted as a VARCHAR type. It is saved using the bigInteger.toString() and uses the string constructor to convert it back again. BigDecimal (DataType.BIG_DECIMAL) The java.math.BigDecimal class persisted as a VARCHAR type. It is saved using the bigDecimal.toString() and uses the string constructor to convert it back again. BigDecimal (DataType.BIG_DECIMAL_NUMERIC) You specify the dataType eld (from the @DatabaseField annotation) as a DataType.BIG_DECIMAL_NUMERIC in which case a java.math.BigDecimal eld will be persisted as a NUMERIC type. This is only supported by some database types and with various default precision settings. Android should use the default DataType.BIG_DECIMAL. DateTime (DataType.DATE_TIME) This stores the Joda DateTime into the database as long epoch millis. This persister uses reection to avoid setting up a dependency with Joda jars. You can dene a custom data persister if you want to natively use the class. See [custom data persister], page 70. java.sql.Date (DataType.SQL_DATE) Persisted as SQL type TIMESTAMP. NOTE: This is the java.sql.Date and not the java.util.Date. It is recommended that you use the java.util.Date class handled by DataType.DATE instead. java.sql.Timestamp (DataType.TIME_STAMP) Persisted as SQL type TIMESTAMP. NOTE: It is recommended that you use the java.util.Date class instead which is the DataType.DATE type. NOTE: ORMLite also supports the concept of foreign objects where the id of another object is stored in the database. See Section 2.12 [Foreign Objects], page 32.
18
6 September 2013
The package also includes the class JdbcPooledConnectionSource which is a relatively simple implementation of a pooled connection source. As database connections are released, instead of being closed, they are added to an internal list so they can be reused at a later time. New connections are created on demand only if there are no dormant connections available. JdbcPooledConnectionSource is also synchronized and can be used by multiple threads. It has settings for the maximum number of free connections before they are closed as well as a maximum age before a connection is closed. // pooled connection source JdbcPooledConnectionSource connectionSource = new JdbcPooledConnectionSource("jdbc:h2:mem:account"); // only keep the connections open for 5 minutes connectionSource.setMaxConnectionAgeMillis(5 * 60 * 1000); JdbcPooledConnectionSource also has a keep-alive thread which pings each of the dormant pooled connections every so often to make sure they are valid closing the ones that are no long good. You can also enable the testing of the connection right before you get a connection from the pool. See the javadocs for more information. // change the check-every milliseconds from 30 seconds to 60 connectionSource.setCheckConnectionsEveryMillis(60 * 1000); // for extra protection, enable the testing of connections // right before they are handed to the user connectionSource.setTestBeforeGet(true); There are many other, external data sources that can be used instead, including more robust and probably higher-performance pooled connection managers. You can instantiate your own directly and wrap it in the DataSourceConnectionSource class which delegates to it. // basic Apache data source BasicDataSource dataSource = new BasicDataSource(); String databaseUrl = "jdbc:h2:mem:account"; dataSource.setUrl(databaseUrl); // we wrap it in the DataSourceConnectionSource ConnectionSource connectionSource = new DataSourceConnectionSource(dataSource, databaseUrl); When you are done with your ConnectionSource, you will want to call a close() method to close any underlying connections. Something like the following pattern is recommended. JdbcConnectionSource connectionSource = new JdbcPooledConnectionSource("jdbc:h2:mem:account"); try { // work with the data-source and DAOs ... } finally { connectionSource.close(); }
19
6 September 2013
Unfortunately, the DataSource interface does not have a close method so if you are using the DataSourceConnectionSource you will have to close the underlying DataSource by hand the close() method on the DataSourceConnectionSource does nothing.
20
6 September 2013
@DatabaseTable(daoClass = AccountDaoImpl.class) public class Account { ... } Thats all you need to dene your DAO classes. You are free to add more methods to your DAO interfaces and implementations if there are specic operations that are needed and not provided by the Dao base classes. More on how to use these DAOs later. See Section 2.9 [DAO Usage], page 26. NOTE: If you are using a custom DAO then be sure to add the daoClass argument to the @DatabaseTable annotation which species the class of your custom DAO. This is used by the DaoManager to instantiate the DAO internally. See [DaoManager], page 19.
21
6 September 2013
database type on your ConnectionSource directly if it doesnt. See Section 5.3 [Database Type Details], page 57. HSQLDB No special instructions. Microsoft SQL Server No special instructions. Netezza As of August 2011, the driver should be considered alpha and possibly with bugs. I do not currently have access to a server running a Netezza database. We will try to keep this driver up to date with the help of contributors. Thanks to Richard Kooijman for the driver. Please contact us if you want to help with development of this driver. ODBC As of August 2011, the driver should be considered alpha and possibly with bugs. I do not have access to a server running Microsofts Open Database Connectivity. We will try to keep this driver up to date with the help of contributors. Thanks to Dale Asberry for the driver. Please contact us if you want to help with development of this driver. DB2 I do not have access to an DB2 database so we cannot run any tests to make sure that our support for it works well. Please contact us if you want to help with development of this driver. Oracle I do not have access to an Oracle database so we cannot run any tests to make sure that our support for it works well. Please contact us if you want to help with development of this driver. Please contact the author if your database is not supported.
22
6 September 2013
// if you need to create the accounts table make this call TableUtils.createTable(connectionSource, Account.class); // create an instance of Account Account account = new Account("Jim Coakley"); // persist the account object to the database accountDao.create(account); ... // destroy the data source which should close underlying connections connectionSource.destroy(); For more examples, see the code later in the manual. See Chapter 7 [Examples], page 78.
23
6 September 2013
DatabaseTableConfig<Account> tableConfig = new DatabaseTableConfig<Account>(Account.class, fieldConfigs); // this returns number of statements executed to create table TableUtils.createTable(connectionSource, tableConfig); createTableIfNotExists(ConnectionSource, DatabaseTableConfig) Similar to the last method but it will only create the table if it doesnt exist. This is not supported on all database types. dropTable(ConnectionSource, Class, boolean ignoreErrors) This method drops the table associated with the class. It uses the annotations from the class to determine the name of the table to drop. This is not undo-able and most likely will be used only in tests since production tables are dropped rarely. The ignoreErrors argument is useful when you are dropping a table before you are creating it and the table may not already exist. If ignoreErrors is true then any exceptions are swallowed. dropTable(ConnectionSource, DatabaseTableConfig, boolean ignoreErrors) Same as the previous method but it will use the DatabaseTableConfig to determine the name of the table to drop. getCreateTableStatements(ConnectionSource, Class) This is similar to the createTable method but will return a list of statements that can be used to create a class. This is useful if you want to load the schema during some sort of database initialization process. getCreateTableStatements(ConnectionSource, DatabaseTableConfig) Same as the previous method but with a DatabaseTableConfig instead. clearTable(ConnectionSource, Class) Clear all data out of the table. For certain database types and with large sized tables, which may take a long time. In some congurations, it may be faster to drop and re-create the table. This is [obviously] very destructive and is unrecoverable. clearTable(ConnectionSource, DatabaseTableConfig) Same as the previous method but with a DatabaseTableConfig instead.
24
6 September 2013
changes by hand. You can set the system properties in your test start scripts but leave them o in the production scripts. List<Dao<?, ?>> daoList = new ArrayList<Dao<?, ?>>(); daoList.add(accountDao); ... TableCreator creator = new TableCreator(connectionSource, daoList); // create the tables if the right system property is set creator.maybeCreateTables(); ... // later, we may want to drop the tables that were created creator.maybeDropTables(); For a real life example of using TableCreator you can see [spring example], page 78.
25
6 September 2013
NOTE: If you need to change the value of an objects id eld, you must use the Dao.updateId() method which takes the current object still with its old id value and the new value. ORMLite has to rst locate the object by its old id and then update it with the new id. See [updateId], page 61.
26
6 September 2013
match existing schema, you can used the generatedIdSequence value which takes a string name for the sequence. public class Order { @DatabaseField(generatedIdSequence = "order_id_seq") private int id; ... } In the above example, the id value is again automatically generated but using a sequence with the name order_id_seq. This will throw an exception if you are working with a database which does not support sequences. NOTE: Depending on the database type, you may not be able to change the value of an auto-generated id eld.
27
6 September 2013
accountDao.delete(account); iterate through all of the rows in a table: The DAO is also an iterator so you can easily run through all of the rows in the database: // page through all of the accounts in the database for (Account account : accountDao) { System.out.println(account.getName()); } NOTE: you must page through all items for the iterator to close the underlying SQL object. If you dont go all of the way through to the loop, ORMLite does not know to close the underlying object, and a connection to the database may be leaked that will only be closed if the garbage collector reaps some time later which may cause bugs in your code. Use the try ... finally wrapped iterator patterns below. For example, the following for loop is a very bad pattern. for (Account account : accountDao) { if (account.getName().equals("Bob Smith")) { // you cant return, break, or throw from here return account; } } This also may happen if an exception is thrown out of the loop so for loops should not be used in these cases. This is also the case with lazy loaded collections. See [lazy collection iterator], page 35. use the iterator directly You can also use the iterator directly because the for loops are not optimal. This allows you to use try ... finally which is a much better pattern. CloseableIterator<Account> iterator = accountDao.closeableIterator(); try { while (iterator.hasNext()) { Account account = iterator.next(); System.out.println(account.getName()); } } finally { // close it at the end to close underlying SQL statement iterator.close(); } get a "wrapped iterable" You can also use the "wrapped iterable" which allows you to do the close in the nally while still using for loops. CloseableWrappedIterable<Account> wrappedIterable = accountDao.getWrappedIterable(); try {
28
6 September 2013
for (Account account : wrappedIterable) { ... } } finally { wrappedIterable.close(); } For a detailed list of the methods in the DAO see Section 5.4 [DAO Methods], page 59.
29
6 September 2013
To create unique indexes, there is a uniqueIndex = true and uniqueIndexName = "othername" elds also available on the @DatabaseField annotation. These work the same as the above settings but will instead create unique indexes that ensure that no two row has the same value(s) for the indexed eld(s).
30
6 September 2013
If you want to use the QueryBuilder with aggregate or other raw/custom arguments do something like the following. Since there is only one result out you can use the genericRawResults.getFirstResult() method: QueryBuilder<Account, Integer> qb = accountDao.queryBuilder(); // select 2 aggregate functions as the return qb.selectRaw("MIN(orderCount)", "MAX(orderCount)"); // the results will contain 2 string values for the min and max results = accountDao.queryRaw(qb.prepareStatementString()); String[] values = results.getFirstResult(); For large numbers of results, you should consider using the iterator() method on the GenericRawResults object which uses database paging. For example: // return the orders with the sum of their amounts per account GenericRawResults<String[]> rawResults = orderDao.queryRaw( "select account_id,sum(amount) from orders group by account_id"); // page through the results for (String[] resultArray : rawResults) { System.out.println("Account-id " + resultArray[0] + " has " + resultArray[1] + " total orders"); } rawResults.close(); If you are just trying to query for a single value (typically an aggregate function like MAX) then you can use the queryRawValue(...) method: long maxUnits = orderDao.queryRaw("select max(units) from orders"); If some of your elds cannot be appropriately mapped to strings, you can also return the elds as an Object[] if you pass in the types of the resulting columns. For example: // return the orders with the sum of their amounts per account GenericRawResults<Object[]> rawResults = orderDao.queryRaw( "select account_id,sum(amount) from orders group by account_id", new DataType[] { DataType.LONG, DataType.INTEGER }); // page through the results for (Object[] resultArray : rawResults) { System.out.println("Account-id " + resultArray[0] + " has " + resultArray[1] + " total orders"); } rawResults.close(); NOTE : select * can return elds in dierent orders depending on the database type. To make sure that the data-type array matches the returned columns you must specify the elds specically and not with a SQL *. You can also map the results into your own object by passing in a RawRowMapper object. This will call the mapping object with an array of strings and allow it to convert the strings into an object. The DAO provides a default RawRowMapper that can be gotten from orderDao.getRawRowMapper() that knows how to convert the string array into the object.
31
6 September 2013
You can also dene your own custom mapper if the results are more complex. For example: // return the orders with the sum of their amounts per account GenericRawResults<Foo> rawResults = orderDao.queryRaw( "select account_id,sum(amount) from orders group by account_id", new RawRowMapper<Foo>() { public Foo mapRow(String[] columnNames, String[] resultColumns) { return new Foo(Long.parseLong(resultColumns[0]), Integer.parseInt(resultColumns[1])); } }); // page through the results for (Foo foo : rawResults) { System.out.println("Account-id " + foo.accountId + " has " + foo.totalOrders + " total orders"); } rawResults.close(); NOTE : The query and the resulting strings can be very database-type specic. For example: 1. Certain databases need any column names specied in uppercase others need lowercase. 2. You may have to quote your column or table names if they are reserved words. 3. The resulting column names also could be uppercase or lowercase. 4. select * can return elds in dierent orders depending on the database type. NOTE : Like other ORMLite iterators, you will need to make sure you iterate through all of the results to have the statement closed automatically. You can also call the GenericRawResults.close() method to make sure the iterator, and any associated database connections, is closed. NOTE: If you are using the QueryBuilder#prepareStatementString() method to build your query, it may have added the id column to the selected column list if the Dao object has an id you did not include it in the columns you selected. So your results might have one more column than you are expecting.
32
6 September 2013
33
6 September 2013
If you want some level of auto creation, then you can use the foreignAutoCreate setting. See [foreignAutoCreate], page 10. When you query for an order, you will get an Order object with an account eld object that only has its id eld set. The rest of the elds in the foreign Account object will have default values (null, 0, false, etc.). If you want to use other elds in the Account, you must call refresh on the accountDao class to get the Account object lled in. For example: Order order = orderDao.queryForId(orderId); System.out.println("Account-id on the order should be set: " + order.account.id); // this should print null for order.account.name System.out.println("But other fields on the account should not be set: " + order.account.name); // so we refresh the account using the AccountDao accountDao.refresh(order.getAccount()); System.out.println("Now the account fields will be set: " + order.account.name); You can have the foreign objects automagically refreshed foreignAutoRefresh setting. See [foreignAutoRefresh], page 9. by using the
NOTE: Because we use refresh, foreign objects are therefor required to have an id eld. You can query for foreign elds in a couple of dierent ways. The following examples show code which queries for all orders that match a certain account eld. Since the id eld is the name eld, you can query by the name eld of the account: // query for all orders that match a certain account List<Order> results = orderDao.queryBuilder().where(). eq("account_id", account.getName()).query(); Or you can just let ORMLite extract the id eld from the account itself. This will perform an equivalent query to the above: // ORMLite will extract and use the id field internally List<Order> results = orderDao.queryBuilder().where(). eq("account_id", account).query(); There is example code to show how to use foreign objects. See [foreign objects example], page 78.
34
6 September 2013
public class Account { ... @ForeignCollectionField(eager = false) ForeignCollection<Order> orders; ... } In the above example, the @ForeignCollectionField annotation marks that the orders eld is a collection of the orders that match the account. The eld type of orders must be either ForeignCollection<T> or Collection<T> no other collections are supported because they are much heavier with many methods to support. The @ForeignCollectionField annotation supports the following elds: eager There are two dierent types of foreign collections: eager or lazy. If eager is set to true then the separate query is made immediately and the orders are stored as a list within the collection. If eager is set to false (the default) then the collection is considered to be "lazy" and will iterate over the database using the Dao.iterator() only when a method is called on the collection. WARNING: By default, if you have eager collections of objects that themselves have eager collections, the inner collection will be created as lazy for performance reasons. If you need change this see the maxEagerLevel setting below. maxEagerLevel This can be set to the number of times to expand an eager foreign collections foreign collection. If you query for A and it has an eager foreign-collection of eld B which has an eager foreign-collection of eld C (. . . ), then a lot of database operations are going to happen whenever you query for A. By default this value is 1 meaning that if you query for A, the collection of B will be eager fetched but each of the B objects will have a lazy collection instead of an eager collection of C. It should be increased only if you know what you are doing. columnName The name of the column. This is only used if you want to match the string passed to Dao.assignEmptyForeignCollection(Object, String) or to specify that you want the collection returned when you specify queryBuilder.selectColumns(...). See [selectColumns], page 41. orderColumnName The name of the column in the foreign object that we should order the collection by. orderAscending If an order column has been dened with the above orderColumnName, this sets the order as ascending (true which is the default) or descending (false). foreignFieldName Name of the eld (not the column name) in the class that the collection is holding that corresponds to the collection. This is needed if there are two foreign elds in the class in the collection (such as a tree structure) and you want to identify which column you want in this collection.
35
6 September 2013
WARNING: Due to some internal complexities, this it eld/member name in the class and not the column-name. Remember that when you have a ForeignCollection eld, the class in the collection must (in this example Order) must have a foreign eld for the class that has the collection (in this example Account). If Account has a foreign collection of Orders, then Order must have an Account foreign eld. It is required so ORMLite can nd the orders that match a particular account. WARNING: With lazy collections, even the size() method causes a iteration across the database. Youll most likely want to just use the iterator() and toArray() methods on lazy collections. NOTE: Like with the Dao.iterator() method, the iterator returned by a lazy collection must be closed when you are done with it because there is a connection open to the database underneath. A close happens either if you go all of the way through the iterator or if you call close() on it. Only the ForeignCollection returns a closeable iterator. This means that for loops across lazy loaded collections are a bad pattern. For more details about iterating across lazy collections, see the iterator documentation. See [iterator], page 27. The foreign collections support the add() and remove() methods in which case the objects will be both added or removed from the internal list if the collection is eager, and DAO calls will be made to aect the order table as well for both eager and lazy collections. NOTE : When you are adding a new object to a foreign collection, this will also add it to the database by calling through to dao.create(obj). If the object has already been created in the database then you should instead set the foreign eld on the object and call dao.update(obj). If you add it here the DAO will try to create it in the database again which will most likely cause an error. NOTE : When you call update on an object with a foreign collection (like Account above) the objects that are stored in the collection are not automatically written to the database as well. There is no way for ORMLite to be able to detect which of the objects has been updated unfortunately. If you update an object in the collection you should call the update(data) method on the ForeignCollection to make sure that the object is persisted. For example: for (Order order : account.orders()) { // if we are changing some field in the order order.setAmount(123); // then we need to update it in the database account.orders.update(order); } Lastly, there is example code to show how to use foreign collections. See [foreign collections example], page 78.
36
6 September 2013
is to use the Dao classes which allow your data classes to have their own hierarchy and it isolates the database code in the Daos. However, you are free to use the BaseDaoEnabled class if you prefer this pattern. All classes that are able to refresh (update, delete, etc.) themselves should extend the BaseDaoEnabled class. For example: @DatabaseTable(tableName = "accounts") public class Account extends BaseDaoEnabled { @DatabaseField(id = true) private String name; @DatabaseField(canBeNull = false) private String password; ... To rst create the object, you will need to use the DAO object or you will need to set the dao on the object so that it can self create: account.setDao(accountDao); account.create(); However, whenever an object is returned by ORMLite as query results, the DAO has already been set on the object it extends the BaseDaoEnabled class. Account account = accountDao.queryForId(name); account.setPassword(newPassword); account.update(); This will also work for foreign elds. Order order = orderDao.queryForId(orderId); // load all of the fields from the account order.getAccount().refresh(); The javadocs for BaseDaoEnabled will have the most up-to-date list of self operations but right now the class can do: create To create the object you will need to use the DAO or to call setDao() on the object. refresh Refresh the object in case it was updated in the database. update After you make changes to the object in memory, update it in the database. updateId If you need to update the id of the object, you must use this method. You cannot change the id eld in the object and then call the update method because then the object will not be found. delete Delete it from the database. Feedback on this is welcome.
37
6 September 2013
38
6 September 2013
You can use another short cut to call query() or iterator() either on the QueryBuilder or Where objects. // query for all accounts that have that password List<Account> accountList = accountDao.queryBuilder().where() .eq(Account.PASSWORD_FIELD_NAME, "qwerty") .query();
39
6 September 2013
where.and( where.eq(Account.NAME_FIELD_NAME, "bar"), where.eq(Account.PASSWORD_FIELD_NAME, "qwerty"))); This produces the following approximate SQL: SELECT * FROM account WHERE ((name = foo AND password = _secret) OR (name = bar AND password = qwerty)) If you want to do complex queries linearly, you can even use Reverse Polish Notation (of all things). There is a Where.or(int) and Where.and(int) methods which do the operation on the previous number of specied clauses. where.eq(Account.NAME_FIELD_NAME, "foo"); where.eq(Account.PASSWORD_FIELD_NAME, "_secret"); // this does an AND between the previous 2 clauses // it also puts a clause back on the stack where.and(2); where.eq(Account.NAME_FIELD_NAME, "bar"), where.eq(Account.PASSWORD_FIELD_NAME, "qwerty"))); // this does an AND between the previous 2 clauses // it also puts a clause back on the stack where.and(2); // this does an OR between the previous 2 AND clauses where.or(2); The QueryBuilder also allows you to set what specic select columns you want returned, specify the ORDER BY and GROUP BY elds, and various other SQL features (LIKE, IN, >, >=, <, <=, <>, IS NULL, DISTINCT, . . . ). See Section 3.5 [Where Capabilities], page 42. You can also see the javadocs on QueryBuilder and Where classes for more information. Heres a good SQL reference site.
40
6 September 2013
// update hasDog boolean to true if dogC > 0 updateBuilder.updateColumnExpression( "hasDog", "dogC > 0"); To help you construct your expressions, you can use the UpdateBuilders escape methods escapeColumnName and escapeValue can take a string or a StringBuilder. This will protect you if columns or values are reserved words. If, instead, you wanted to delete the rows in the Accounts table whose password is currently null, then you might do something like the following: DeleteBuilder<Account, String> deleteBuilder = accountDao.deleteBuilder(); // only delete the rows where password is null deleteBuilder.where().isNull(Account.PASSWORD_FIELD_NAME); deleteBuilder.delete();
41
6 September 2013
other one. An exception will be thrown otherwise. This can be called multiple times to join with more than one table. leftJoin(QueryBuilder joinedQueryBuilder) Same as join(QueryBuilder) but it will use "LEFT JOIN" instead. See: LEFT JOIN SQL documentation. NOTE: RIGHT and FULL JOIN SQL commands are not supported because we are only returning objects from the "left" table. limit(Integer maxRows) Limit the output to maxRows maximum number of rows. Set to null for no limit (the default). offset(Integer startRow) Start the output at this row number. Set to null for no oset (the default). If you are paging through a table, you should consider using the Dao.iterator() method instead which handles paging with a database cursor. Otherwise, if you are paging you probably want to specify a column to orderBy. NOTE: This is not supported for all databases. Also, for some databases, the limit must also be specied since the oset is an argument of the limit. orderBy(String columnName, boolean ascending) Add "ORDER BY" clause to the SQL query statement to order the results by the specied column name. Use the ascending boolean to get a ascending or descending order. This can be called multiple times to group by multiple columns. orderByRaw(String sql) Add a raw SQL "ORDER BY" clause to the SQL query statement. This allows you to order by things that are not just columns but can include calculations. The SQL argument should not include the "ORDER BY" string. prepare() Build and return a prepared query that can be used by Dao.query(PreparedQuery) or Dao.iterator(PreparedQuery) methods. If you change the where or make other calls you will need to re-call this method to re-prepare the statement for execution. selectColumns(String... columns) Add columns to be returned by the SELECT query and set on any resulting objects. If no columns are selected then all columns are returned by default. For classes with id columns, the id column is added to the select list automagically. All elds not selected in the object with be their default values (null, 0, false, etc.). This allows you to in eect have lazy loaded elds. You can specify exactly which elds to be set on the resulting objects. This is especially helpful if you have large elds in a table that you dont always want to access. To get all of the elds on the object later, you can either do another query or call refresh() with the object. This can be called multiple times to add more columns to select.
42
6 September 2013
WARNING: If you specify any columns to return, then any foreign-collection elds will be returned as null unless their ForeignCollectionField.columnName is also in the list. See [ForeignCollectionField], page 34. selectColumns(Iterable<String> columns) Same as the above but with an iterable (such as a collection) instead of a variable list of column names. This can be called multiple times to add more columns to select. selectRaw(String... columns) Add raw columns or aggregate functions (COUNT, MAX, ...) to the query. This will turn the query into something only suitable for using as a raw query. This can be called multiple times to add more columns to select. See Section 2.11.1 [Raw Queries], page 29. where() Build and return the Where object with which you can customize your WHERE SQL statements. See Section 3.5 [Where Capabilities], page 42. query() Convenience method to perform the query. Same as dao.query(queryBuilder.prepare()). queryForFirst() Convenience method to perform the query and return the rst result. Same as dao.queryForFirst(queryBuilder.prepare()). queryRawFirst() Convenience method to perform a raw query on the generated state and then return the rst result as a String[]. Same as Dao.queryRaw(String) and GenericRawResults.getFirstResult(). iterator() Convenience method to generate the iterator for the query. dao.iterator(queryBuilder.prepare()). reset() Resets all of the settings in the QueryBuilder so it can be reused. Same as
43
6 September 2013
and(Where<T, ID> first, Where<T, ID> second, Where<T, ID>... others) AND operation which takes 2 or more arguments and ANDs them together. This is when you are not using inline query calls but instead want to use standard arguments. NOTE: There is no guarantee of the order of the clauses that are generated in the nal query. NOTE: There is an annoying code warning that I get with the usage of this method with more than 2 arguments that can be ignored. and(int numClauses) This method needs to be used carefully. This will absorb a number of clauses that were registered previously with calls to Where.eq() or other methods and will string them together with ANDs. There is no way to verify the number of previous clauses so the programmer has to count precisely. NOTE: There is no guarantee of the order of the clauses that are generated in the nal query. between(String columnName, Object low, Object high) Add a BETWEEN clause which makes sure the column is between the low and high parameters. eq(String columnName, Object value) Add a = clause which makes sure the column is equal to the value. exists(QueryBuilder<?, ?> subQueryBuilder) Add a EXISTS clause with a sub-query inside of parenthesis. This will return returns as long as the inner query returns results. NOTE: The sub-query will be prepared at the same time that the outside query is. ge(String columnName, Object value) Add a >= clause which makes sure the column is greater-than or equals-to the value. gt(String columnName, Object value) Add a > clause which makes sure the column is greater-than the value. idEq(ID id) Add a clause where the ID is equals to the argument. idEq(Dao<OD, ?> dataDao, OD data) Add a clause where the ID is extracted from an existing object. in(String columnName, Iterable<?> objects) Add a IN clause which makes sure the column is equal-to one of the objects from the Iterable passed in. Most likely the Iterable should probably be on of the Collection classes such as a List or Set. in(String columnName, Object... objects) Add a IN clause which makes sure the column is equal-to one of the objects passed in.
44
6 September 2013
in(String columnName, QueryBuilder<?, ?> subQueryBuilder) Add a IN clause which makes sure the column is in one of the columns returned from a sub-query inside of parenthesis. The QueryBuilder must return 1 and only one column which can be set with the QueryBuilder.selectColumns(String...) method calls. That 1 argument must match the SQL type of the column-name passed to this method. See also Section 3.8 [Join Queries], page 47. NOTE: The sub-query will be prepared at the same time that the outside query is. isNull(String columnName) Add a IS NULL clause which makes sure the columns value is null. = NULL does not work. isNotNull(String columnName) Add a IS NOT NULL clause so the column must not be null. <> NULL does not work. le(String columnName, Object value) Add a <= clause which makes sure the column is less-than or equals-to the value. lt(String columnName, Object value) Add a < clause which makes sure the column is less-than the value. like(String columnName, Object value) Add a LIKE clause which makes sure the column match the value using % patterns. ne(String columnName, Object value) Add a <> clause which makes sure the column is not-equal-to the value. not() Used to NOT the next clause specied when using inline query calls. not(Where<T, ID> comparison) Used to NOT the argument clause specied. This is when you are not using inline query calls but instead want to use standard arguments. notIn(String columnName, Iterable<?> objects) Same as the IN clause but negated. Results are returned that are not in the objects from the iterator. in(String columnName, Object... objects) Same as IN clause but negated. Results are returned that are not in the variable array of objects. notIn(String columnName, QueryBuilder<?, ?> subQueryBuilder) Same as IN clause but negated. Results are returned that are not in the results from the sub-query. or() Binary OR operation which takes the previous clause and the next clause and ORs them together. This is when you are using inline query calls.
45
6 September 2013
or(Where<T, ID> first, Where<T, ID> second, Where<T, ID>... others) OR operation which takes 2 or more arguments and ORs them together. This is when you are not using inline query calls but instead want to use standard arguments. NOTE: There is no guarantee of the order of the clauses that are generated in the nal query. NOTE: There is an annoying code warning that I get with the usage of this method with more than 2 arguments that can be ignored. or(int numClauses) This method needs to be used carefully. This will absorb a number of clauses that were registered previously with calls to Where.eq() or other methods and will string them together with ORs. There is no way to verify the number of previous clauses so the programmer has to count precisely. raw(String rawStatement) Add a raw statement as part of the WHERE that can be anything that the database supports. Using the more structured methods above is recommended but this gives more control over the query and allows you to utilize database specic features. prepare() A short-cut for calling prepare() on the original QueryBuilder.prepare(). This method returns a PreparedQuery object. reset() Reset the where object so it can be reused in a new query but with the same QueryBuilder. query() Convenience method to perform the query. Same as queryBuilder.query() and dao.query(queryBuilder.prepare()). queryRaw() Convenience method to perform the query and return raw results. Same as queryBuilder.queryRaw() and dao.queryRaw(...). queryForFirst() Convenience method to perform the query and return rst result. Same as queryBuilder.queryForFirst() dao.queryForFirst(queryBuilder.prepare()). the and
queryRawFirst() Convenience method to perform the query and return the rst raw result. Same as queryBuilder.queryRawFirst() and dao.queryRaw(...). countOf() Convenience method to perform the query and return number of results. Same as queryBuilder.countOf() dao.countOf(queryBuilder.prepare()). the and
46
6 September 2013
iterator() Convenience method to generate the iterator for the query. Same as queryBuilder.iterator() and dao.iterator(queryBuilder.prepare()).
47
6 September 2013
// list all of the accounts that have the same // name and password field queryBuilder.where().eq(Account.NAME_FIELD_NAME, new ColumnArg(Account.PASSWORD_FIELD_NAME)); List<Account> results = queryBuilder.query(); The ColumnArg can also take a table-name which is useful with JOIN queries to compare a column from one table with one in another table. See Section 3.8 [Join Queries], page 47. For example: QueryBuilder<Order, Integer> orderQb = orderDao.queryBuilder(); orderQb.where().ge("amount", 100.0F); QueryBuilder<Account, Integer> accountQb = accountDao.queryBuilder(); // find all accounts who have an order larger than their limit accountQb.where().gt(Account.MAX_LIMIT_AMOUNT_FIELD, new ColumnArg("orders", Order.AMOUNT_FIELD)); // join with the order query List<Account> results = accountQb.join(orderQb).query();
48
6 September 2013
Please note that other ORM libraries use JOIN statements to retrieve results from multiple tables to ll in foreign elds and foreign collections. ORMLite does not support this feature. You can only get results from one table using it.
49
6 September 2013
50
6 September 2013
private DatabaseHelper databaseHelper = null; @Override protected void onDestroy() { super.onDestroy(); if (databaseHelper != null) { OpenHelperManager.releaseHelper(); databaseHelper = null; } } private DBHelper getHelper() { if (databaseHelper == null) { databaseHelper = OpenHelperManager.getHelper(this, DatabaseHelper.class); } return databaseHelper; } 5. By default, if you are using OrmLiteBaseActivity or other base classes, the OpenHelperManager will detect the database helper class through reection. Another way to wire in the appropriate database helper class is to set the full class name of it in the the open_helper_classname value dened in the res/values/strings.xml resource le . You can also set the class using the OpenHelperManager.setOpenHelperClass(Class) method in a static {} block in your code. 6. The Android native SQLite database type is SqliteAndroidDatabaseType and is used by the base classes internally. 7. WARNING: You must make sure that any background threads call the OpenHelperManager.getHelper() and release() methods appropriately. Otherwise, if they access the database before it is opened or after it is closed, you will get exceptions. Please see the example code documentation for more information. See Section 7.2 [Android Examples], page 78. Again, feedback on this is welcome.
51
6 September 2013
We have made a couple of changes in ORMLite to help work around this issue. Firstly, we added some reection hacks to work around these problems in the short run. Annotations using this mechanism run 20 times faster than with the native Android calls. With a little bit of work (and some caveats), you can remove all annotation work from your application and make DAO creation an extremely fast operation. ORMLite supports the loading of the data congurations from a text conguration le. When a DAO is created, these congurations will be used, removing the need for any annotation method calls entirely. 1. The OrmLiteConfigUtil utility class writes a ormlite_config.txt conguration le in the raw resource folder res/raw/ormlite_config.txt. You will need to extend this class into your own project along side your DatabaseHelper class. It should look something like: public class DatabaseConfigUtil extends OrmLiteConfigUtil { public static void main(String[] args) throws Exception { writeConfigFile("ormlite_config.txt"); } } 2. You will need to run this utility locally on your development box (not in an Android device), whenever you make a change to one of your data classes. This means that right now, this must be done by hand to keep the conguration le in sync with your database classes. To run the utility you will need to use the local Java runtime environment (JRE). Under eclipse, edit the "Run Conguration" for the utility, select the JRE tab, and select an alternative JRE (1.5 or 1.6). Your projects JRE should be undened since it is an Android application. Youll also need to remove the Android bootstrap entry from the Classpath tab. 3. By default this utility will look in the current directory and below in les ending in .java for the existence of one of the @DatabaseTable or DatabaseField annotations. These classes will be investigated and written into the database conguration le. You can also list the classes to be processed: public class DatabaseConfigUtil extends OrmLiteConfigUtil { private static final Class<?>[] classes = new Class[] { SimpleData.class, }; public static void main(String[] args) throws Exception { writeConfigFile("ormlite_config.txt", classes); } } 4. When the utility is run it should create the ormlite_config.txt conguration le in the raw resource folder. This folder must exist before the utility is run. Afterwards, if you refresh your project your should see the le appear. In the Eclipse console, you should see something like the following outputted by the utility: Writing configurations to /HelloAndroid/./res/raw/ormlite_config.txt Wrote config for class com.example.helloandroid.SimpleData Done. The cong le generated should look something like:
52
6 September 2013
# # generated on 2011/09/15 01:42:02 # # --table-start-dataClass=com.example.helloandroid.SimpleData tableName=simpledata # --table-fields-start-# --field-start-fieldName=id canBeNull=true generatedId=true ... 5. The rst time you create the cong le in the resource folder, the Android build plugin should add it to the R.java le inside of the gen folder. This denes a unique integer value so that the application can open this resource by le-id number. The le should contain something like: public final class R { ... public static final class raw { public static final int ormlite_config=0x7f040000; } ... } 6. After the R.java le entry has been generated, you will need to enable the reading of the le at runtime. Inside of your DatabaseHelper class, you will need to change the constructor to add the integer le-id. The constructor will look something like the following: public DatabaseHelper(Context context) { super(context, DATABASE_NAME, null, DATABASE_VERSION, R.raw.ormlite_config); } Notice the R.raw.ormlite_config entry at the end that passes the le-id to the super class so it can be read in. You can also pass in a le-name or a Java File if you want to load in the cong le from another location. 7. When you build and run your application, you will know that the database conguration le is being loaded if you see log entries like the following: I/DaoManager( 999): Loaded configuration for class ...SimpleData Oh, and if it is working you should notice a signicant lack of GC messages during DAO startup. As of 9/2011, this is one of the newest parts of ORMLite so we most likely will be improving it. Feedback is welcome.
53
6 September 2013
The ormlite-android.jar classes dene the AndroidLog class which is the Android specic version of ORMLite logging. This class makes calls to the Log.d, Log.i, . . . methods in the Android API. To see the log output, you will need to use the adb utility to view the log output: adb logcat Since INFO is the default under Android, only message such as the following will be spit out by default: I/TableUtils( 254): creating table simpledata I/TableUtils( 254): creating index simpledata_string_idx for table simpledata I/TableUtils( 254): executed create table statement changed 1 rows: CREATE TABLE simpledata (date VARCHAR, id INTEGER PRIMARY KEY AUTOINCREMENT , even SMALLINT ) I/TableUtils( 254): executed create table statement changed 1 rows: CREATE INDEX simpledata_string_idx ON simpledata ( string ) To enable more debug information you will want to do something like the following to turn on logging for a particular class: adb shell setprop log.tag.StatementExecutor VERBOSE adb shell setprop log.tag.BaseMappedStatement VERBOSE adb shell setprop log.tag.MappedCreate VERBOSE This enables messages such as: D/BaseMappedStatement(465): create object using INSERT INTO simpledata (date ,string ,millis ,even ) VALUES (?,?,?,?) and 4 args, changed 1 rows D/BaseMappedStatement(465): assigned id 9 from keyholder to id in SimpleData object To enable all debug messages for all ORMLite classes then use the following: adb shell setprop log.tag.ORMLite DEBUG NOTE: Unfortunately, Android property names are limited in size so the ORMLite logger only takes that last 23 [sic] characters of the class name if it is larger than 23 characters. For example, if the class is AndroidDatabaseConnection you would do: adb shell setprop log.tag.droidDatabaseConnection VERBOSE If you are trying to track operations performed to the database by ORMLite use: adb shell setprop log.tag.droidDatabaseConnection VERBOSE adb shell setprop log.tag.ndroidCompiledStatement VERBOSE
54
6 September 2013
Dao<Account, String> dao = DaoManager.createDao(connectionSource, Account.class); RuntimeExceptionDao<Account, String> accountDao = new RuntimeExceptionDao<Account, String>(dao); Or you can call the createDao helper methods on RuntimeExceptionDao: RuntimeExceptionDao<Account, String> accountDao = RuntimeExceptionDao.createDao(connectionSource, Account.class); Other classes such as TableUtils and QueryBuilder still throw SQLException but the hope is that RuntimeExceptionDao helps a little bit at least.
55
6 September 2013
5 Advanced Concepts
5.1 Spring Conguration
ORMLite contains some classes which make it easy to congure the various database classes using the Spring Framework. TableCreator Spring bean that auto-creates any tables that it nds DAOs for if the system property ormlite.auto.create.tables has been set to true. It will also auto-drop any tables that were auto-created if the property ormlite.auto.drop.tables has been set to true. This should be used carefully and probably only in tests. DaoFactory Spring bean that can be used to create Daos for certain classes without needing to dene their own Dao class. Heres an example of a full Spring conguration. <!-- URL used for database, probably should be in properties file --> <bean id="databaseUrl" class="java.lang.String"> <!-- we are using the in-memory H2 database in this example --> <constructor-arg index="0" value="jdbc:h2:mem:account" /> </bean> <!-- datasource used by ORMLite to connect to the database --> <bean id="connectionSource" class="com.j256.ormlite.jdbc.JdbcConnectionSource" init-method="initialize"> <property name="url" ref="databaseUrl" /> <!-- probably should use system properties for these too --> <property name="username" value="foo" /> <property name="password" value="bar" /> </bean> <!-- abstract dao that is common to all defined daos --> <bean id="baseDao" abstract="true" init-method="initialize"> <property name="connectionSource" ref="connectionSource" /> </bean> <!-- our daos --> <bean id="accountDao" class="com.j256.ormlite.examples.common.AccountDaoImpl" parent="baseDao" /> <bean id="deliveryDao" class="com.j256.ormlite.spring.DaoFactory" factory-method="createDao"> <constructor-arg index="0" ref="connectionSource" />
56
6 September 2013
<constructor-arg index="1" value="com.j256.ormlite.examples.spring.Delivery" /> </bean> You can also take a look at the spring example code. See [spring example], page 78.
57
6 September 2013
<bean class="com.j256.ormlite.field.DatabaseFieldConfig"> <property name="fieldName" value="password" /> <property name="canBeNull" value="false" /> </bean> </list> </property> </bean> You can also look at the eld conguration example code. See [eld cong example], page 78.
58
6 September 2013
dropColumnArg Takes a eld type and adds all of the commands necessary to drop the column from the database. appendEscapedEntityName Add a entity-name (table or column name) word to the SQL wrapped in the proper characters to escape it. This avoids problems with table, column, and sequence-names being reserved words. appendEscapedWord Add the word to the string builder wrapped in the proper characters to escape it. This avoids problems with data values being reserved words. generateIdSequenceName Return the name of an ID sequence based on the table-name and the eld-type of the id. This is required by some database types when we have generated ids. getCommentLinePrefix Return the prex to put at the front of a SQL line to mark it as a comment. isIdSequenceNeeded Return true if the database needs a sequence when you insert for generated IDs. Some databases handle generated ids internally. getFieldConverter Return the eld converter associated with a particular eld type. This allows the database instance to convert a eld as necessary before it goes to the database. isVarcharFieldWidthSupported Return true if the database supports the width parameter on VARCHAR elds. isLimitSqlSupported Return true if the database supports the LIMIT sql command. isLimitAfterSelect Return true if the LIMIT should be called after SELECT otherwise at the end of the WHERE (the default). appendLimitValue Add the necessary SQL to limit the results to a certain number. isOffsetSqlSupported Return true if the database supports the OFFSET SQL command in some form. isOffsetLimitArgument Return true if the database supports the oset as a comma argument from the limit. This also means that the limit must be specied if the oset is specied. appendOffsetValue Append to the string builder the necessary SQL to start the results at a certain row number. appendSelectNextValFromSequence Add the SQL necessary to get the next-value from a sequence. This is only necessary if isIdSequenceNeeded returns true.
59
6 September 2013
appendCreateTableSuffix Append the SQL necessary to properly nish a CREATE TABLE line. isCreateTableReturnsZero Returns true if a CREATE TABLE statement should return 0. False if > 0. isEntityNamesMustBeUpCase Returns true if table and eld names should be made uppercase. This is an unfortunate "feature" of Derby and Hsqldb. See the Javadocs for the class for more information. isNestedSavePointsSupported Returns true if the database supports nested savepoints (transactions). getPingStatement Return an statement that doesnt do anything but which can be used to ping the database by sending it over a database connection. isBatchUseTransaction Returns true if batch operations should be done inside of a transaction. Default is false in which case auto-commit disabling will be done. isTruncateSupported Returns true if the table truncate operation is supported. isCreateIfNotExistsSupported Returns true if the table creation IF NOT EXISTS syntax is supported.
60
6 September 2013
queryForMatching(T matchObj) Query for the rows in the database that match the object passed in as an argument. Any elds in the matching object that are not the default value (null, false, 0, 0.0, etc.) are used as the matching parameters with AND. If you are worried about SQL quote escaping, you should use queryForMatchingArgs. queryForMatchingArgs(T matchObj) Same as queryForMatching but this uses SQL ? arguments. This is slightly more expensive but you dont have to worry about SQL quote escaping. queryForFieldValues(Map<String, Object> fieldValues) Query for the rows in the database that matches all of the eld to value entries from the map passed in. queryForFieldValuesArgs(Map<String, Object> fieldValues) Same as queryForFieldValues but this uses SQL ? arguments. This is slightly more expensive but you dont have to worry about SQL quote escaping. queryForSameId(T data) Query for a data item in the table that has the same ID as the data parameter. queryBuilder() Create and return a new QueryBuilder object which allows you to build a custom query. See Section 3.1 [QueryBuilder Basics], page 37. updateBuilder() Create and return a new UpdateBuilder object which allows you to build a custom update statement. See [UpdateBuilder], page 39. deleteBuilder() Create and return a new DeleteBuilder object which allows you to build a custom delete statement. See [DeleteBuilder], page 39. query(PreparedQuery<T> preparedQuery) Query for the items in the object table which match a prepared statement. See Chapter 3 [Statement Builder], page 37. This returns a list of matching objects. For medium sized or large tables, this may load a lot of objects into memory so you should consider using the iterator method instead. create(T data) Create a new entry in the database from an object. Should return 1 indicating 1 row was inserted. createIfNotExists(T data) This is a convenience method to creating a data item but only if the ID does not already exist in the table. This extracts the id from the data parameter, does a query for on it, returning the data if it exists. If it does not exist then create is called with the data parameter. createOrUpdate(T data) This is a convenience method for creating an item in the database if it does not exist. The id is extracted from the data argument and a query-by-id is made on the database. If a row in the database with the same id exists then
61
6 September 2013
all of the columns in the database will be updated from the elds in the data parameter. If the id is null (or 0 or some other default value) or doesnt exist in the database then the object will be created in the database. This also means that your data item must have an id eld dened. update(T data) Save the elds from an object to the database. If you have made changes to an object, this is how you persist those changes to the database. You cannot use this method to update the id eld see updateId(). This should return 1 since 1 row was updated. updateId(T data, ID newId) Update an object in the database to change its id to a new id. The data must have its current id set and the new-id is passed in as an argument. After the id has been updated in the database, the id eld of the data object will also be changed. This should return 1 since 1 row was updated. update(PreparedUpdate<T> preparedUpdate) Update objects that match a custom update statement. refresh(T data, ID newId) Does a query for the objects id and copies in each of the eld values from the database to refresh the data parameter. Any local object changes to persisted elds will be overwritten. If the database has been updated this brings your local object up-to-date. This should return 1 since 1 row was retrieved. delete(T data) Delete an object from the database. This should return 1 since 1 row was removed. deleteById(ID id) Delete an object from the database if you have its id. This should return 1 since 1 row was removed. delete(Collection<T> datas) Delete a collection of objects from the database using an IN SQL clause. This returns the number of rows that were deleted. deleteIds(Collection<ID> ids) Delete the objects that match the collection of ids from the database using an IN SQL clause. This returns the number of rows that were deleted. delete(PreparedDelete<T> preparedDelete) Delete objects that match a custom delete statement. iterator() This method satises the Iterable Java interface for the class and allows you to iterate through the objects in the table using SQL. This method allows you to do something like: for (Account account : accountDao) { ... } WARNING: See the Dao class for warnings about using this method.
62
6 September 2013
iterator(PreparedQuery<T> preparedQuery) Same is the iterator method but with a prepared statement parameter. See Chapter 3 [Statement Builder], page 37. getWrappedIterable() This returns a one time use iterable class that can be closed afterwards. The DAO itself is CloseableWrappedIterable but multiple threads can each call this to get their own closeable iterable. This allows you to do something like: CloseableWrappedIterable<Account> wrappedIterable = accountDao.getWrappedIterable(); try { for (Account account : wrappedIterable) { ... } } finally { wrappedIterable.close(); } getWrappedIterable(PreparedQuery<T> preparedQuery) Same as getWrappedIterable() but with a prepared query parameter. closeLastIterator() This closes the last iterator returned by the iterator() method. NOTE: This is not reentrant. If multiple threads are getting iterators from this DAO then you should use getWrappedIterable() method. queryRaw(String query, String... arguments) Query for all of the items in the object table that match the SQL select query argument. This method allows you to do special queries that arent supported otherwise. For medium sized or large tables, this may load a lot of objects into memory so you should consider using the iterator() method on the GenericRawResults instead of the getResults method. See Section 2.11.1 [Raw Queries], page 29. queryRaw(String query, RawRowMapper<UO> mapper, String... arguments) Same as the above queryRaw method but with the addition of a row mapper. Instead of each row being returned as an array of strings, this will map the row using the mapper object passed in. See Section 2.11.1 [Raw Queries], page 29. queryRaw(String query, DataType[] columnTypes, RawRowObjectMapper<UO> mapper, String... arguments) Similar to the above queryRaw but uses the column-types array to present an array of object results to the mapper instead of strings. The arguments are optional but can be set with strings to expand ? type of SQL. See Section 2.11.1 [Raw Queries], page 29. queryRaw(String query, DataType[] columnTypes) Same as the above queryRaw method but with the addition of a an array of column data types. Instead of each row being returned as an array of strings, they are returned as an array of objects. See Section 2.11.1 [Raw Queries], page 29.
63
6 September 2013
queryRawValue(String query, String... arguments) Perform a raw query that returns a single value (usually an aggregate function like MAX or COUNT). If the query does not return a single long value then it will throw a SQLException. executeRaw(String statement) Run a raw execute SQL statement against the database. See Section 2.11.3 [Raw Executes], page 32. updateRaw(String statement) Run a raw update SQL statement (INSERT, DELETE, or UPDATE against the database. See Section 2.11.2 [Raw Updates], page 31. callBatchTasks(Callable callable) Call the call-able that will perform a number of batch tasks. This is for performance when you want to run a number of database operations at once maybe loading data from a le. This will turn o what databases call "auto-commit" mode, run the call-able and then re-enable "auto-commit". If auto-commit is not supported then it will try to use a database transaction to speed up the tasks. NOTE: If neither auto-commit nor transactions are supported by the database type then this method may not give any performance improvement. accountDao.callBatchTasks(connectionSource, new Callable<Void>() { public Void call() throws SQLException { // insert a number of accounts at once for (Account account : accountsToInsert) { // update our account object accountDao.create(account); } return null; } }); countOf() Returns the value returned from a SELECT COUNT(*) query which is the number of rows in the table. Depending on the database and the size of the table, this could be expensive. countOf(PreparedQuery<T> preparedQuery) Returns the number of rows in the table associated with the prepared query passed in. Depending on the size of the table and the database type, this may be expensive and take a while. assignEmptyForeignCollection(T parent, String fieldName) Assigns an empty collection to the appropriate collection eld that has the eld-name. This allows you to add things to the collection from the start. This allows you to do something like: accoundDao.assignEmptyForeignCollection(account, "orders"); // this would add it the collection and the internal DAO
64
6 September 2013
account.orders.add(order1); setObjectCache(boolean enabled); Call this with true to enable an object cache for the DAO. Set to false to disable any caching. See Section 5.8 [Object Caches], page 68. setObjectCache(ObjectCache objectCache); Same as setObjectCache(boolean) except you specify the actual cache instance to use for the DAO. This allows you to inject your own cache classes. Call it with null to disable the cache. See Section 5.8 [Object Caches], page 68. clearObjectCache(); Flush the object cache if it has been enabled. This will remove an objects that are in the cache to reclaim memory. Any future queries will re-request them from the database. mapSelectStarRow(DatabaseResults results) Return the latest row from the database results from a query to select * (star). This allows you to remap the results. It is particularly useful if you are repositioning a database cursor externally. getSelectStarRowMapper() Return a row mapper that is suitable for mapping results from a query to select * (star). idExists(ID id) Returns true if an object exists that matches this ID otherwise false. startThreadConnection() WARNING: This method is for advanced users only. It is only to support the setAutoCommit(conn, boolean) and other methods below. Chances are you should be using the TransactionManager class callInTransaction(Callable) method instead f this method unless you know what you are doing. This allocates a connection for this specic thread that will be used in all other DAO operations. The thread must call endThreadConnection(conn) once it is done with the connection. It is highly recommended that a try / finally pattern be used here to ensure you do not leak connections. This is really only useful if you are using a pooled connection source and want to do certain operations on the same pool. Android users, for example have a single connection to the database so this is eectively a no-op. endThreadConnection(DatabaseConnection connection) This method is used to free the connection startThreadConnection() above. returned by the
setAutoCommit(DatabaseConnection connection, boolean autoCommit) Set auto-commit mode to be true or false on the connection returned by the startThreadConnection(). This may not be supported by all database types.
65
6 September 2013
isAutoCommit(DatabaseConnection connection) Return true if the database connection returned by the startThreadConnection() is in auto-commit mode otherwise false. This may not be supported by all database types. commit(DatabaseConnection connection) If you have previously called setAutoCommit(conn, false) then this will commit all changes to the database made from that point up to now on the connection returned by the startThreadConnection(). The changes will be written to the database and discarded. The connection will continue to stay in the current auto-commit mode. WARNING: Chances are you should be using the TransactionManager class callInTransaction(Callable) method instead unless you know what you are doing. rollBack(DatabaseConnection connection) If you have previously called setAutoCommit(conn, false) then this will rollback and ush all changes to the database made from that point up to now on the connection returned by the startThreadConnection(). None of those changes will be written to the database and are discarded. The connection will continue to stay in the current auto-commit mode. WARNING: Chances are you should be using the TransactionManager class callInTransaction(Callable) method instead unless you know what you are doing.
66
6 September 2013
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout # print the date in ISO 8601 format log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} [%p] %c{1} %m%n # be more verbose with our code log4j.logger.com.j256.ormlite=DEBUG # to enable logging of arguments to all of the SQL calls # uncomment the following lines #log4j.logger.com.j256.ormlite.stmt.mapped.BaseMappedStatement=TRACE #log4j.logger.com.j256.ormlite.stmt.mapped.MappedCreate=TRACE #log4j.logger.com.j256.ormlite.stmt.StatementExecutor=TRACE Notice that you can uncomment the last lines in the above log4j.properties le to log the arguments to the various SQL calls. This may expose passwords or other sensitive information in the database so probably should only be used during debugging and should not be the default. If you are using the LocalLog logger (which is helpful for testing at least) then you can congure it using a ormliteLocalLog.properties le. The le congures the log output of the ORMLite LocalLog class. Lines in the le have the format class-regex-pattern = Level. For example: com\.j256\.ormlite.* = DEBUG com\.j256\.ormlite\.stmt\.mapped\.BaseMappedStatement = TRACE com\.j256\.ormlite\.stmt\.mapped\.MappedCreate = TRACE com\.j256\.ormlite\.stmt\.StatementExecutor = TRACE NOTE: You should escape any period characters with a single backslash unless they are part of a regex match. For logging with Android, See Section 4.3 [Android Logging], page 52.
67
6 September 2013
com.h2database As a test database implementation, H2 is very fast and simple to use. However, we recommend MySQL or Postgres for multi-threaded, high-performance, production databases.
68
6 September 2013
69
6 September 2013
cleanNullReferencesAll() method on your cache to remove these objects and free up their associated memory on occasion. There is also a Least Recently Used (LRU) cache that will store a certain number of objects based on a capacity value. Each class gets the same capacity value so if the same cache is used in 5 dierent daos, then 500 objects will be held in the LruObjectCache if the capacity is 100. Dao<Account, String> accountDao = DaoManager.createDao(connectionSource, Account.class); // enable least-recently-used cache with max 100 items per class accountDao.setObjectCache(new LruObjectCache(100)); You can also implement your own cache class that implements the ObjectCache interface. All of the caches can be cleared if you want to free up memory and you can also disable the cache from the DAO if necessary. // clear all Account items from the cache accountDao.clearObjectCache(); ... // disable the cache accountDao.setObjectCache(false);
70
6 September 2013
NOTE: I do not have any details about how to congure Android projects with maven. If you are doing so then just replace the ormlite-jdbc artifact name with ormlite-android.
71
6 September 2013
if (TODO: somehow test fo 0000-00-00 here) return null; else return timestamp; } The data persister example has a MyDatePersister class which does just that. See [data persister example], page 78. To use your persister class on a particular eld in your objects, you would do something like this: @DatabaseField(persisterClass = MyDatePersister.class) Date birthDate; ORMLite also allows you to dene data persisters for atypical or custom data types that are not handled at all by the internal classes. When dening a data persister class from scratch, you could extend one of the other data type persisters or the BaseDataType class. You will need to dene the following methods. 1. parseDefaultString Converts a default string into a SQL argument suitable to be loaded into the database. 2. resultToSqlArg Uses the DatabaseResults object to get the right SQL argument type out of the results. 3. sqlArgToJava Converts the SQL argument to the associated Java class. Look at the other data types in com.j256.ormlite.field.types for other examples. When you have dened your persister class, you can use it with the persisterClass construct above or you can register it with the DataPersisterManager.registerPersisters(...) method. This will then automatically call your persister whenever a eld with the associated class is congured. DataPersisterManager.registerDataPersisters( MyTypePersister.getSingleton()); You probably would not want to register the MyDatePersister above because you would not want to change the persistence behavior for all Date types.
72
6 September 2013
73
6 September 2013
74
6 September 2013
super(connectionSource, tableConfig); } } Because we had to write specic code to reect on the @DatabaseField annotation we have deprecated the @DatabaseFieldSimple and other annotations that were added in version 4.26. Sorry for the reversal on this but they were also causing confusion.
75
6 September 2013
76
6 September 2013
You now call selectColumns() on the QueryBuilder instead of columns() since now we have columns also in the UpdateBuilder. Unfortunately, there are no deprecated methods for them on the StatementBuilder. You call QueryBuilder.prepare() instead of StatementBuilder.prepareStatement(). It returns a PreparedQuery instead of a PreparedStmt. You pass a PreparedQuery into the Dao.query() and Dao.iterator() methods instead of a PreparedStmt. We removed the DatabaseTypeFactory class since it was no longer needed for Spring congurations. Removed BaseJdbcDao since it had been deprecated in 3.X.
77
6 September 2013
that customized queries of ORMLite generated tables were aected. In version 2.4, all tables and eld names are capitalized in the SQL generated for Derby and Hsqldb databases. This means that if you have data in these databases from a pre 2.4 version, the 2.4 version will not be able to nd the tables and elds without renaming to be uppercase.
78
6 September 2013
7 Example Code
Here is some example code to help you get going with ORMLite. I often nd that code is the best documentation of how to get something working. Please feel free to suggest additional example packages for inclusion here. Source code submissions are welcome as long as you dont get piqued if we dont chose yours.
79
6 September 2013
ClickCounter A nice little application written by Kevin G. that provides a counter type application using ORMLite. NotifyService An example of a service application that uses ORMLite written by Kevin G. HelloAndroidH2 This is similar to the HelloAndroid example but it is using JDBC and H2 instead of the build-in Android database calls. This is more a proof of concept rather than a true example. The wiring for the onCreate and onUpdate is a hack. H2 is certainly larger, has tons more features, but is slower than the native SQLite. Also, JDBC under Android is not completely sanctioned by Google and support for it may be removed in the future. HelloAndroidNoBase This is similar to the HelloAndroid example but its activity does not extend the OrmLiteBaseActivity but instead manages the helpers itself. Certain programmers may want to manage the database connections using their own code to better share between activities and services or to use ORMLite when it is not possible to extend the base classes. HelloAndroidTwoDbs This is similar to the HelloAndroid example but it uses two separate databases, manages the helpers itself, and does not use the OpenHelperManager to manage the helpers at all. This is one way that you can deal with two dierent databases.
Chapter 8: Contributions
80
6 September 2013
8 Contributions
There are a number of people who have helped with this project. If Ive forgotten you please remind me so I can add you to this list. Let me know if youd like to tune your name or add link to your home page here as well. Thanks much to them all. Kevin Galligan was the impetus and the author of a good bit of the Android compatible code. He wrote the Android level support classes and did a ton of beta-testing of it. Hes also provided the initial Android examples. See http://www.kagii.com/. Nelson Erb was our self-appointed documentation and testing volunteer for a year. He did a great job summarizing sections of this document so we could create a better Getting Started section. He also eshed out a bunch of unit tests to improve coverage. Craig Andrews and Pedro Velasco has been very quick with feedback, bug reports, feature requests and other help. JC Romanda has been an excellent addition to the user base providing feedback, discovering and reporting bugs, providing patches for new features, testing new features before the release, and thinking a lot about how ORMLite can be extended and improved. Jim Gloor was one of the Java gurus at a previous company. His great object instincts and the JDBC code samples helped start this project. Robert Adamsky was a colleague of mine at a company where he laid out our entire DAO and hibernate class hierarchy. The DAO interface and the BaseDaoImpl where in some part modeled after his code. Thanks much to the following folks for their bug reports, unit test submissions, memory analysis, code samples, feature requests, improvements, and general feedback: Adam Brown, AlexPal, Ali Aksakarya, Andre, Andrea Sprega, Andreas, Andrew Sleeman, Andrey, Bart, Ben Mosher, Candlejack, Casey, Chad Schultz, Chase, Chris Banes, Chris Nevill, Dale Asberry, Daniel Colchete, Evan Grim. Filipe Leandro, Flo, Guillermo Campelo, Howard Liberty, Ian Dees, Javier Hinmel, Jaxelrod, Jaykob, Jean-Maxime Pelletier, Jeremy Mcjunkin, Jeremy Stone, Jeroen Rakhorst, Joao Bosco, John Kristian, Johny Jugianto, Jomble, Jonathan Caryl, Josh Guilfoyle, Kaan, Kyle Lampert, Larry Hamel, Luke Meyer, ManosProm, Mariak Kalman, Mark Rogers, Markus Wiederkehr, Mathias Lin, Micael Dahlgren, Michael, Ming Lin, Miroslav Nadhajsky, Mohammad Moghimi, Nathan Jones, Nick Campion, Patras Vlad, Patrick, Pedro Velasco, Rahan, Ramps, Richard Kooijman, Roger Keays, Roland Oldenburg, Roman Zimmer, Sebastian Roth, Skylar, Slava Tysianchuk, Stephen Couchman, Stew, Stewert, Timo, Tom Tantisalidchai, Tony, Vladimir, Wayne Stidolph, Yossi Wasserman, birbird, coder sam, glenviewje, igromanru, jon, mjomble, nybblr, shikajiro, steen, zachawilson . Thanks much to them all.
81
6 September 2013
Index of Concepts
82
6 September 2013
Index of Concepts
!
!=, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 auto drop tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 auto refresh foreign objects . . . . . . . . . . . . . . . . . . . . 9 auto-generated id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 AVG, using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
<
<, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 <=, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 <>, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
B
BaseDaoEnabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BaseDaoImpl base class . . . . . . . . . . . . . . . . . . . . . . BasicDataSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . batch operations . . . . . . . . . . . . . . . . . . . . . . . . . 63, BETWEEN, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . BigDecimal Numeric type . . . . . . . . . . . . . . . . . . . . BigDecimal type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BigIteger type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . boolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . building queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . bulk inserts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . byte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . byte array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . byte array string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 19 18 70 43 17 17 16 14 38 70 15 15 14
=
=, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
>
>, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 >=, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
@
@Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 @DatabaseField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 @DatabaseTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 @Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 @GeneratedValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 @Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 @JoinColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 @ManyToOne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 @OneToOne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 @Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
C
cache database connection . . . . . . . . . . . . . . . . . . . . 64 caching objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 callBatchTasks . . . . . . . . . . . . . . . . . . . . . . . . . . . 63, 70 can be null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 12 case sensitive columns, Android . . . . . . . . . . . . . . . 73 chain query methods . . . . . . . . . . . . . . . . . . . . . . . . . 38 change id value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 changes with ORMLite versions . . . . . . . . . . . . . . . 72 char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 class annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 class conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 class setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 clear object cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 clear table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 close data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 close last iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 CloseableWrappedIterable . . . . . . . . . . . . . . . . . 27, 62 closing an iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 code example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 code examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 collections of objects . . . . . . . . . . . . . . . . . . . . . . . . . 33 Column annotation . . . . . . . . . . . . . . . . . . . . . . . . . . 12 column arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 column denition, custom . . . . . . . . . . . . . . . . . . . . 10 column name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 ColumnArg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 commit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 comparing multiple columns . . . . . . . . . . . . . . . . . . 46 complex query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 cong le for tables . . . . . . . . . . . . . . . . . . . . . . . . . . 50
A
accented strings, storing . . . . . . . . . . . . . . . . . . . . . . 14 aggregate function, query . . . . . . . . . . . . . . . . . . . . . 30 aggregate functions, query . . . . . . . . . . . . . . . . . . . . 42 aggregate, raw queries . . . . . . . . . . . . . . . . . . . . . . . . 29 AND, many arguments . . . . . . . . . . . . . . . . . . . . . . . 42 AND, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Android basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Android case sensitive columns . . . . . . . . . . . . . . . 73 Android examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Android logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Android OS support . . . . . . . . . . . . . . . . . . . . . . . . . 49 android performance . . . . . . . . . . . . . . . . . . . . . . . . . 50 Android SQLite database . . . . . . . . . . . . . . . . . . . . . 20 Android strings resources . . . . . . . . . . . . . . . . . . . . . 50 annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 arguments to queries . . . . . . . . . . . . . . . . . . . . . . . . . 46 array of bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 assignEmptyForeignCollection . . . . . . . . . . . . . . . . 63 author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 auto create foreign objects . . . . . . . . . . . . . . . . . . . . 10 auto create tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Index of Concepts
83
6 September 2013
conguration with Spring . . . . . . . . . . . . . . . . . . . . . 55 congure a class in code . . . . . . . . . . . . . . . . . . . . . . 56 conguring a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 connection pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 connection source . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 connection source, simple . . . . . . . . . . . . . . . . . . . . . 17 constraint, unique . . . . . . . . . . . . . . . . . . . . . . . . . 8, 12 constructor with no args . . . . . . . . . . . . . . . . . . . . . 13 contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 count of table rows . . . . . . . . . . . . . . . . . . . . . . . . . . 63 COUNT, using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 countOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 create if not exists . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 create or update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 create schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 create tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 createDao . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 createDao method . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 creating a database row . . . . . . . . . . . . . . . . . . . . . . 26 creating a table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 creating an index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 creating an object . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 creating objects with foreign elds . . . . . . . . . . . . 32 custom column denition . . . . . . . . . . . . . . . . . . . . . 10 custom data persister example . . . . . . . . . . . . . . . . 78 custom data types . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 custom delete statement . . . . . . . . . . . . . . . . . . . . . . 61 custom delete statements . . . . . . . . . . . . . . . . . . . . . 39 custom persisters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 custom query builder . . . . . . . . . . . . . . . . . . . . . . . . . 37 custom statement builder . . . . . . . . . . . . . . . . . . . . . 37 custom update statement . . . . . . . . . . . . . . . . . . . . . 61 custom update statements . . . . . . . . . . . . . . . . . . . . 39
database type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 DatabaseField annotation . . . . . . . . . . . . . . . . . . . . . 5 databases supported . . . . . . . . . . . . . . . . . . . . . . . . . . 1 DatabaseTable annotation . . . . . . . . . . . . . . . . . . . . . 5 DataSourceConnectionSource . . . . . . . . . . . . . . . . . 18 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 date formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 date row last modied . . . . . . . . . . . . . . . . . . . . . . . 11 Date, SQL type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 DateTime Joda type . . . . . . . . . . . . . . . . . . . . . . . . . 17 DB2 database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 default value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 delete builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 delete custom statement . . . . . . . . . . . . . . . . . . . . . . 61 delete multiple objects . . . . . . . . . . . . . . . . . . . . . . . 61 delete objects by id . . . . . . . . . . . . . . . . . . . . . . . . . . 61 delete rows in table . . . . . . . . . . . . . . . . . . . . . . . . . . 23 delete tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 deleteBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 deleting an object . . . . . . . . . . . . . . . . . . . . . . . . 26, 61 deleting by ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Derby database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 destroy data source . . . . . . . . . . . . . . . . . . . . . . . . . . 18 dierent databases . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 distinct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 does id exist already . . . . . . . . . . . . . . . . . . . . . . . . . 64 double . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 droid support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 drop tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23, 55
D
DAO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 dao enabled objects . . . . . . . . . . . . . . . . . . . . . . . . . . 35 dao factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Dao interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 dao methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 DAO setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 DAO usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 DaoManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 DaoManager class . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 data access objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 data persister example . . . . . . . . . . . . . . . . . . . . . . . 78 data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 database cong le . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 database connection . . . . . . . . . . . . . . . . . . . . . . . . . 17 database not supported . . . . . . . . . . . . . . . . . . . . . . 21 database notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 database open helper wiring . . . . . . . . . . . . . . . . . . 50 database schema upgrade . . . . . . . . . . . . . . . . . . . . . 54 database sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 database specic code . . . . . . . . . . . . . . . . . . . . . . . . 57 database transactions . . . . . . . . . . . . . . . . . . . . . . . . 67
E
eager load collections . . . . . . . . . . . . . . . . . . . . . . . . . 33 eager versus lazy collection . . . . . . . . . . . . . . . . . . . 34 empty foreign collection . . . . . . . . . . . . . . . . . . . 34, 63 enable object cache . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Entity annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Enum integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Enum string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 enumerated name unknown . . . . . . . . . . . . . . . . . . . . 7 enumerated types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 equals, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 escaping arguments . . . . . . . . . . . . . . . . . . . . . . . . . . 46 examples of code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 exceptions, runtime . . . . . . . . . . . . . . . . . . . . . . . . . . 53 execute native SQL . . . . . . . . . . . . . . . . . . . . . . . . . . 29 execute raw sql statements . . . . . . . . . . . . . . . . . . . 32 executing raw select statements . . . . . . . . . . . . . . . 62 EXISTS, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 external data sources . . . . . . . . . . . . . . . . . . . . . . . . . 18 external dependencies . . . . . . . . . . . . . . . . . . . . . . . . 66
Index of Concepts
84
6 September 2013
F
eld access using getters and setters . . . . . . . . . . . . 7 eld conguration example . . . . . . . . . . . . . . . . . . . 78 eld indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 eld type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 eld width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 12 oat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 foreign auto refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 foreign collection column name . . . . . . . . . . . . . . . 34 foreign collection, empty . . . . . . . . . . . . . . . . . . . . . 63 foreign collection, ordered . . . . . . . . . . . . . . . . . . . . 34 foreign collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 foreign collections example . . . . . . . . . . . . . . . . . . . 78 foreign column name . . . . . . . . . . . . . . . . . . . . . . . . . 11 foreign eld querying . . . . . . . . . . . . . . . . . . . . . . . . . 33 foreign object refreshing . . . . . . . . . . . . . . . . . . . . . . 33 foreign object, auto create . . . . . . . . . . . . . . . . . . . . 10 foreign object, auto refresh . . . . . . . . . . . . . . . . . . . . 9 foreign objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7, 32 foreign objects example . . . . . . . . . . . . . . . . . . . . . . 78 foreign objects, creating . . . . . . . . . . . . . . . . . . . . . . 32 foreignAutoCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 format, eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
HSQLDB database . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
I
ibatis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Id annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 id column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19, 24 id eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 12 identity columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 identity eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 if id exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 IN sub-query, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 IN, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 index creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 index name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 indexing elds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 inner join queries, building . . . . . . . . . . . . . . . . . . . 47 inner join query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 inner queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 int . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 IS NOT NULL, SQL . . . . . . . . . . . . . . . . . . . . . . . . . 44 IS NULL, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 iterating through all rows . . . . . . . . . . . . . . . . . . . . 27 iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27, 61 iteratorRaw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
G
garbage collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 ge, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 generated id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 generated id sequence . . . . . . . . . . . . . . . . . . . . . . . . . 6 generated identity eld . . . . . . . . . . . . . . . . . . . . . . . 25 generated identity sequence name . . . . . . . . . . . . . 25 generated-id optional . . . . . . . . . . . . . . . . . . . . . . . . . 10 generatedId column . . . . . . . . . . . . . . . . . . . . . . . . . . 25 generatedIdSequence column . . . . . . . . . . . . . . . . . . 25 GeneratedValue annotation . . . . . . . . . . . . . . . . . . . 12 generation of the schema . . . . . . . . . . . . . . . . . . . . . 55 GenericRawResults . . . . . . . . . . . . . . . . . . . . . . . . . . 29 get and set method usage . . . . . . . . . . . . . . . . . . . . . . 7 getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 greater than or equal, SQL . . . . . . . . . . . . . . . . . . . 43 greater than, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 group by columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 group by raw SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 GROUP BY, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 gt, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
J
java annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 java date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 java long date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 java string date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 java.sql.Date type . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 javax.persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 jdbc dao implementation . . . . . . . . . . . . . . . . . . . . . 19 JDBC examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 jdbc type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 JdbcConnectionSource . . . . . . . . . . . . . . . . . . . . . . . 17 Joda DateTime type . . . . . . . . . . . . . . . . . . . . . . . . . 17 join queries, building . . . . . . . . . . . . . . . . . . . . . . . . . 47 join query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 join query, example . . . . . . . . . . . . . . . . . . . . . . . . . . 47 JoinColumn annotation . . . . . . . . . . . . . . . . . . . . . . 13 JPA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11, 66
H
H2 database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 H2 examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 having raw SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 hibernate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 how to download the jars . . . . . . . . . . . . . . . . . . . . . . 2 how to get started . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 how to upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 how to use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 how to use the query builder . . . . . . . . . . . . . . . . . . 37
K
key eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 12
Index of Concepts
85
6 September 2013
L
last modied eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 lazy load collections . . . . . . . . . . . . . . . . . . . . . . . . . . 33 lazy load elds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 left join query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 length of eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 12 less than or equals, SQL . . . . . . . . . . . . . . . . . . . . . . 44 less than, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 level 1 cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 LIKE, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 limiting eager foreign collections . . . . . . . . . . . . . . 34 limiting foreign auto-refresh levels . . . . . . . . . . . . . . 9 list of objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 log4j properties le . . . . . . . . . . . . . . . . . . . . . . . . . . 65 logging information . . . . . . . . . . . . . . . . . . . . . . . . . . 65 logging sql arguments . . . . . . . . . . . . . . . . . . . . . . . . 66 logging under Android . . . . . . . . . . . . . . . . . . . . . . . 52 long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 long string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 LRU cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 LruObjectCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 lt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
O
object cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 object cache, clear . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 object cache, enable . . . . . . . . . . . . . . . . . . . . . . . . . . 64 object mapping for select star . . . . . . . . . . . . . . . . . 64 object relational mapping . . . . . . . . . . . . . . . . . . . . . 1 ODBC database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 oset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 OneToOne annotation . . . . . . . . . . . . . . . . . . . . . . . . 13 open source license . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 optional generated-id . . . . . . . . . . . . . . . . . . . . . . . . . 10 OR, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Oracle database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 order by columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 order by raw SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 ORDER BY, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 ordered foreign collection . . . . . . . . . . . . . . . . . . . . . 34 other data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 overriding how data is stored . . . . . . . . . . . . . . . . . 70
P
parse format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 partial elds returned . . . . . . . . . . . . . . . . . . . . . . . . 41 persist objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 persisted eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 persisted types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 persisting an object . . . . . . . . . . . . . . . . . . . . . . . . . . 26 pooled connection source . . . . . . . . . . . . . . . . . . . . . 17 Postgres database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 prepare the query . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 prepared statement . . . . . . . . . . . . . . . . . . . . . . . . . . 37 primary key eld . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 12 primitive null values . . . . . . . . . . . . . . . . . . . . . . . . . . 7
M
mac function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 many to many example . . . . . . . . . . . . . . . . . . . . . . . 78 ManyToOne annotation . . . . . . . . . . . . . . . . . . . . . . 13 map raw query objects . . . . . . . . . . . . . . . . . . . . . . . 30 map select starquery . . . . . . . . . . . . . . . . . . . . . . . . . 64 matching object . . . . . . . . . . . . . . . . . . . . . . . . . . 59, 60 maven conguration . . . . . . . . . . . . . . . . . . . . . . . . . 69 max eager foreign collection level . . . . . . . . . . . . . . 34 max foreign auto-refresh level . . . . . . . . . . . . . . . . . . 9 Microsoft ODBC database . . . . . . . . . . . . . . . . . . . . 21 Microsoft SQL Server database . . . . . . . . . . . . . . . 21 modied last eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 multiple elds unique . . . . . . . . . . . . . . . . . . . . . . . . . 8 MySQL database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Q
query arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . query builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . query builder basics . . . . . . . . . . . . . . . . . . . . . . . . . . query for aggregate functions . . . . . . . . . . . . . . . . . query for all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . query for all raw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . query for eld value map . . . . . . . . . . . . . . . . . . . . . query for rst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . query for id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26, query for matching object . . . . . . . . . . . . . . . . . 59, query for number . . . . . . . . . . . . . . . . . . . . . . . . . . . . query for objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . query for single value . . . . . . . . . . . . . . . . . . . . . . . . query raw columns . . . . . . . . . . . . . . . . . . . . . . . . . . . query single number . . . . . . . . . . . . . . . . . . . . . . . . . QueryBuilder methods . . . . . . . . . . . . . . . . . . . . . . . QueryBuilder, raw queries . . . . . . . . . . . . . . . . . . . . queryForAllRaw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 60 37 42 59 62 60 59 59 60 30 60 59 42 30 40 29 29
N
name of database column . . . . . . . . . . . . . . . . . . . . . . 6 naming a unique index . . . . . . . . . . . . . . . . . . . . . . . . 9 naming an index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 native queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 ne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Netezza database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 no argument constructor . . . . . . . . . . . . . . . . . . . . . 13 not equal to, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 NOT IN sub-query, SQL . . . . . . . . . . . . . . . . . . . . . 44 NOT IN, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 NOT, SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 null comparison, SQL . . . . . . . . . . . . . . . . . . . . . . . . 44 null value allowed . . . . . . . . . . . . . . . . . . . . . . . . . 6, 12
Index of Concepts
86
6 September 2013
queryForEq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . queryForFieldValues . . . . . . . . . . . . . . . . . . . . . . . . . queryForFieldValuesArgs . . . . . . . . . . . . . . . . . . . . . queryForMatching . . . . . . . . . . . . . . . . . . . . . . . . . . . queryForMatchingArgs . . . . . . . . . . . . . . . . . . . . . . . queryForSameId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . querying for foreign elds . . . . . . . . . . . . . . . . . . . . . quotes in queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
59 60 60 59 60 60 33 46
R
raw columns, query . . . . . . . . . . . . . . . . . . . . . . . . . . 42 raw execute statements . . . . . . . . . . . . . . . . . . . . . . . 32 raw queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 raw query object[] . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 raw query using QueryBuilder . . . . . . . . . . . . . . . . 29 raw row mapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 raw select statements . . . . . . . . . . . . . . . . . . . . . . . . 62 raw SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . 29 raw update statements . . . . . . . . . . . . . . . . . . . . . . . 31 raw where statement . . . . . . . . . . . . . . . . . . . . . . . . . 45 RawResults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 ReferenceObjectCache . . . . . . . . . . . . . . . . . . . . . . . 68 refreshing an object . . . . . . . . . . . . . . . . . . . . . . 26, 61 refreshing foreign objects . . . . . . . . . . . . . . . . . . . 7, 33 remote objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 remove tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 reset Where object . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 reusing DAOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 reverse polish notation . . . . . . . . . . . . . . . . . . . . . . . 39 roll back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 row mapping for select star . . . . . . . . . . . . . . . . . . . 64 row versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 RPN queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 RuntimeExceptionDao . . . . . . . . . . . . . . . . . . . . . . . 53
SQL Date type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 SQL injection bugs . . . . . . . . . . . . . . . . . . . . . . . . . . 46 SQL Server database . . . . . . . . . . . . . . . . . . . . . . . . . 21 SQL statements, raw . . . . . . . . . . . . . . . . . . . . . . . . . 29 SQL Timestamp type . . . . . . . . . . . . . . . . . . . . . . . . 17 SQL type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 SQLExceptionDao . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 sqlite alter table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 SQLite database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 starting code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 startup optimization . . . . . . . . . . . . . . . . . . . . . . . . . 50 statement builder . . . . . . . . . . . . . . . . . . . . . . . . 37, 60 storing custom data types . . . . . . . . . . . . . . . . . . . . 70 String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 string byte array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 string quoting in queries . . . . . . . . . . . . . . . . . . . . . . 46 STRING BYTES . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 sub-queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 SUM, using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 supported databases . . . . . . . . . . . . . . . . . . . . . . . . . . 1
T
table columns comparing . . . . . . . . . . . . . . . . . . . . . 46 table cong le . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 table creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 TableCreator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23, 55 TableUtils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 throwIfNull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 time row last modied . . . . . . . . . . . . . . . . . . . . . . . 11 Timestamp, SQL type . . . . . . . . . . . . . . . . . . . . . . . . 17 TransactionManager . . . . . . . . . . . . . . . . . . . . . . . . . 67 transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 types that are persisted . . . . . . . . . . . . . . . . . . . . . . 14
S
saving an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 schema creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 schema generation . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 schema upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 select arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 select columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Serializable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 setting up the DAO . . . . . . . . . . . . . . . . . . . . . . . . . . 19 setting up your classes . . . . . . . . . . . . . . . . . . . . . . . . 5 short . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 simple connection source . . . . . . . . . . . . . . . . . . . . . 17 simple example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 soft reference cache . . . . . . . . . . . . . . . . . . . . . . . . . . 68 spring example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 spring examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 spring framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 spring wire a class . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 sql ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 sql argument logging . . . . . . . . . . . . . . . . . . . . . . . . . 66
U
unicode strings, storing . . . . . . . . . . . . . . . . . . . . . . . 14 unique constraint . . . . . . . . . . . . . . . . . . . . . . . . . . 8, 12 unique index creation . . . . . . . . . . . . . . . . . . . . . . . . . 8 unique index name . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 unique, multiple elds . . . . . . . . . . . . . . . . . . . . . . . . . 8 uniqueCombo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 unknownEnumName . . . . . . . . . . . . . . . . . . . . . . . 7, 16 update an object id . . . . . . . . . . . . . . . . . . . . . . . . . . 61 update builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 update custom statement . . . . . . . . . . . . . . . . . . . . . 61 update identity of object . . . . . . . . . . . . . . . . . . . . . 24 update with raw sql . . . . . . . . . . . . . . . . . . . . . . . . . . 31 updateBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 updateId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 updating an object . . . . . . . . . . . . . . . . . . . . . . . 26, 61 updating database schema . . . . . . . . . . . . . . . . . . . . 54 upgrading database schema . . . . . . . . . . . . . . . . . . . 54 upgrading from previous versions . . . . . . . . . . . . . 72 usage example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 use with Android OS . . . . . . . . . . . . . . . . . . . . . . . . . 49 use with external data source . . . . . . . . . . . . . . . . . 18
Index of Concepts
87
6 September 2013
useGetSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 using get and set methods . . . . . . . . . . . . . . . . . . . . . 7 using the DAOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 UUID type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
V
VARCHAR string . . . . . . . . . . . . . . . . . . . . . . . . . . . Version annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . version eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . versions, upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . 14 13 10 72
where . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 where method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 where methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 where to get new jars . . . . . . . . . . . . . . . . . . . . . . . . . 2 width of eld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 12 wrapped iterable . . . . . . . . . . . . . . . . . . . . . . . . . 27, 62 writing an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
X
Xerial SQLite driver . . . . . . . . . . . . . . . . . . . . . . . . . 20
W
weak reference cache . . . . . . . . . . . . . . . . . . . . . . . . . 68
Z
Zentus SQLite driver . . . . . . . . . . . . . . . . . . . . . . . . . 20