Page History

So, you fill in all the fields, submit the form (without validation errors) and voila: you get back the same form, blanked out. What happened, and where did the data go?

What happened is that we haven't told Tapestry what to do after the form is succesfully submitted (by succesful, we mean, with no validation errors). Tapestry's default behavior is to redisplay the active page, and that occurs in a new request, with a new instance of the Address object (because the address field is not a peristent field).

Well, since we're creating objects, we might as well store them somewhere ... in a database. We're going to quickly integrate Tapestry with [Hibernate|http://hibernate.org] as the object/relational mapping layer, and ultimately store our data inside a [HSQLDB|http://www.hsqldb.org/] database. HSQLDB is an embedded database engine and requires no installation

 -- it will be pulled down as a dependency via maven.

h2.

 Re-configuring the Project

We're going to bootstrap this project from a simple Tapestry project to one that uses Hibernate and HSQLDB.

h3.

 Updating the Dependencies

First, we must update the POM to list a new set of dependencies, that includes Hibernate, the Tapestry/Hibernate integration library, and the HSQLDB JDBC driver:

{code

:XML

|title

=src/pom.xml (partial)

}
    <dependencies>
        <dependency>
            <groupId>org.apache.tapestry</groupId>
            <artifactId>tapestry-hibernate</artifactId>
            <version>${tapestry-release-version}</version>
        </dependency>

        <dependency>
            <groupId>hsqldb</groupId>
            <artifactId>hsqldb</artifactId>
            <version>1.8.0.7</version>
        </dependency>

    </dependencies>
{code}

The tapestry-hibernate library includes, as transitive dependencies, Hibernate and tapestry-core. This means that you can simply replace "tapestry-core" with "tapestry-hibernate" inside the <artifactId> element.

Since Hibernate can work with so many different databases, we must explicitly add in the correct driver.

h3.

 Hibernate Configuration

Hibernate has a master configuration file used to store connection and other data.

{code

:XML

|title

=src/main/resources/hibernate.cfg.xml

}
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
    <session-factory>
        <property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property>
        <property name="hibernate.connection.url">jdbc:hsqldb:./target/work/t5_tutorial1;shutdown=true</property>
        <property name="hibernate.dialect">org.hibernate.dialect.HSQLDialect</property>
        <property name="hibernate.connection.username">sa</property>
        <property name="hibernate.connection.password"></property>
        <property name="hbm2ddl.auto">update</property>
        <property name="hibernate.show_sql">true</property>
        <property name="hibernate.format_sql">true</property>
    </session-factory>
</hibernate-configuration>{code}

Most of the configuration is to identify the JDBC driver and connection URL.

Note the connection URL. We are instructing HSQLDB to store its database files within our project's target directory. We are also instructing HSQLDB to flush any data to these files at shutdown. This means that data will persist across different invocations of this project, but if the target directory is destroyed (e.g., via "mvn clean"), then all the database contents will be lost.

In addition, we are configuring Hibernate to _update_ the database schema; when Hibernate initializes it will create or even modify tables to match the entities. Finally, we are configuring Hibernate to output any SQL it executes, which is very useful when initially building an application.

But what entities? Normally, the available entities are listed inside hibernate.cfg.xml, but that's not necessary with Tapestry; in another example of convention over configuration, Tapestry locates all entity classes inside the entities package and adds them to the configuration. Currently, that is just the Address entity.

h2.

 Adding Hibernate Annotations

For an entity class to be used with Hibernate, some Hibernate annotations must be added to the class.

Below is the updated Address class, with the Hibernate annotations (as well as the Tapestry ones).

{code

:title

=src/main/java/org/apache/tapestry5/tutorial/entities/Address.java

}
package org.apache.tapestry5.tutorial.entities;

import org.apache.tapestry5.beaneditor.NonVisual;
import org.apache.tapestry5.beaneditor.Validate;
import org.apache.tapestry5.tutorial.data.Honorific;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class Address
{
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @NonVisual
    private Long id;

    private Honorific honorific;

    @Validate("required")
    private String firstName;

    @Validate("required")
    private String lastName;

    private String street1;

    private String street2;

    @Validate("required")
    private String city;

    @Validate("required")
    private String state;

    @Validate("required,regexp")
    private String zip;

    private String email;

    private String phone;

    public Long getId()
    {
        return id;
    }

    public void setId(Long id)
    {
        this.id = id;
    }

    public Honorific getHonorific()
    {
        return honorific;
    }

    public String getFirstName()
    {
        return firstName;
    }

    public String getLastName()
    {
        return lastName;
    }

    public String getStreet1()
    {
        return street1;
    }

    public String getStreet2()
    {
        return street2;
    }

    public String getCity()
    {
        return city;
    }

    public String getState()
    {
        return state;
    }

    public String getZip()
    {
        return zip;
    }

    public String getEmail()
    {
        return email;
    }

    public String getPhone()
    {
        return phone;
    }

    public void setCity(String city)
    {
        this.city = city;
    }

    public void setEmail(String email)
    {
        this.email = email;
    }

    public void setFirstName(String firstName)
    {
        this.firstName = firstName;
    }

    public void setHonorific(Honorific honorific)
    {
        this.honorific = honorific;
    }

    public void setLastName(String lastName)
    {
        this.lastName = lastName;
    }

    public void setPhone(String phone)
    {
        this.phone = phone;
    }

    public void setState(String state)
    {
        this.state = state;
    }

    public void setStreet1(String street1)
    {
        this.street1 = street1;
    }

    public void setStreet2(String street2)
    {
        this.street2 = street2;
    }

    public void setZip(String zip)
    {
        this.zip = zip;
    }
}{code}

The Tapestry annotations, @NonVisual and @Validate, may be placed on the setter or getter method or on the field (as we have done here). As with the Hibernate annotations, putting the annotation on the field requires that the field name match the corresponding property name.

{code

:title

=src/main/java/org/apache/tapestry5/tutorial/pages/Index.java (partial)

}
    @Inject
    private Session session;

    public List<Address> getAddresses()
    {
        return session.createCriteria(Address.class).list();
    }
{code}

Here, we're using the Hibernate Session object to find all Address objects in the database. Any sorting that takes place will be done in memory. This is fine for now (with only a handful of Address objects in the database). Later we'll see how to optimize this for very large result sets.

h2.

 What's Next?

We have lots more to talk about: more components, more customizations, built-in Ajax support, more common design and implementation patterns, and even writing your own components (which is easy!).

More tutorials are planned, but for now check out the other Tapestry resources available on the [Tapestry 5 Documentation page|Documentation] page.
{tutorialnav}