The benefits of using Java in these environments is I can package my program as a Runnable Jar easily through Eclipse's Export functionality. I also have a wonderful wealth of libraries for doing almost anything I want -- from FTP libraries, to any Database driver I can dream of. Anyone who's had to deal with the freetds library in perl to connect to a MS SQL database knows what a huge boon being able to use JDBC is.

The cons of using Java is my code is not as terse as it could be, and for common scripting tasks like reading and writing files and database records a simple task now becomes tons of boiler plate exception handling and JDBC calls. I also have to re-compile and re-package my entire program if I want to make a simple change.

What if we could harness the power of any Java Library we wanted, no hassle deployment, but marry the simplicity of a scripting language and flexibility of an interpreted language?

Enter Groovy

Hello world in groovy:

Iterating over an oracle record set in Groovy:

I don't want to go into the groovy language, that's another topic, but I think it's obvious that for simple tasks Groovy is superior to Java.

There are many ways to Run Groovy Scripts. However, I want a way to run a script without having to install the Groovy Runtime.

Ideal situation:

• Develop Groovy script in Eclipse
• Export Groovy Runtime as Runnable Jar from Eclipse Project
• Upload Runnable Jar and Groovy Script to Any Server with a JRE
• Run runnable jar server, by specifying path to groovy script

This gives me the flexibility of being able to use my favorite IDE, and easily run and change my script on any other machine with a JRE.

If you'd like you can also download the finished GroovyLauncher eclipse project.

Developing Groovy Scripts in Eclipse
You'll should have a recent version of Eclipse and the Groovy Plugin. To create a new project, simply start a new Java Project, then create a new Groovy Class to add any classes/scripts you want to your project. It's important that you add one groovy script to this project even if it's just a simple hello world script, that will prompt Eclipse to add the Groovy Libraries jars to the build path of your project.

Now to run a groovy script in eclipse you just right click on the .groovy file and do "Run as Groovy Script", done and done. However, in order to run our script from a runnable jar we are going to need a Java Class with a Main method.

Launching A Groovy Script with the Groovy Shell

The GroovyShell class is a handy Java Class that can run any Groovy Script passed into it's Main method. We're going to wrap this class in our own Main class called GroovyLauncher.

So I just make a new Java Class called GroovyLauncher and tell eclipse to create a main method for it.

The class looks like this:

So this class will be the Main Class we tell Eclipse to use when creating an exportable jar. This class does nothing inside of eclipse, because it expects the path to a groovy script to be passed into it from the command line. We'll only use this Main class when launching from our deployed location.

In order to create a Runnable Jar from an Eclipse Project we need to create a LaunchConfiguration, the quickest way to do that is just to right click on our GroovyLauncher class and do Run as Java Application. When run it will display some GroovyShell error messages because we didn't pass in any arguments. That's fine, we just want Eclilpse to create a default Launch Configuration for the class.

Now right click on your project and select "Export" in the next dialog choose Runnable Jar.

In the next dialog we need to select the Launch Configuration to use (this is the Main class that the Jar will use when run).

Pull down the drop down and you should see your GroovyLauncher Run Configuration that was created automatically by Eclipse when we tried to run our GroovyLauncher class.

Now just specify the file name for the jar and we're done. What eclipse does during the next step is repackage all the classes from your Build Path into one single jar file. So if we included mysql jdbc drivers in our build path, they'd be repackaged into our own jar. This is a legal gray area, but it's damn cool and simple. We don't have to worry about classpaths anymore when we launch our jar! We just run it with "java -jar filename.jar"

So now to test our GroovyLauncher jar we can run it on our machine or another by running:

Now we can pass in ANY groovy script we want using this same launcher jar, it can reference any Java class that was in our BuildPath of our eclipse project. If you didn't add anything other than the Groovy Libraries you'll just have access to the core Groovy Libraries + the Java API's, if you want to be able to do SQL and other fun stuff you'll need to add the appropriate jars to your Eclipse Project just like normal.

Conclusion
You might make a couple different Runnable Jars based on different needs. You could create a project that just included the Groovy Libraries and the GroovyLauncher class and maybe export that as GroovyLauncherLight.jar and make another project that has your favorite JDBC drivers plus any other common libraries and export that project as GroovyLauncherFull.jar

A word of warning, I haven't benchmarked using the GroovyShell versus the GroovyLauncher, however most of your swiss army type scripts don't need to be blazing fast, they just need to be easily changed and easy to run.

Bookmark to:

I found myself replacing a project's hideous System.out.println statements with log4j log calls.

Just do a File Search in eclipse , tick the regular expression box and do a Replace:

Now you just have to go in and add your imports and your log field variable to your classes.

Bookmark to:

It requires a derby database which you can download from here, simply run the startNetworkServer.bat in the bin directory to start it.

Introduction

