The Hibernate ORM can be downloaded from http://hibernate.org/orm/ as a zip file containing a collection of JAR files that have to be added to the classpath manually.

As Hibernate depends on a couple of other open source libraries, it is recommended to let a build tool like Maven or Gradle resolve the dependencies automatically by adding a dependency to the hibernate-core module of the build file.

Before Hibernate can be used, it has to be configured with the correct connection parameters and the database driver to use. This can be done either by using an XML file (hibernate.cfg.xml) or a properties file (hibernate.properties). In both cases, the file should be stored in the classpath, normally in src/main/resources/, if the Mavens standard directory structure is used.

A basic configuration in the XML format could look like this:

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
  "-//Hibernate/Hibernate Configuration DTD//EN"
  "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
  <session-factory>
    <property name="connection.driver_class">
      org.postgresql.Driver
    </property>
    <property name="connection.url">
      jdbc:postgresql://localhost/car_portal
    </property>
    <property name="connection.username">
      car_portal_app
    </property>
    <property name="connection.password"></property>
    <property name="dialect">
      org.hibernate.dialect.PostgreSQL9Dialect
    </property>
    <property name="show_sql">true</property>
  </session-factory>
</hibernate-configuration>

When using a properties file, the configuration would be written in a name=value format (such as connection.username=car_portal_app).

In addition to specifying the parameters needed to connect to the database, two optional settings are configured in the example:

A complete list of the optional configuration properties is given in chapter 3.4 of the Hibernate reference documentation (http://docs.jboss.org/hibernate/orm/4.3/manual/en-US/html/).

Before a Java application can interact with the persistence store, it has to open a session. A session is a single-threaded object that holds a JDBC connection to the database. As with connections, a session should be closed as soon as it is no longer needed. A new session can be created by calling openSession() on the SessionFactory.

A SessionFactory is an immutable, thread-safe factory for session instances. It is recommended to instantiate it as a singleton object with the application-global scope.

Often, it is helpful to create a reusable helper class that provides the SessionFactory:

public class SessionFactoryHelper{
  private static final SessionFactory sessionFactory = createSessionFactory();

  private static SessionFactory createSessionFactory(){
    Configuration configuration = new Configuration().configure();
    StandardServiceRegistry registry =
      new StandardServiceRegistryBuilder()
      .applySettings(configuration.getProperties())
      .build();
    return configuration.buildSessionFactory(registry);
  }

  public static SessionFactory getSessionFactory(){
    return sessionFactory;
  }
}

Upon the first invocation of the SessionFactoryHelper, createSessionFactory is called to instantiate the sessionFactory object.

First, the configuration is loaded from the standard configuration file by calling configure on an instance of Configuration. The loaded properties are then used to create an instance of StandardServiceRegistry.

A ServiceRegistry instance manages services, which provide functionality in a pluggable manner. An example of a service is ConnectionProvider, which is an interface declaring methods for obtaining and releasing connections. Hibernate always references this interface, while the actual implementation is managed by the registry.

The ServiceRegistry is then used again to let the Configuration object build the SessionFactory.

Once this is done, the factory can be obtained by calling the getSessionFactory method.

In order to allow Hibernate to store objects in a table, a mapping between the Java class that represents the object and the table that it will be stored in has to be configured.

This can either be done by creating a mapping in the XML format or by adding annotations to an entity-class. In both cases, the mapping has to be added to the session-factory section in the configuration-file:

<mapping resource="Account.hbm.xml"/>
<mapping class="carportal.Account"/>

The first entry adds a mapping in the XML format, while the second entry specifies the fully-qualified name of an annotated entity class.

It is possible to add multiple mappings to the configuration, and use both methods at the same time.

package carportal;

public class Account{
  private int accountID;
  private String firstName;
  private String lastName;
  private String email;
  private String password;
  
  protected Account(){}
}

<hibernate-mapping package="carportal" schema="carportal_app">
  <class name="Account" table="account">
    <id name="accountID" column="account_id">
      <generator class="identity"/>
    </id>
    <property name="firstName" column="first_name"/>
    <property name="lastName" column="last_name"/>
    <property name="email"/>
    <property name="password"/>
  </class>
</hibernate-mapping>

package carportal;
import javax.persistence.*;

@Entity
@Table(name = "account")
public class Account{
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  @Column(name = "account_id")
  private int accountID;

  @Column(name = "first_name")
  private String firstName;

  @Column(name = "last_name")
  private String lastName;

  private String email;
  private String password;

  @Transient
  private int someInternalValue;

  private Account(){}
}