6. Upgrade From Old Versions

We strive to maintain backwards compatibility and to provide deprecated versions of old classes and methods. However, sometimes when a new version is released, changes are made that require programmers to change their code and rarely the on-disk database formats.

6.1 Notes About Version 5.0

A number of things have changed and it’s been a long time since the last published ORMLite release, so a .0 number on the release seemed to be warranted. See the following details.

• ORMLite now requires Java 6 and no longer supports Java 5. We also added java.io.Closeable support for Java 7 and better support for Java 8 but they are not required.
• We used the native locale to do uppercase database entity names (tables and fields). This sounds like a good idea until you realize that in Turkish, a uppercase i with a dot is a capital I with a dot which can be incompatible with databases that don’t understand UTF8 names. For this reason the default behavior is to do capitalization of entities using Locale.ENGLISH. This means that your schema may need to change. To go back to the old behavior, you should override the appropriate DatabaseType and override the upCaseEntityName(String) method.
• We’ve added the usage of the java.io.Closeable interface in a number of places for Java 7 support. This means that you may not get warnings about unclosed iterators and other things. Watch for and pay attention to them. They are important. Java 7 is not required.
• To better support database partitioning, we made some changes to the ConnectionSource interface so now the table name is specified which allows the ConnectionSource to make decisions about which database to connect to depending on the table.
• We’ve made changes to Android to better support the java.sql.Timestamp and java.sql.Date as strings in the database. If you were using this types before you may have to add a persisterClass = TimeStampType.class or SqlDateType.class.
• We’ve removed a number of deprecated methods:
  • Dao.setAutoCommit(boolean), isAutoCommit()
  • QueryBuilder.clear(), limit(int), offset(int)
  • ForeignCollectionField.maxEagerForeignCollectionLevel(), foreignColumnName()
  • DatabaseFieldConfig.setMaxEagerForeignCollectionLevel(), setForeignCollectionMaxEagerForeignCollectionLevel(), setForeignCollectionOrderColumn(), setForeignCollectionForeignColumnName()
  • DataSourceConnectionSource.setUsesTransactions(boolean)
  • JdbcPooledConnectionSource.setUsesTransactions(boolean)
  • OpenHelperManager.release()
  • AndroidDatabaseResults(Cursor, boolean, ObjectCache) constructor

6.2 Notes About Version 4.49

The 4.49 release took a long time to put out unfortunately so it included a lot of changes, a couple of which need to be specifically enumerated. For more details, please check the change-log.

• Due to a couple of reporting issues, it was determined that some sort of locking was needed to protect concurrent usage of dao.callBatchTasks(...) calls from multiple threads when dealing with a single database connection. ORMLite now makes an attempt to detect a single-connection connection-source and will enforce locking so that only one batch task can be running at a time.
• A lot of changes were made to have CloseableIterator and other classes extend java.io.Closeable. If you are extending any of these classes then you may have to tweak your code.
• We fixed a problem with the maxForeignAutoRefreshLevel configuration setting which was particularly impacting Android users.

Again, please check the change-log for the entire list.

6.3 Upgrade to Version 4.45

To fix the date-string format bug introduced in version 4.43, I’ve decided to revert back to the date-string of yyyy-MM-dd HH:mm:ss.SSSSSS from the one introduced in 4.43 which was yyyy-MM-dd HH:mm:ss.SSS. This means that for folks doing date comparisons or using the version = true feature, if you have created data under 4.43 you will have to add the following to your date fields to make it work.

@DatabaseField(version = true, format="yyyy-MM-dd HH:mm:ss.SSS",
   dataType=DataType.DATE_STRING)
private Date date;

If you have data that was created both in 4.42 or before and 4.43 or 4.44 then you will have to convert some of the data. Something like the following UPDATE statement should work:

UPDATE your-table SET your-date-field =
    CONCAT(SUBSTRING(your-date-field, 1, 20), "000",
       SUBSTRING(your-date-field, 20, 3))
    WHERE LENGTH(your-date-field) = 23;

My sincere apologies for this mess up.

6.4 Problems With Version 4.43

In the process of looking into adding the timezone to the date-string, I made a change to the date-string format from yyyy-MM-dd HH:mm:ss.SSSSSS to yyyy-MM-dd HH:mm:ss.SSS – changing the milliseconds output from 6 digits to 3. This relatively small change broke the equality checking for date-strings which meant that Where.eq(...) and version = true field settings ceased to work correctly. The version processing code uses equality to verify that the object date is the same with the database and the new string value ...### is not equal to the old database format of ...######.