Eclipselink is a part of the Eclipse Project. It's an ORM that implements the JPA 1.0 specification, the main commiters on the project are Oracle employees, and Eclipselink is based on the mature Toplink library, in fact Toplink is being renamed Eclipselink for future releases.

Why use JPA?

JPA is the official persistence specification for EJB 3, it's not going anywhere and you're going to have an easier time finding other developers who are familiar with the JPA specification. What's even better is the EclipseLink implementation is the JPA 2.0 reference specification, so there's a good chance some features you enjoy in the EclipseLink implementation will be present in the JPA 2 specification as well.

Why bother with an ORM?

When you're coding an RCP application, chances are you're already passing around Java Beans that represent your data model. If you could have the mapping take place automatically from your database to java beans, it just makes your life that much easier. Once you add the power of libraries like Jface Databinding it's hard to go back to any other method of data access.

Death to XML

Thankfully EclipseLink does not require much XML, the only xml file I create is a persistence.xml that simply lists all my entity classes. A nice editor is included with the JPA Tools plugin that makes managing it simple. All other configuration can be done via annotations.

Tons more after the Jump!

High Level Plug-in Architecture

I like to split my project into 2 main parts. You could put it all in one plugin, but this is how I do it.

UI

This plugin contains all my UI code. Views, Perspectices, Editors, etc. No data access code should occur here though. Instead we'll just use our model plugin. This isn't an RCP tutorial, so I'm going to assume you know your way around the base RCP classes and project set up.

The Model

The model plugin is where all the data access work takes place, from here we can separate 3 main concerns.

Connection Set Up (EntityManagerFactory)
The EclipseLink class that takes care of creating database connection, configuring pooling, or re-using an exisiting datasource as a connection is the EntityManagerFactory.

Configuring your EntityManagerFactory involves specificing the connection, and setting options. Once we're done, you guessed it, we can create EntityManagers!

The call to createEntityManagerFactory takes the name of your "persistence unit", it must match the name you put in your persistence.xml, so in this case it's "comics".

Here's the EntityManagerFactory I created for the Comics example:

Models (EntityManager Usage)
Once we have an EntityManagerFactory we can use that EntityManagerFactory to create an EntityManager. An EntityManager has it's own cache, handles all data access (selects/inserts/updates) and also can manage your transactions (commit/rollback).

I've found that I wrote the same code quite a bit: Obtain an EntityManager from my EntityManagerFactory, begin a transaction, commit a transaction, etc. Rather than write this same code over and over again I find it much easier to simply put this code in a base "Model" class.

I use two types of "Models", one type is your standard Read Only model, I call this class BaseModel, it has some convience methods like selectAll and getNamedQueryResults. The next type of Model I call an "EditorModel" (Because I mostly use it in editors). It has transaction management methods as well as a method called isDirty which can tell me if I have any changes pending to go in the current transaction. This is very useful for editors and any other place you want to do read/write stuff.

I either use these two classes on their own or I extend them to put business specific methods in them -- things like getAllEmployees(), etc.

Entities
An entity represents a persistent object in your database (usually a table or a view). In java terms they are POJO's (Plain Old Java Objects). I usually add property change support to them for use with the JFace Databinding library, but that's not required.

Example Entity (this one implements property change support, that's why I'm extending BaseEntityObject) :

Rememeber: Every entity defined in your model project must be referenced in your persistence.xml.

Generating Entities
The best way to generate your entities is with the Dali JPA Tools plugin, it's available on the standard eclipse update site. After you get Dali make sure you configure your drivers & connections for whatever platform your database uses - oracle,mysql, etc.

You cannot just use the JPA Tools plugin on any ol' project however. Though in the future this limitation will go away. First you must create a special "JPA Project" and immediately converting it to a plugin project.

Then you can then generate your entities by right clicking on your project and selecting JPA Tools->Generate Entities.

Common Gotcha - sharing Entities
When we're talking about OSGi, Entities can not pass the class loader boundry, so you cannot (at this time: September 2008) re-use entities between bundles. This just means the EntityManager you persist an entity with, must be in the same bundle. So I couldn't take common entities and put them in their own bundle, then expect to persist/select to them with an EntityManager defined in another bundle.

This isn't as much of a deal breaker as it sounds at first, you just have to violate DRY for Entity Classes, which aren't all that interesting in the first place. There's nothing stopping you from defining common interfaces or Abstract classes that entities from multiple bundles share.

Selects/Inserts/Updates/Deletes

So how do you do stuff with EclipseLink? Turns out, it's pretty simple. However there are so many different ways to do things, I don't have the room here to go over it. Please read this excellent wiki article to quickly get up to speed. Also any JPA Tutorial will get you caught up on the basics. I'd like to go over how all of this stuff pertains to your run of the mill RCP applications.

Editor Use Case

