Tuesday, April 18, 2006

Java Persistence API kickstart example

The new Java Persistence API (JSR 220) - the API for management of persistence and object/relational mapping - is comming your way! Finally persistence gets standardised. The Java Persistence API, or simply JPA, is required to be supported by any Java EE 5 implementation (as part of EJB 3.0), but can also be used in stand-alone Java SE.

I've set up a simple kickstart example which can be used as starting point to persist objects and run EJBQL queries. Start experimenting yourself today! You can add your own Java objects to the example and use them to persist or retrieve data.

To keep things simple we will use the stand-alone JPA implementation of GlassFish, Toplink Essentials, in Java SE (JDK 5 required) and as database we use an embedded HSQLDB database.

  1. Let's get started by downloading the GlassFish JPA implementation from: https://glassfish.dev.java.net/downloads/persistence/JavaPersistence.html (for this example I used build 44). You need to install/unpackage the downloaded jar as described on the download page: java -jar filename.jar. A directory will be created containing the needed jar files. Next, download HSQLDB from: http://www.hsqldb.org.

  2. Create a project environment (e.g. using Eclipse) and make sure toplink-essentials.jar, toplink-essentials-agent.jar and hsqldb.jar are on the classpath.

  3. Next, create your first entity class:
    import javax.persistence.Entity;import javax.persistence.Id;


    public class Cat {

    private String id;

    private String name;

    private char sex;

    private float weight;

    public Cat() {


    public Cat(String id, String name, char sex, float weight) {

    this.id = id;

    this.name = name;

    this.sex = sex;

    this.weight = weight;



    public String getId() {

    return id;


    public void setId(String id) {

    this.id = id;


    public String getName() {

    return name;


    public void setName(String name) {

    this.name = name;


    public char getSex() {

    return sex;


    public void setSex(char sex) {

    this.sex = sex;


    public float getWeight() {

    return weight;


    public void setWeight(float weight) {

    this.weight = weight;



  4. Create a META-INF directory on your classpath and add the file persistence.xml:
    <persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">

    <persistence-unit name="example">

    <!-- Provider class name is required in Java SE -->


    <!-- All persistence classes must be listed -->



    <!-- Provider-specific connection properties -->

    <property name="toplink.jdbc.driver" value="org.hsqldb.jdbcDriver"/>

    <property name="toplink.jdbc.url" value="jdbc:hsqldb:mem:."/>

    <property name="toplink.jdbc.user" value="sa"/>

    <property name="toplink.jdbc.password" value=""/>

    <!-- Provider-specific settings -->

    <property name="toplink.ddl-generation" value="create-tables"/>

    <!-- other values are: drop-and-create-tablesnone -->

    <property name="toplink.logging.level" value="DEBUG"/>

    <property name="toplink.platform.class.name" value="oracle.toplink.essentials.platform.database.HSQLPlatform"/>




    Because we are running HSQLDB in memory and have set ddl-generation to "create-tables" we don't have to install a database and even don't have to create the Cat table. Toplink Essentials will create the table automatically.

  5. Create a simple Example class in which we will use the Java Persistence API:
    import java.util.List;

    import javax.persistence.EntityManager;

    import javax.persistence.EntityManagerFactory;

    import javax.persistence.Persistence;

    public class Example {

    public static void main(String[] args) {

    EntityManagerFactory emf = Persistence.createEntityManagerFactory("example");

    EntityManager em = emf.createEntityManager();

    try {


    Cat princess = new Cat("1", "Princess", 'F', 7.4f);

    Cat blackie = new Cat("2", "Blackie", 'M', 7.6f);




    List<Cat> cats = em.createQuery("SELECT c FROM Cat c").getResultList();

    for (Cat c : cats) {



    } catch(Exception ex) {


    } finally {





    First we persist 2 Cat instances and later we retrieve them back againg using an EJBQL query.

  6. Now run the Example class. The result should be something like below. This means you are successfully using the Java Persistence API!
    [TopLink Info]: 2006.04.18 08:54:44.734--ServerSession(9800632)--TopLink, version: Oracle TopLink Essentials - 2006.4 (Build 060412)

    [TopLink Info]: 2006.04.18 08:54:45.093--ServerSession(9800632)--file:/C:/Projects/workspace/jpa_example-example login successful



Next steps: create your own Java objects, list them in the persistence.xml and start expirementing with them by persisting them and retrieving them using EJBQL queries. Note that when you run the example new tables are created automatically for your new Java objects.

Saturday, April 8, 2006

Using other query languages in JasperReports

In version 1.2.0 of JasperReports - The most popular open source reporting engine in the world - support for other query languages, including HQL and XPath, is added.

This means you can use HQL directly in report templates! The report engine will create a HibernateSessionFactory which uses your Hibernate configuration and mappings to connect to the database, build the SQL statement and return the mapped Java objects. Example of HQL queryString in report template:

<queryString language="hql">
from Cat cat
where cat.weight > ($P{CatWeight})]]>

Notice the language="hql" which indicates the report engine to use HQL instead of plain JDBC SQL. JasperReports introduced the JRQueryExecuterFactory and JRQueryExecuter interfaces to incorporate new/additional query languages easily by - just - implementing them. Currently there are query language implementations for JDBC, Hibernate and Xpath.

As the Java Persistence API, part of EJB 3.0/JEE 5.0, is becoming the standard I decided to create a patch to add support for JPA/EJBQL in JasperReports. The code is already submitted to the JasperReports team and I hope it will be included soon in a future release.

When released I will add a step-by-step example on using EJBQL queries in report templates.

Thursday, April 6, 2006

I've just successfully deployed the demo webapp of JasperReports - The most popular open source reporting engine in the world - on the latest GlassFish build (b42).

  1. Download the latest GlassFish build from https://glassfish.dev.java.net/public/downloadsindex.html.
  2. See the Instructions to unbundle and configure GlassFish and the GlassFish Quick Start Guide to get GlassFish up and running.
  3. Make sure GlassFish is running by checking http://localhost:8080.
  4. Download JasperReports (jasperreports-1.2.0-project.zip) from http://sourceforge.net/project/showfiles.php?group_id=36382&package_id=28579.
  5. Unzip the downloaded JasperReports archive.
  6. Navigate to the the JasperReports demo webapp source directory.
    cd jasperreports-1.2.0\demo\samples\webapp
  7. Run the ant command and specify the war target.
    ant war
    When the build is finished the jasper-webapp.war should be in the \webapp directory.
  8. Copy jasper-webapp.war to GlassFish install-dir/domains/domain1/autodeploy. The JasperReports demo webapp will be deployed automatically.
  9. Goto the JasperReports demo webapp running on http://localhost:8080/jasper-webapp/. If you get a 404 wait a couple of seconds and refresh; probably the application was not yet deployed. Eventually you should see the JasperReports Web Application Sample.
  10. In the leftside menu click the compile link and compile the report template either using the JSP or Servlet Example.
  11. Now the report template is compiled you can execute the report itself with the PDF and HTML output links in the leftside menu. Both PDF and HTML output should work!

In a next entry I will explain how to use Java Persistence API EJBQL queries directly in report templates. This by using the new JasperReports 1.2.0 extendible JRQueryExectureFactory feature.

Wednesday, April 5, 2006

Welcome to my new weblog

Welcome to my brand new weblog about Java, open source and other interesting things.