We have fixed this problem in 4.45 which reverts the string format. If you want to fix it permanently, you can use the format specifier on your date-string fields:

@DatabaseField(version = true, format="yyyy-MM-dd HH:mm:ss.SSSSSS",
   dataType=DataType.DATE_STRING)
private Date date;

My apologies for this problem.

6.5 Upgrade to Version 4.37

For Android users, in 4.37 we fixed a problem with the looking up of column names with imbedded periods in them by implementing our own lookup and not using the Android API. This had the unintended consequence of making the field name lookups be case sensitive. If you used ORMLite to generate your tables or if you used the @DatabaseField columnName to match the case then you would not be affected by this issue. But if you were working with an existing database with field names that did not match the case of the Java fields, then as of 4.37 you would be seeing the following exception.

java.sql.SQLException: Unknown field 'accountName' from the
    Android sqlite cursor, not in:[accountname, ...]"

Since other parts of the system are also case sensitive, we made the decision to not fix this problem but to encourage our users to properly use the @DatabaseField columnName if the case of your database does not match your Java fields. See columnName.

For example, before 4.37 your Android SQLite database might have the column accountname although your Java field might actually be accountName. As of 4.37, when you look up your Java fields you will have to add a columnName value like the following:

@DatabaseField(columnName = "accountname")
private String accountName;

We made the decision to force this change because there are other parts of ORMLite that are already case sensitive. For example, if you had mismatched case in your field names then using the dao.queryForMatching(obj) method would not work without the case matching the database. If you were building a custom query, you would have to say queryBuilder.where().eq("columnname", value) and could not use columnName.

Sorry for not recognizing this incompatibility earlier.

6.6 Upgrade to Version 4.30

For Android users, in 4.30 we added some reflection hacks to make the processing of the @DatabaseField annotations a lot faster. For this reason the following changes must be made:

