back to Javelin Home

Javelin
Award Winning Point and Click, Visual Java Development Tool
Now with integrated support for Hibernate persistence!

Javelin: Working with Hibernate Tutorial

Introduction

The purpose of this tutorial is to demonstrate, in a few simple steps, how easy it is to persist object models developed visually in Javelin using the Hibernate O/R mapper. If you have never used Javelin before don't worry: it's learning curve is about 5 minutes - you're going to spend more time getting your Hibernate environment established!

Set up your Hibernate environment

The first step is to establish a working Hibernate environment. Download Hibernate from here, install and then run the test.

The second step is to learn what Hibernate is about so that you know how Javelin works with it. So work through this tutorial at least up to point 2.2.6. At this stage you will have established a separate hibernate work directory and an ant build.xml file which we will use and change slightly for our own needs.

Your work directory will look something like this:

.
+lib
  <Hibernate and third-party libraries>
+src
  Event.java
  Event.hbm.xml
  HibernateUtil.java
  hibernate.cfg.xml
+data
build.xml

You should also be at the stage where you can type:

ant run -Daction=store

ant run -Daction=list

to store and list objects to/from the database.

Creating a Javelin project

If Javelin is not running then launch it. You should see what appears to be a fairly simple user interface with a gray background (for reduced glare - which you can change of course). The application also appears to be lacking lots of "gadgets" and floating windows with icons representing lot's of weird and wonderful functions. You might be thinking, "how can something so clean and devoid of clutter actually have any significant functionality?" Don't let it's uncluttered appearance fool you - we have designed it like that on purpose to devote maximum real estate to your class diagrams as it's from here that you perform nearly all of your tasks. We actually call this window the slate. So in this step you're going to start with a clean slate!

We are going to create a new project: Click on the "New Project" button in the tool bar (it's the first button on the left). If it prompts to save the current project press 'No' if it's got nothing worth keeping.

Enter a project name like 'First Tutorial'. The other fields are self explanatory. The information you enter here will be included with every Java file that is generated or synchronized using Javelin. So this is a neat place to set up your copyright notice.

Make sure the Default package field is left blank! Hit Next.

Now click on the 'Change...' button and use the file dialog to point to the 'src' directory of the Hibernate directory structure that you set up in the Hibernate tutorial. Now type javhiber as the filename for your project. Click next and then click finish. Select the Hibernate persistence option and click Ok.

The file javhiber.vcm should now be located in your 'src' directory. The .vcm extension stands for "Visual Class Model".

Testing New Project

Now we are going to set up the compile and run options in preparation for our development. Under Debug select "Compile/Run Options...". Enter the values as shown below:

Compile command:

ant compile

Run command:

ant run -Daction=list

Press Ok.

Now if you select Debug > Run you should see a console window appear. This will invoke the ant make program and when finished will open up a text file to show you the results. You should see the same results as when you ran the run command via the command line in the Hibernate tutorial.

My first class

Now things are getting exciting - we're going to create a class but only after we destroy one! In Windows Explorer go the src directory and delete the files called Event.java and Event.hbm.xml.

Now we are going to recreate them - not the hard way but the easy way - with Javelin. Right click in the slate window somewhere around the middle and choose Add Class... Type 'Event' for the class name, leave the package field blank and add a description.

Adding Attributes - "Do you want fries with that?"

We will add the following two attributes

We do this via the "members" form. Right click on the Event class icon and choose "Members". You will see two sections: one for attributes and one for methods. Here's where you manage your attributes and methods and even gain direct access to the source code of individual methods. (Inheritance and association relationships are managed via connecting lines between classes but more on that later).

In the attributes section click "New". Type in 'title' as the name and String as the type and you can optionally write a description. Press 'Ok' and answer 'Yes' when it asks to automatically create getters and setters for your new attribute. This is similar to being asked "Do you want fries with that?". Quite often people say yes but you can never be sure so we just have to ask!

Javelin offers to automatically create a getter and setter after adding each new attribute so that your class conforms to the 'bean' standard. This bean standard is how Hibernate expects to manage the persistence of your objects once it has discovered their attributes via reflection. Don't worry if you didn't understand that last sentence - you don't need to understand how Hibernate works in detail when you're developing from the object modeling level in Javelin.

Repeat the above process to add the Date attribute. You should be starting to get glimpses of how Javelin is not merely a UML class diagramming tool but a high productivity development environment.

The java compiler needs to know about the Date type via a java 'import' statement. Before we add the import statement we must learn a little bit about how Javelin seems to magically keep your design 'in sync' with your code without you doing anything special to make it happen.

Javelin code synchronization

Whenever you make changes to your design from within Javelin it resynchronizes the underlying source files that are affected by that change. Unlike many heavyweight UML/coding tools when working with Javelin you do not need to explicitly "export" your code after making changes and then "import" when you want to go back the other way. You should never need to explicitly force a resynchronization of a source file but there may be times when this is useful - eg., if you have accidentally deleted a .java file you can get Javelin to regenerate it - minus the code in the bodies of your method - Javelin does not store code from method bodies in its database. It only stores design information like attributes, method signatures, relationships etc.,

The important thing to remember about Javelin's legendary "InSync" synchronization strategy is that certain sections in .java source files are preserved and others are overwritten. Preserved code sections are sections of your .java file in which you can make changes directly from external editors or from IDE's like Eclipse (make sure you save the changes because Javelin only sees what has been written to file). Changes made in preserved code sections will not be lost when Javelin resynchronizes your file at a later date. So you want to ensure that any code changes that you make directly to a source file from outside Javelin are made within "preserved" sections otherwise you will lose those changes. This may seem a little harsh but it is extremely easy to work with and has never been an issue for Javelin users. The benefit of allowing automatic, effectively zero time model-code synchronization far outweighs any issues of working only within preserved sections.

So what code sections are preserved? There are two types of preserved sections:

Ok, now back to the import statement needed for the Date class. We are going to add an import statement to the keep section before the class declaration. You could open an external editor and do this but its much faster to right click on the class and select "Edit 'Keep' section > before class declaration". Do this and add the following line then press 'Ok'.

import java.util.Date;

Why no identity field?

There's no need to add the identity attribute - Javelin does that automatically (in Hibernate persistence mode) when it generates the code for all persistent classes that do not have a super class (if they have a super class then they inherit the identity from their super class). The identity attribute is not shown in the class icon as it's existence is implied by most persistence mechanisms.

If you want to see the identity attribute in the source code then right click on your class and choose 'View class source file'. Scroll down till you see the identity attribute and its getter and setter.

Hibernate Mapping File

By now you should have re-established the Event class so that is has the same methods and attributes as the one we deleted earlier. Now is a good time to take a look at the Hibernate mapping file that Javelin has created for this class. Right click on the class and select 'View mapping file'. The Event.hbm.xml mapping file will be opened for you to view. You can see how the mappings for the file have been automatically created. Don't make changes directly to this file - as this file is regenerated from scratch each time from information embedded in your design. There are a number of places in Javelin where you can customize the generated mapping file so there should not be any need to edit this file manually. We are about to use this customization right now!

Hibernate, by default, uses the attribute name for the column name and a closely matching type. In the Hibernate example a non default column name was assigned to the date field and its type was changed to 'timestamp'.  We will now do this in Javelin.

Double click on the event class. This is a short cut way to bring up the members form. Select the 'date' attribute and then click 'Properties...'. In the last field, marked 'Extra Persistence Directives' enter:

type="timestamp" column="EVENT_DATE"

and press 'OK' and then press 'Close' on the members form.

View the mapping file again (Right click > View mapping file) and you should see your new persistence mapping directives.

Compiling and Running

We want to start with a clean database so change your hibernate.hbm.xml to "create schema" mode by making sure the line

<property name="hbm2ddl.auto">create</property>

is present and not surrounded by a comment marker.

Change the Compile/Run Option's run command to:

ant run -Daction=store

and then perform a Debug > Compile and after it compiles without error do a Debug > Run. Hopefully your app should work just like before. You will have to change Run command to:

ant run -Daction=list

so that you can get the app to fetch the data it stored in the previous step.

Saving your project

Javelin projects are automatically saved whenever you exit or switch to another project. You can explicitly save a project at any time using File|Save.

Conclusion

You have now successfully created a new class and mapped it to a relational database table using the Hibernate persistence service. This is a very elemental but important step. Adding more classes is just as easy as right clicking on empty space and choosing "Add Class...". Adding the relationships between them is just a matter of dragging from the very top bar, "the relationship launch bar" of one class to another class and specifying the type of relationship that you require. You can edit the multiplicity and code generation for each end of an association relationship by right clicking on the extreme ends of association and choosing "reference details".

You should feel confident to go forth and experiment more with Javelin. Create a few more classes. Establish some relationships between them and look at the mapping file to see the code generated for the relationships.

In the near future we will be creating tutorials on inheritance and associations so check the website regularly.

back to Javelin Home