A sample using Vaadin with Hibernate JPA and Spring on Z2¶

This sample is similar to Sample-spring-hibernate but differs (or rather extends) in that it show cases
the use of the Vaadin user interface toolkit in conjunction with Spring implemented annotation based
dependency injection over Z2 modularity.

As Spring is used throughout - in all modules - this is another practical application of How to Spring.

Moreover this sample illustrates modularization of Vaadin user interfaces with Z2 using extension points as described in Vaadin add-on.

This sample is stored in z2-samples.vaadin-spring-hibernate.

Prerequisites¶

Z2 has the following Java Version requirements

Z2 Version	Min. Java version required	Max Java version supported	Max language level
2.1 - 2.3.1	Java 6	Java 7	Java 7
2.4 - 2.5	Java 8	Java 8	Java 8
2.6	Java 9	Java 11	Java 10
2.7	Java 9	Java 11	Java 11
2.8	Java 9	Java 13	Java 13
2.9b	Java 8	Java 8	Java 8
2.9.1	Java 11	Java 16	Java 15
2.9.1b	Java 8	Java 8	Java 8
2.10	Java 11	Java 18	Java 18
2.10.1	Java 11	Java 21	Java 18
master	Java 17	?	Java 23

Note: Most samples suggest to use the master branch. You may choose another version branch (please check the respective repository).
Make sure you have a corresponding Java Development Kit (JDK) or Java Runtime Environment (JRE) installed. If in doubt, go to Download Java SE.

Note: Running v2.1-v2.3.1 on Java 8 is supported by specifying

com.zfabrik.java.level=7

(or 6, if that is your desired compilation language level) in <home>/run/bin/runtime.properties. By this the Java compiler version detection does not fall back to a lower level.

You need to run Java DB as network server on localhost. This is explained next.

The application will create a database "z2-samples"

Running a Java DB Network Server¶

Previously to Java 9, the Java SE Development Kit (JDK) by Oracle provided the Java DB - essentially the same as the Apache Derby DB. That is not the case anymore. However, we use that Database implementation in our samples. In order to run those samples that illustrate use of a relational database, please follow the instructions below to install and run Apache Derby. Could hardly be simpler.

Step 1: Download and Install¶

Unless you have done so already, download Apache Derby DB and follow the installation how-to.

Note: You do not need to unpack Apache Derby into some global folder on your system. Instead you may want to use some local folder under your user's home folder. There is no problem installing and runnning different instances and configurations at any time.

Step 2: Run¶

Let's assume you installed (well - unpacked) into a folder $DERBY_INSTALL. Also, let's assume some Java Runtime Environment is installed and ready.

Simply run the following on Linux or Mac OS:

cd $DERBY_INSTALL
java -jar lib/derbyrun.jar server start

On Windows run

cd %DERBY_INSTALL
java -jar lib\derbyrun.jar server start

That's it. Apache Derby will be waiting for connections on port 1527.

Run it¶

If you have the database, the fastest way to verify whether it runs is:

mkdir install
cd install

On Mac-OS or Linux run:

wget http://download.z2-environment.net/z2/z2-base-v2.10.zip
unzip z2-base-v2.10.zip

On Windows download the archive and unpack using the Windows explorer. Make sure to unpack into the installation folder previously created.

This will create a folder z2-base.core that contains the complete version 2.9 z2-base installation.

Check out the sample

git clone -b v2.6 http://git.z2-environment.net/z2-samples.vaadin-spring-hibernate

On Mac OS or Linux run:

cd z2-base.core/bin
./gui.sh

On Windows run:

cd z2-base.core\bin
gui.bat

(In order to check that z2 is up, when you see "Completed home process initialization", try http://localhost:8080/adm with user "z*" and password "z".)

When running, go to http://localhost:8080/vaadin-spring-hibernate. You should see this:

Details¶

As in the other samples we have a re-use domain module. That is a recurring theme for many good reasons. In this case, the domain module com.zfabrik.samples.vaadin-spring-hibernate.domain is essentially like the similarly named module of Sample-spring-hibernate. The only difference is some more data access methods in the ThingyRepository.

The Vaadin Web application is defined in the module com.zfabrik.samples.vaadin-spring-hibernate.web. It has the usual Spring application context in web/WebContent/WEB-INF/applicationContext.xml that imports the thingy repository:

        <!-- import external components -->
        <bean id="thingyRepository" class="com.zfabrik.springframework.ComponentFactoryBean">
                <property name="componentName" value="com.zfabrik.samples.vaadin-spring-hibernate.domain/repository" />
                <property name="className" value="com.zfabrik.samples.vaadin_spring_hibernate.thingies.ThingyRepository" />
        </bean>

One particularity of using Vaadin in a modular environment is that Vaadin loads it's application class using the class loader that loaded the Vaadin classes (rather than the current thread's context class loader - as would be advised normally). When the Web application module is separated from the Vaadin module this can obviously not work too well (see also Enhancement #9809). To fix that you can tell Vaadin to use a custom class loader implementation (that - again - is loaded with the Vaadin class loader). That's why we declare the Vaadin servlet in web/WebContent/WEB-INF/web.xml list this:

<!-- Vaadin -->
<servlet>
  <servlet-name>VaadinServlet</servlet-name>
  <servlet-class>com.vaadin.terminal.gwt.server.ApplicationServlet</servlet-class>
  <init-param>
    <param-name>application</param-name>
    <param-value>com.zfabrik.samples.impl.vaadin_spring_hibernate.ApplicationImpl</param-value>
  </init-param>
  <!-- this because Vaadin doesn't use the thread's context class loader by default -->
  <init-param>
    <param-name>ClassLoader</param-name>
    <param-value>com.zfabrik.vaadin.ContextClassLoader</param-value>
  </init-param>*
</servlet>

The Vaadin application class ApplicationImpl constructs a simple view hierarchy that containes a table view based on a lazy query container add-on data model that is fed from the domain module. To do so the corresponding query implementation (in lazy query container speak) has the repository injected:

@Configurable
public class ThingiesQuery implements Query {
    @Autowired
    private ThingyRepository repository;
    private Integer size;
    private boolean asc;

// ...
}

Please browse the actual UI code at com.zfabrik.samples.vaadin-spring-hibernate.web/java/src.impl/com/zfabrik/samples/impl/vaadin_spring_hibernate. It pretty much speaks for itself.

Transaction Management¶

One important note on transaction management: In this example, transaction boundaries are enforced by a servlet filter once more. It is implemented in TransactionFilter and essentially looks like this:

public class TransactionFilter implements Filter {

        @Transactional
        @Override
        public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
                chain.doFilter(request, response);
        }

}

In other words, the only thing it really does is to make sure Spring spans a transaction (using the underlying JTA implementation) along the request. It is tempting to implement transaction demarcation in the Vaadin Application class. However, we cannot use the @Transactional annotation as there is no single request spanning method and using the JTA UserTransaction object is unfortunately not sufficient to "remote control" Spring's JTA wrappers. So the easiest work around is to use Spring TX demarcation right away (see also how to transaction management).

Extensibility¶

Furthermore this sample illustrates the use of the ExtensionComponentsUtil (javadoc) as described in detail at Vaadin_Add-on. This utility allows to conveniently modularize the user interface implementation by providing and retrieving Vaadin user interface component implementations across modules.

In the specific case, the module com.zfabrik.samples.vaadin-spring-hibernate.extension provides an extension component somethingAboutThingies that is added as the button "About these..." to the button toolbar of the main interface.

The component declaration makes sure the implementation can be found and (important!) that the module's Spring application context is loaded before providing the component implementation

#
# A Vaadin UI extension 
#
com.zfabrik.component.type=com.vaadin.ui.Component

#
# Coordinates:
#
com.zfabrik.vaadin.extension.point=com.zfabrik.samples.vaadin_spring_hibernate.actions
com.zfabrik.vaadin.extension.order=100

#
# The implementation class
#
component.className=com.zfabrik.samples.impl.vaadin_spring_hibernate.ext.SomethingAboutThingies

#
# make sure the app context is loaded first
#
com.zfabrik.component.dependencies=\
     com.zfabrik.samples.vaadin-spring-hibernate.extension/applicationContext

The user interface that assembles consumes this extension is at ThingiesView and adds extensions like this:

// find extensions and add them to the button row
for (Component c : ExtensionComponentsUtil.getComponentyByExtensionForApplication(application,"com.zfabrik.samples.vaadin_spring_hibernate.actions")) {
    // and add them to this.
    buttons.addComponent(c);
}