• Instead of calling the annotation methods directly which causes tons of unnecessary GC objects, we use reflection and build a DatabaseTableConfig instead. This means that if you have defined custom Dao classes, you will need to add a new constructor:

  public class AccountDaoImpl extends BaseDaoImpl<Account, String> implements AccountDao { public AccountDaoImpl(ConnectionSource connectionSource) throws SQLException { super(connectionSource, Account.class); } // NOTE: this constructor is needed under Android in 4.30 public AccountDaoImpl(ConnectionSource connectionSource, DatabaseTableConfig<Account> tableConfig) throws SQLException { super(connectionSource, tableConfig); } }

• Because we had to write specific code to reflect 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.

6.7 Upgrade to Version 4.20

In 4.20 we made a couple of changes that bear some note.

• For Android developers, we significantly improved the mechanism for injecting the class of the database open helper. Setting the class name in the strings.xml resource file is still supported although it is not necessary if you are using OrmLiteBaseActivity or the other base classes. If you are extending those classes, ORMLite will detect the helper class automagically. The SqliteOpenHelperFactory mechanism, although still supported, has been deprecated. See database open helper wiring.
• We added the uniqueCombo setting for uniqueness across field combinations. We also changed the SQL that was generated if you are using the unique setting. The old SQL was correct but the new versions are more compatible with the SQL standard and the various database types. See unique constraints.
• We did some memory audits of ORMLite and improved the way that we were using DAOs internally so that we use cached DAOs where possible. We also improved the memory usage with foreign fields and some of the TableUtil methods. Thanks much to various folks on the user list who significantly helped with this process.

6.8 Upgrade to Version 4.14

In 4.14 we added a DatabaseType.BYTE_ARRAY which stores byte[] directly. See BYTE_ARRAY. In the past, this array would have been stored as a serialized array of bytes. To not break backwards compatibility with the database, fields with the byte[] type must now specify either the BYTE_ARRAY or SERIALIZABLE types using the dataType field on @DatabaseField – it will not be chosen automatically. See DatabaseField dataType. If we did not do this then previously stored data would be read from the database improperly.

In addition, serialized types must also now specify their dataType value. You should use DataType.SERIALIZABLE to continue to store serialized objects in the database. This will allow us to add direct support for other serialized types in the future without breaking backwards compatibility.

If you already have Serializable data (byte[] or other objects) stored in a database then you will need to add something like the following to your fields:

@DatabaseField(dataType = DataType.SERIALIZABLE)
Serializable field;

For newly stored byte[] fields, you could use the BYTE_ARRAY type to store the bytes directly. But any existing data will not be converted automatically.

@DatabaseField(dataType = DataType.BYTE_ARRAY)
byte[] field;

6.9 Upgrade to Version 4.10

4.10 was a reasonably large release containing some feature upgrades and some bug fixes. No data formats were changed, however the following API code was altered:

• We significantly refactored the RawResults class which is now deprecated and replaced it with the GenericRawResults class. See the GenericRawResults for more information. See section Issuing Raw Queries.
• The Dao methods queryForAllRaw() and iteratorRaw() are now deprecated. They are replaced with queryRaw(...) methods. See the Dao class javadocs for more information.
• Before this release the -jdbc and -android versions of ORMLite contained the -core functionality. In this release we split out the -core from the other packages so you will now need to install both the core and android (or jdbc) packages to get the package to work.

6.10 Upgrade to Version 4.0

No data formats were changed, however the following API code was altered. Removed any outside usage of the DatabaseType since the ConnectionSource now provides it. Also added features to be able to prepare update and delete statements. To provide type safety, we’ve moved back to using QueryBuilder so we can have UpdateBuilder and DeleteBuilder. And instead of a PreparedStmt there is PreparedQuery, PreparedUpdate, and PreparedDelete. Here are the details:

• We have removed most of the cases where the user has to deal with the DatabaseType. All you need to set on the DAOs is the ConnectionSource which provides the database type internally. To create and drop the tables, also, you only need the ConnectionSource.
• Constructing a BaseDaoImpl now self-initializes if it is constructed with a ConnectionSource. This validates the class configurations meaning that it now throws a SQLException.
• Constructing a JdbcConnectionSource or DataSourceConnectionSource also now throws a SQLException since they also now self-initialize if they are constructed with the URL. This creates the internal database type and loads the driver class for it.
• Deprecated the createJdbcConnectionSource method in the DatabaseTypeUtils and turned the loadDriver method into a no-op. You now just instantiate the JdbcConnectionSource directly and there is no need for referencing the DatabaseTypeUtils anymore.
• Dao.statementBuilder() method changed (back) to Dao.queryBuilder().
• Dao.queryBuilder() returns a QueryBuilder instead of a StatementBuilder.
• You now call distinct(), limit() and offset() on the QueryBuilder. Unfortunately, there are no deprecated methods for them on the StatementBuilder.
• 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 configurations.
• Removed BaseJdbcDao since it had been deprecated in 3.X.

6.11 Upgrade to Version 3.2

The 3.2 release involved a very large code reorganization and migration. There were no on-disk changes unless you somehow managed to get ORMLite working previously on Android. The project was basically split into 3 pieces: core functionality, JDBC database handlers, and the new Android handler. With significant help from Kevin G, we abstracted all of the database calls into 3 interfaces: ConnectionSource (like a DataSource), DatabaseConnection (like a Connection) and DatabaseResults (like a ResultSet). Once we had the interfaces in place, we wrote delegation classes for JDBC and Android handlers. This means that as of 3.X we release 3 packages: ormlite-core (for developers), ormlite-jdbc (for people connecting to JDBC databases), and ormlite-android (for Android users). Both the JDBC and Android packages include all of the core code as well.

Along the way a number of specific changes were made to the methods and classes:

• Since we split off the JDBC, we renamed the BaseJdbcDao to be BaseDaoImpl in the core package. You will need to adjust any DAOs that you have.
• We are in the process of allowing custom delete and update methods so we took the major upgrade opportunity to rename the QueryBuilder object to be StatementBuilder. NOTE: this was reverted later.
• Because of the above, we also renamed Dao.queryBuilder() method to be statementBuilder(). NOTE: this was reverted later.
• Also renamed the PreparedQuery object to be PreparedStmt.
• One of the big changes for those of you using an external JDBC DataSource is that you no longer set it on the DAO directly. You need to wrap your DataSource in a DataSourceConnectionSource wrapper class which gets set on the DAO instead.

Again, there were no on-disk changes unless you somehow managed to get ORMLite working previously on Android. Since we were using JDBC before to do the data marshaling and now are doing it by hand, some of the data representations may have changed. Sorry for the lack of detail here.

6.12 Upgrade to Version 2.4

A bug was fixed in 2.4 with how we were handling Derby and Hsqldb. Both of these databases seem to be capitalizing table and field names in certain situations which meant that customized queries of ORMLite generated tables were affected. In version 2.4, all tables and field 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 find the tables and fields without renaming to be uppercase.

This document was generated by Gray Watson on July 27, 2016 using texi2html 1.82.