re: Empire-db version 3.0.0 / Quick migration guide from version 2.x to 3.0

[Rainer Döbele <do...@esteam.de>]

Hi Jan,

thanks for asking. 
Below you will find my "quick and dirty" migration guide.

It's not complete since the changes are too many.
However it should all be a strait forward process and the compile will guide the way ;-) 
And if you are really stuck, then you can always ask me.

So here's what you should do:
--------------------------------------------------------------------------------------------------------------------
Step 1:
In Version 2.x the DMBS specifics where handled by a class derived from DBDatabaser driver.
Never liked the name, since it confuses with the JDBC Driver (which is a real driver).

The class DBDatabaseDriver has now been renamed and split into an interface DBMSHandler and an abstract implementation DBMSHandlerBase. 
The base package for all DBMSHanders has been changed to org.apache.empire.dbms.

You can do that.

Replace:	org.apache.empire.db.DBDatabaseDriver
With:		org.apache.empire.dbms.DBMSHandler

Replace:	extends DBDatabaseDriver
With:		extends DBMSHandlerBase

For PostgreSQL you now want to use the class
org.apache.empire.dbms.postgresql.DBMSHandlerPostgreSQL

Also affects DBDriverFeature which is now dbms.DBMSFeature.

--------------------------------------------------------------------------------------------------------------------
Step 2:
This is probably the most severe change in term of API calls:
In Version 2 we have always passed a JDBConnetion as function parameter for functions that interacted with the database.
Instead of directly providing a JDBConnetion to methods and functions you now need a context that implements the DBContext interface.

The context provides access to the DBMSHandler and the JDBC Connection. 
It also provides methods for transaction management (commit and rollback) and command execution plus access to database utilities (DBUtils) which provide further convenient query methods.

The idea is that you provide your own Context and extend it with e.g. User or credentials information.
But  there are two implementations of DBContext already provided which can also be extended.

For simple applications the DBContextStatic class can be used.
And for JSF WebApplications the implementation class WebDBContext may be used (and extended)
If you don’t like both of them, then your own implementations should be derived from DBContextBase for convenience.

Passing a JDB-Connection is now obsolete in most cases. 
For DBRecord for example it is now only:
record.create();
record.read(key);
record.upate()
record.delete()

Hence what you can do is:

Replace:	, Connection conn)
With:		)

Replace:	, conn)
With:		)

Please also take a look at the empire-db-example-basic (DBContextStatic) and  empire-db-example-jsf2 (WebDBContext).

--------------------------------------------------------------------------------------------------------------------
Step 3:
All execute methods previously implemented in DBDatabase have been moved to the  DBContext like
executeSQL, executeInsert, executeInsertInto, executeUpdate and executeDelete.

All query methods previously implemented in DBDatabase have been moved to the new class DBUtils like e.g.
querySingleValue, querySimpleList, queryObjectList, etc.

Access to these functions is via the context like e.g.
context.executeUpdate(cmd)
context.getUtils().querySingleInt(cmd)

The DBUtils class may be extended with more user defined functions.
For this you may override the protected method DBContextBase.createUtils()

--------------------------------------------------------------------------------------------------------------------
Step 4:
The class DBRecord now requires a context as well as a rowset (table, view, query) to be provided with the constructor.

Before	After
DBRecord rec = new DBRecord();	-->	DBRecord rec = new DBRecord(context, table) ;
rec.read(table, key, conn) ;		-->	rec.read(key) ;
rec.update(conn) ;			-->	rec.update();

However you can also use the class DBRecordBean which has a default constructor and expects a context with all CRUD methods.

Similarly the class DBReader now requires a context to be provided with the constructor.

Before	After
DBReader reader = new DBReader ();	-->	DBReader reader = new DBReader(context) ;
reader.open(cmd, conn) ;		-->	reader.open(cmd) ;

--------------------------------------------------------------------------------------------------------------------
Step 5:
For Record the getValue() and setValue() function names have change to just get() and set()

Record.getValue(Column) 	-> Record.get(Column)
Record.setValue(Column) -	-> Record.set(Column)

Also set() now returns a this pointer so set method calls can be nicely chained:
model.create().set(MODEL.BRAND_ID, idVW).set(MODEL.NAME, "Golf").set(MODEL.CONFIG_NAME, "Golf Style 1,5 l TSI").set(MODEL.TRIM, "Style").update();

--------------------------------------------------------------------------------------------------------------------
Step 6:
Finally we got a nasty one:
Many methods of DBCommand and DBRecord have been changed to return "this" in order to allow method chaining.
This is generally not an issue as most methods returned void before.