A common usage scenario with a database driven app is to use a FormEditor to modify a collection of entities. Thanks to EclipseLink we get lots of stuff for free, let's take a look at an example editor class.

Editor Initialization
The init method, here we want to get whatever entities we want to set up our Model, remember our Model basically wraps our EntityManager and contains some convenience methods for dealing with transactions, etc. We need to obtain all of our entities from the entity manager, usually through a simple select query.

So we create a new PublisherEditorModel, which is a simple class I created that handles starting my transaction, then we get our Publisher entity from the model, let's peak inside the PublisherEditorModel class, here we use call the find method on our entity manager, that method takes the class of our Entity and it's primary key.

So now we've got our Publisher Entity, but it's one we obtained from our EntityManager, that means any changes we make to the entity will be followed by the EntityManager. So if we changed a field, then called save on the EntityManager, an update statement would be sent to the database!

You could of course skip the convention of a model class all together and deal with getting the EntityManager directly from your plugin's EntityManagerFactory yourself, but it's much easier to just write that code once.

Checking for changes
One feature of an editor is a dirty state -- you change something, the editor is marked as dirty (A star is added to the editor title). If you save the changes, they go through, if not they're discarded. By using EclipseLink we get this functionality for free. No matter how complicated our model is. In basically one line of code we take care of what used to be a gigantic chore. Now figuring out exactly what the differences are is a bit more complicated, but for our case this works great.

Saving Changes
To save our changes we simply commit our transaction, then start a new one (so editing can continue). Once again, we haven't had to write a single line of SQL. This simple commit will handle, updates, inserts, deletes! This step used to cause me many hours of grief for each new editor, troubleshooting what sort of SQL I had to generate, and in what order. Don't get me wrong, sometimes EclipseLink doesn't generate the SQL you think it should, but it's usually fairly easy to debug what went wrong.

So, our entities we got from our entity manager we expose to our FormPages in the editor, we then bind those very entities to UI controls, either using JFace databinding or by hand -- whichever way you prefer.

Review
That's really all there is to tying a simple editor to a database. Let's review:

1. Obtain an EntityManager and begin a transaction
2. Obtain all the entities you need from the EntityManager, either through the find method, a JPQL query or a Native SQL Query, or combination of these methods.
3. Leverage EclipseLink's UnitOfWork class in your isDirty method.
4. In your form pages, bind Entities to UI controls.
5. Commit your transaction when save is called.

Caching in a Thick Client

Traditionally one of the major benefits you get when using an ORM library and with EclipseLink especially is the ability to have a shared in memory cache. The benefits in a server side web application are immense, when we're dealing with a client side thick application. Caching just gets in our way in most cases. The reason for this is obvious: In a web application EntityManagers across users sessions can all easily share the same cache, since they all reside on the same server (usually).

However in a thick client each user is an island. When I make an update to the database, I update my very own Shared Cache, however Mary who is sitting 2 cubes over still has her own cache that's oblivious to my changes. It's imperative that she receive fresh data all the time!

Fresh data from a find call
Calling find on the EntityManager is the easiest way to get a handle on an Entity. However, you're not gauranteed to hit the database on this call. After our find we just need to call refresh to refresh the Entity from the database. I created a method called findFresh that I put in my Base Model class, here's how it looks:

In EntityManager Setup
You can turn off the Shared Cache EntityManager wide, to stop regular JPQL queries from hitting the shared cache, this is called putting your EntityManager in "Isolated Mode", just set it in the properties map you pass to the createEntityManagerFactory method.

I just set the property like this:

Fresh results from Queries
Just to be sure when I execute any Query - Native or otherwise I set the Query Hint to not use the cache, I created a little helper method I through in a util class like this:

When dealing with NamedQueries you can use the @CacheHint annotation to set the hint.

Conclusion

Before using EclipseLink in my business critical RCP applications, we were using all home grown DAO. We successfully ported our old applications to EclipseLink in a matter of months and that was using alpha code. Looking back all the developers agree we couldn't live with out it. It's amazing what the simplicity of being able to focus on your actual business logic and not SQL generation can do to you, coding is fun again. Thanks EclipseLink!

Bookmark to:

Here's a code template you can use based on the cool trick I learned at Stuff That Happens

firePropertyChange("${enclosing_method_arguments}", this.${enclosing_method_arguments}, ${line_selection});

Just select the assignment part of your setter and use this template.

If you're really lazy you can use a regex find and replace (With the File Search Dialog)

Your Find string will be:
(this.+) = (\w+);

And your replace string will be:
firePropertyChange("$2", $1, $1 = $2);

Both of these solutions assume you use an Abstract BaseClass to set up your firePropertyChange stuff, then extend for each bean.

Mine looks like this:

Bookmark to:

http://jautodoc.sourceforge.net/update/

Screenshot:

Bookmark to: