Installing Maven

There are many ways to install Maven. This is a cursory overview; different operating systems (and different system configurations) can affect the installation procedure, so when you are in doubt, you can refer to http://maven.apache.org/download.cgi#Installation for the actual documentation.

To save you some time, however, you can download Maven from http://maven.apache.org/download.cgi/ ; you should get the most recent version. UNIX users (including Linux and MacOS users) should download the file ending in tar.gz; Windows users should download the zip file.

In UNIX , untar the file into a directory of your choice; an example of the command that might be run is this:

mkdir ∼/tools || cd ∼/tools; tar xf apache-maven-3.3.9-bin.tar.gz

This will create ∼/tools/apache-maven-3.3.9/, and the mvn executable will be in ∼/tools/apache-maven-3.3.9/bin; add this to your command path.

For Windows, open the archive and extract it into a known location (for example, C: ools). Add the location of mvn.bat (in this example, C: oolsapache-maven-3.3.9in) to your path via the System Properties dialog, and you should be able to run Maven with “mvn” in the command prompt.

Maven uses a project object model , typically written in XML, called “ pom.xml”. This file describes the project's name and versions and builds configurations (if any), as well as any subprojects and any project dependencies. When Maven is run, it will automatically download any resources it needs in order to complete the build as specified, and then it will compile the project source code; if the project includes tests, it will run the tests and complete the build if (and only if) no test failures occur.

This book uses a parent project that contains global dependencies for the book, and subprojects corresponding to the chapters; much of the operating code is written as a set of tests in the subprojects. Chapter 1, for example, used two methods to write data to and read data from a database; those tests were written as TestNG⁶ test classes: chapter01.hibernate.PersistenceTest and chapter01.jdbc.PersistenceTest.

The parent project's configuration file , after Chapter 1 was written, looked like Listing 2-1.

Listing 2-1. The Top-Level Project Object Model for Maven

<?xml version="1.0"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd"
         xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.autumncode.books.hibernate</groupId>
    <artifactId>hibernate-parent</artifactId>
    <packaging>pom</packaging>
    <version>1.0-SNAPSHOT</version>
    <modules>
        <module>chapter01</module>
    </modules>
    <name>hibernate-parent</name>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.testng</groupId>
            <artifactId>testng</artifactId>
            <version>[6.9.10,)</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-core</artifactId>
            <version>[5.0.0,5.9.9]</version>
        </dependency>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <version>1.4.192</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.3.2</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <showDeprecation>true</showDeprecation>
                    <showWarnings>true</showWarnings>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

This specifies a number of things about the project (such as the Java version, which is the current maintained version of Java⁷), and includes three dependencies: Hibernate itself; the H2 database; and TestNG, the last which is limited to the testing phase (as the “scope” node instructs).

The child projects —in this listing, this is only chapter01—will receive this configuration and its set of dependencies automatically, which means we don't have to repeat ourselves very often.

To build and run this project after installing Maven, you simply have to go to the directory that contains pom.xml, and execute “mvn package” — that will, as stated, download all the required dependencies, build them, and then test the projects in order.

Maven projects have a specific folder layout, although it's configurable; by default, the Java compiler compiles all code found in src/main/java, and the resulting class files are included with src/main/resources in the deliverable artifact. The src/test/java directorycontains tests, which are then compiled and run (with src/test/resources and the deliverable artifact in the classpath as well).

Wow, that's a lot of non-Hibernate discussion – and all of it can be found (and subverted) on the websites for each given build environment. In general, you can (and should) use what you like; this book uses Maven because of how common it is, not because it's the One True Build Tool.

Let's look at the actual code we've been running so far and explain it all. That will give you a basis for future discussion, even if you're not going to use it much beyond this chapter.

We've already mentioned the top-level pom.xml file ; we're going to start in the chapter02 directory (which is a clone of the chapter01 directory, except with “chapter02” instead of “chapter01”). Our project description file (our pom.xml) is very simple, specifying only the parent project and the current project's name (see Listing 2-2).

Listing 2-2. Chapter 2’s Project Object Model

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>hibernate-parent</artifactId>
        <groupId>com.autumncode.books.hibernate</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>chapter02</artifactId>
</project>

Our Message.java is held in src/main/java/chapter02/Message.java. This is the same POJO as in Listing 1-5, except that it’s in a different package (chapter02.hibernate instead of chapter01.hibernate). Since everything else is the same, we won't list it here.

Our actual running code is in the src/test directory and consists of two relevant files:⁸ src/test/java/chapter02/hibernate/PersistenceTest.java and src/test/resources/hibernate.cfg.xml.

We've already seen the test methods from PersistenceTest.java, but let's take a look at the entire Listing 2-3 so you understand everything in it.

Listing 2-3. A Set of Persistence Tests

package chapter02.hibernate;

import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;
import org.hibernate.boot.MetadataSources;
import org.hibernate.boot.registry.StandardServiceRegistry;
import org.hibernate.boot.registry.StandardServiceRegistryBuilder;
import org.testng.annotations.BeforeSuite;
import org.testng.annotations.Test;

import java.util.List;

import static org.testng.Assert.assertEquals;

public class PersistenceTest {
    SessionFactory factory;

    @BeforeSuite
    public void setup() {
        StandardServiceRegistry registry = new StandardServiceRegistryBuilder()
                .configure()
                .build();
        factory = new MetadataSources(registry)
                .buildMetadata()
                .buildSessionFactory();
    }

    @Test
    public void saveMessage() {
        Message message = new Message("Hello, world");
        try (Session session = factory.openSession()) {
            Transaction tx = session.beginTransaction();
            session.persist(message);
            tx.commit();
        }
    }

    @Test(dependsOnMethods = "saveMessage")
    public void readMessage() {
        try (Session session = factory.openSession()) {
            List<Message> list = session.createQuery("from Message",
                Message.class).list();

            assertEquals(list.size(), 1);
            for (Message m : list) {
                System.out.println(m);
            }
        }
    }
}

Again, note that we're using TestNG to run the tests, which in this case affects our class in a few simple ways.

First, the actual test methods are annotated with @Test; we indicate a dependency between tests with a setting for readMessage(). If saveMessage() were to fail, readMessage() would not be executed, as its execution depends on a successful saveMessage().

Second, there's a @BeforeSuite method , which is executed before any of the tests are attempted. This gives us a chance to do system initialization. This is where we're setting up Hibernate for usable state – in the JDBC code, we use this same mechanism to load the JDBC driver and create our database schema.⁹

Third, we indicate that failure through the use of the statically imported assertEquals(),¹⁰ which should be easy to understand. An exception also indicates a failure, unless we tell TestNG that we expect an exception to be thrown (and we can also tell TestNG what specific types of exceptions allow the test to pass).

You're likely to use this construct often because it's easy to integrate into your project build life cycle (as Maven runs the available tests as part of the build). Also, it gives you a clear order of execution, and also provides an easy way to see what works and what doesn't work. You should feel free to write tests to validate your own understanding of what is being described.

Next, note how the test is constructed.

The test shows the canonically correct way to use Hibernate's native API:¹¹ first, construct a SessionFactory, which is the entry point to the Hibernate API (much as EntityManager is the entry point for the Java Persistence Architecture); then use the SessionFactory to retrieve short-lived Session objects through which updates, or reads, are performed. We use automatic resource management to make sure the Session is closed when the block is finished executing.

We actually don’t (and can’t) use automatic resource management on the Transaction, though. We don’t want a “close” mechanism on a Transaction; we want to specifically determine the end result, whether it’s committed or not. An automatic management mechanism for transactions would have unfortunate implications in the cases of error conditions (which can be common in database-oriented applications.) We cover transactions a good bit more thoroughly in Chapter 8.

The actual tests mirror the JDBC code fairly well¹² (or vice versa); in both, we acquire a resource through which we “talk to” the database, then we perform an action, then we commit our changes (if any) and clean up. (There are definitely details being skipped; this is the ten-thousand-foot view of the mechanisms in place.)

The last piece of the puzzle is the actual configuration file itself, which is in src/test/resource/hibernate.cfg.xml. See Listing 2-4.

Listing 2-4. The hibernate.cfg.xml, the Hibernate Configuration

<?xml version="1.0"?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
    <session-factory>
        <!--  Database connection settings  -->
        <property name="connection.driver_class">org.h2.Driver</property>
        <property name="connection.url">jdbc:h2:./db2</property>
        <property name="connection.username">sa</property>
        <property name="connection.password"/>
        <property name="dialect">org.hibernate.dialect.H2Dialect</property>
        <!--  Echo all executed SQL to stdout  -->
        <property name="show_sql">true</property>
        <!--  Drop and re-create the database schema on startup  -->
        <property name="hbm2ddl.auto">create-drop</property>
        <mapping class="chapter02.hibernate.Message"/>
    </session-factory>
</hibernate-configuration>

This file might serve as a boilerplate for every Hibernate configuration. In it, we specify the JDBC driver class; the JDBC URL, user name, and password used to access the database; a dialect(which allows Hibernate to correctly produce SQL for each given database); some configuration, such as whether to dump the generated SQL to the console; and what to do for the schema. Lastly, it specifies the classes that should be managed — in this case, only our Message class.

There are a lot of things we can control from this file; we can even use it to specify the mapping of our objects to the database (i.e., ignoring the annotations we've been using so far). You'll see a little more of how to do this in later chapters of this book; it helps quite a bit in mapping existing database schemata¹³ to object models.

Most coders will (and should) prefer the annotation-based mappings.