There is one exception however:
The join(...) methon on DBCommand previously returned as Join Object.
You were then able set further join constraints by calling where(...) on this join Object.
Now the join() method returns a "this" pointer, hence the DBCommand object itself.

DBColumnJoinExpr join() ->	DBCommand join()

This is actually a big issue since both classes have a where(DBCompareExpr) method with the same parameter. 
The compiler does not report an error but the result is different!

So what you need to look out is for something like this:
cmd.join(EMPLOYEE.ID, PAYMENT.EMPLOYEE_ID, DBJoinType.LEFT).where(PAYMENT.YEAR.is(lastYear));
with this:
cmd.join(EMPLOYEE.ID, PAYMENT.EMPLOYEE_ID, DBJoinType.LEFT, PAYMENT.YEAR.is(lastYear));
or even better:
cmd.joinLeft(EMPLOYEE.ID, PAYMENT.EMPLOYEE_ID, PAYMENT.YEAR.is(lastYear));

The same applies to when you added a second column with and() i.e.
cmd.join(EMPLOYEE.ID, PAYMENT.EMPLOYEE_ID, DBJoinType.LEFT).and(PAYMENT.YEAR, REPORT.YEAR);
you now say:
cmd.join(EMPLOYEE.ID, PAYMENT.EMPLOYEE_ID, DBJoinType.LEFT, PAYMENT.YEAR.is(REPORT.YEAR));

But in this second case, at least the compile will report an error.
--------------------------------------------------------------------------------------------------------------------

In the end it is quite a bit of work, but believe me, it is worth it.
Nothing has been removed so you will be able to replace everything.
And except for this last part (Step 6) there are not many things that can go wrong as the compiler will tell you where there is work to do.

Please let me know if this was helpful.

Regards,
Rainer


----- Original message -----
from: Jan Glaubitz <ja...@glaubitz.org> 
to: dev <de...@empire-db.apache.org>
Cc: empire-db-dev@empire-db.apache.org; user@empire-db.apache.org; private@empire-db.apache.org
subject: Re: Empire-db version 3.0.0 state of development / Migration of modules


Hello Rainer,

sounds and looks interesting!

I’d like to try it out with my existing projects. Can you provide a small migration guide / getting started guide?

I’m using PostgreSQL and have some postgres-specific functions implemented. I hope I can get them work again ;)

- jan

> Am 14.02.2022 um 18:23 schrieb Rainer Döbele <do...@esteam.de>:
> 
> Hi all,
> 
> as announced I have started working on Empire-db version 3.0.0 in order modernize it for the 2020s.
> I am happy to announce that I have reviewed and optimized almost every part and it looks awesome in my opinion.
> At the start I would have not imagined that there was so much potential.
> 
> Empire-db 3.0 rocks!
> 
> To get more information look at the Jira tickets EMPIREDB-362 to EMPIREDB-372.
> Or even better, get the "version3" branch from git (https://gitbox.apache.org/repos/asf/empire-db.git ) and run the examples.
> 
> A lot of classes and function have been renamed, removed or altered.
> Migrating code from projects using the version 2.x branch is possible but requires some work and attention.
> (I might do a migration guide later)
> 
> I am planning on merging the version3 branch with the head in the coming days.
> Any objections anyone?
> 
> Now about the modules:
> The following modules have been update to version 3:
> 
> Apache Empire-db Core ..............................
> Apache Empire-db Java Server Faces 2.x extensions ..
> Apache Empire-db Code Generator ....................
> Apache Empire-db Maven Plugin ......................
> Apache Empire-db Maven Codegen Example .............
> Apache Empire-db Basic Example .....................
> Apache Empire-db Advanced Example ..................
> Apache Empire-db JSF2 Example ......................
> Apache Empire-db Vue.js Example ....................
> 
> However, I have NOT converted any of the following modules:
> 
> Apache Empire-db CXF Example .......................
> Apache Empire-db Spring JDBC Template ..............
> Apache Empire-db Spring Example ....................
> Apache Empire-db Struts2 Extension .................
> Apache Empire-db Struts2 Example ...................
> Apache Empire-db Struts2/CXF Example ...............
> 
> Originally the Stuts2 Extensions had been provided by me, but I am not planning on continuing Struts2 support myself.
> As I have no experience with Spring, I am unable to do the migration myself. Same with CXF.
> 
> So what should we do with this leftover modules?
> Anyone willing to convert them to version 3?
>