이 튜토리얼은 웹 기반의 어플리케이션 용 Apache Tomcat 서블릿 컨테이너에 대한 Hibernate 3.0 셋업을 설명한다(우리는 버전 4.1을 사용했다. 5.0에 대한 차이점들은 적을 것이다). Hibernate는 모든 주요 J2EE 어플리케이션 서버들의 관리되는 환경에서 잘 동작하고, 또는 심지어 스탠드얼론 어플리케이션들에서도 잘 동작한다. 이 튜토리얼에 사용되는 데이터베이스 시스템은  PostgreSQL 7.4이고, 다른 데이터베이스에 대한 지원은  단지 Hibernate SQL dialect 구성과 커넥션 프로퍼티들을 변경시키는 것에만 관계된다. 

먼저 우리는 모든 필수적인 라이브러리들을 Tomcat 설치 장소에 복사해야 한다. 우리는 이 튜토리얼을 위해 별도의 웹 컨텍스트(webapps/quickstart)를 사용하며, 따라서 우리는 전역 라이브러리 검색 경로(TOMCAT/common/lib)와  webapps/quickstart/WEB-INF/lib(JAR 파일들의 경우)와 webapps/quickstart/WEB-INF/classes 내 에 있는 컨텍스트 레벨에서 클래스로더 양자를 고려해야 한다. 우리는 두 개의 클래스로더 레벨들을 전역 classpath와 컨텍스트 classpath로 언급한다.

이제 라이브러리들을 두 개의 classpath들에 복사하라: 

우리는 이제 Tomcat과 Hibernate 양자에서 데이터베이스 풀링과 공유를 설정한다. 이것은 Tomcat이 (그것의 빌드되어 있는 DBCP 풀링 특징을 사용하여) 풀링된 JDBC 커넥션들을 제공할 것이고, Hibernate가 JNDI를 통해 이들 커넥션들을 요청한다는 것을 의미한다. 달리 당신은 Hibernate로 하여금 커넥션 풀을 관리하도록 할 수 있다. Tomcat은 그것의 커넥션 풀을 JNDI에 바인드 시킨다; 우리는 리소스 선언을 Tomcat 메인 구성 파일 TOMCAT/conf/server.xml에 추가한다: 

<Context path="/quickstart" docBase="quickstart">
    <Resource name="jdbc/quickstart" scope="Shareable" type="javax.sql.DataSource"/>
    <ResourceParams name="jdbc/quickstart">
        <parameter>
            <name>factory</name>
            <value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
        </parameter>

        <!-- DBCP database connection settings -->
        <parameter>
            <name>url</name>
            <value>jdbc:postgresql://localhost/quickstart</value>
        </parameter>
        <parameter>
            <name>driverClassName</name><value>org.postgresql.Driver</value>
        </parameter>
        <parameter>
            <name>username</name>
            <value>quickstart</value>
        </parameter>
        <parameter>
            <name>password</name>
            <value>secret</value>
        </parameter>

        <!-- DBCP connection pooling options -->
        <parameter>
            <name>maxWait</name>
            <value>3000</value>
        </parameter>
        <parameter>
            <name>maxIdle</name>
            <value>100</value>
        </parameter>
        <parameter>
            <name>maxActive</name>
            <value>10</value>
        </parameter>
    </ResourceParams>
</Context>

우리가 이 예제에서 구성하는 컨텍스트는 quickstart로 명명되고, 그것의 베이스는 TOMCAT/webapp/quickstart 디렉토리이다. 임의의 서블릿들에 접근하기 위해, (물론 당신의 web.xml 속에 매핑된 서블릿의 이름을 추가하여) 당신의 브라우저에서 http://localhost:8080/quickstart 경로를 호출하라. 당신은 또한 계속 진행하고 이제 공백의 process() 메소드를 가진 간단한 서블릿을 생성시킬 수 있다. 

Tomcat은 이제 java:comp/env/jdbc/quickstart로 JNDI을 통해 커넥션들을 제공한다. 만일 당신이 실행 중인 커넥션 풀을 얻는 것에 문제가 있다면 Tomcat 문서를 참조하라. 당신이 JDBC 드라이버 예외상황 메시지를 얻을 경우, 먼저 Hibernate 없이 JDBC 커넥션 풀을 셋업하라. Tomcat & JDBC 튜토리얼들은 그 웹 서이트에서 이용 가능하다.

당신의 다음 단계는 Hibernate를 구성하는 것이다. Hibernate는 그것이 JDBC 커넥션들을 얻는 방법을 알고 있어야 한다. 우리는 Hibernate의 XML 기반 구성을 사용한다.  properties 파일을 사용하는 다른 접근법은 거의 동일하지만 XML 구문이 허용하는 몇몇 특징들을 누락하고 있다.  XML 구성 파일은 hibernate.cfg.xml로서 컨텍스트 classpath (WEB-INF/classes) 내에  위치해 있다:

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
    "-//Hibernate/Hibernate Configuration DTD//EN"
    "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <session-factory>

        <property name="connection.datasource">java:comp/env/jdbc/quickstart</property>
        <property name="show_sql">false</property>
        <property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property>

        <!-- Mapping files -->
        <mapping resource="Cat.hbm.xml"/>

    </session-factory>

</hibernate-configuration>

우리는 SQL 명령들에 대한 로깅을 사용하지 않고 Hibernate에게 사용되는 데이터베이스 SQL direct가 무엇인지 그리고 (Tomcat 바인드된 풀의 JNDI 주소를 선언하여) JDBC 커넥션들을 얻는 곳을 알려준다. dialect는 필수적인 설정이고, 데이터베이스들은 SQL "표준"에 대한 그것들의 해석을 달리한다. Hibernate는 차이점들을 처리하고 모든 주요 상용 데이터베이스들 및 오픈 소스 데이터베이스들 용도의 direct들을 번들로 포함하고 있다.

SessionFactory 는 단일 데이터저장소에 관한 개념이고, 여러 데이터베이스들은 여러 개의 XML 구성 파일들을 생성시키고 당신의 어플리케이션 속에서 여러 개의 Configuration 및 SessionFactory 객체들을 생성시켜서 사용될 수 있다.

hibernate.cfg.xml의 마지막 요소는 영속 클래스 Cat에 대한 Hibernate XML 매핑 파일의 이름으로써 Cat.hbm.xml을 선언한다. 이 파일은 데이터베이스 테이블(또는 테이블들)로 POJO 클래스 Cat 을 매핑시키는 메타데이터를 포함한다. 우리는 곧 그 파일로 되돌아 갈 것이다. 먼저 POJO 클래스를 작성하고 그런 다음 그것을 위한 매핑 메타데이터를 선언하자.

Hibernate는 영속 클래스들에 대한 Plain Old Java Objects (POJOs, 종종 Plain Ordinary Java Objects로 명명된다) 프로그래밍 모형으로 가장 잘 동작한다.  POJO는 공용으로 가시적인 인터페이스로부터 내부적인 표상을 은폐시켜, getter와 setter 메소드들을 통해 접근가능한 클래스들의 프로퍼티들을 가진 자바빈과 꽤 유사하다(필요하다면 Hibernate는 또한 필드들에 직접 접근할 수 있다):

package org.hibernate.examples.quickstart;

public class Cat {

    private String id;
    private String name;
    private char sex;
    private float weight;

    public Cat() {
    }

    public String getId() {
        return id;
    }

    private 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;
    }

}

Hibernate는 그것의 프로퍼티 타입들의 사용에 제약되지 않고, 자바 콜렉션 프레임웍에서의 클래스들을 포함하여, 모든 자바 JDK 타입들과 (String, char와 Date 같은) 원시타입들이 매핑될 수 있다. 당신은 그것을 값들로서, 값들을 가진 콜렉션들로서, 또는 다른 엔티티들에 대한 연관들로서 매핑시킬 수 있다.  id 는 그 클래스의 데이터베이스 식별자(프라이머리 키)를 표현하는 특별한 프로퍼티이고, 그것은 Cat과 같은 엔티티들에 대해 매우 권장된다. Hibernate는 내부적으로만 식별자들을 사용할 수 있지만, 우리는 우리의 어플리케이션 아키텍처에서 어떤 유연성을 상실하게 될 것이다. 

특정 인터페이스는 영속 클래스들에 대해 구현되지 말아야 하거나 특정 루트 영속 클래스로부터 서브 클래스로 만들지 말아야 한다. Hibernate는 또한 바이트 코드 처리와 같은, 어떤 빌드 시 처리를 필요로 하지 않고, 그것은 오직 자바 reflection과 (CGLIB를 통한) 런타임 클래스 고양에만 의존한다. 따라서 Hibernate에 대한 POJO 클래스의 어떤 의존성 없이도, 우리는 그것을 데이터베이스 테이블로 매핑할 수 있다.

Cat.hbm.xml 매핑파일은 객체/관계형 매핑에 필요한 메타데이터를 포함한다. 메타데이터는 영속 클래스들의 선언과 데이터베이스 테이블들에 대한 (컬럼들과 다른 엔티티들에 대한 foreign 키 관계들에 대한) 프로퍼티들의 매핑을 포함한다.

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
    "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping>

    <class name="org.hibernate.examples.quickstart.Cat" table="CAT">

        <!-- A 32 hex character is our surrogate key. It's automatically
            generated by Hibernate with the UUID pattern. -->
        <id name="id" type="string" unsaved-value="null" >
            <column name="CAT_ID" sql-type="char(32)" not-null="true"/>
            <generator class="uuid.hex"/>
        </id>

        <!-- A cat has to have a name, but it shouldn' be too long. -->
        <property name="name">
            <column name="NAME" length="16" not-null="true"/>
        </property>

        <property name="sex"/>

        <property name="weight"/>

    </class>

</hibernate-mapping>

모든 영속 클래스는 식별자 속성을 가져야 한다(실제로 value-타입의 클래스들에 의존하지 않는, 엔티티들을 표현하는 유일한 클래스들은 엔티티을 가진 컴포넌트들로 매핑된다). 이 프로퍼티는 영속 객체들을 구별짓는데 사용된다: 만일 catA.getId().equals(catB.getId())이 true일 경우, 두 개의 cat들은 같고, 이 개념은 database identity로 명명된다.  Hibernate는 (데이터베이스 시퀀스, hi/lo 식별자 테이블들, 그리고 어플리케이션 할당 식별자들에 대한 native 생성기들을 포함하는) 다른 시나리오들에 대해 여러 가지 식별자 생성기들을 번들로 갖고 있다. 우리는 UUID 생성기(데이터이스에 의해 생성된 정수 대용 키들이 선호될 것이므로, 테스트용으로만 권장됨)를 사용하고 또한  Hibernate 생성된 식별자 값을 위한 CAT 테이블의 CAT_ID 컬럼을 (테이블의 프라이머리 키로서) 지정한다. 

Cat 의 모든 다른 프로퍼티들은 동일한 테이블로 매핑된다. name 프로퍼티의 경우에, 우리는 그것을 명시적인 데이터베이스 컬럼 선언으로 매핑시켰다. 데이터베이스 스키마가 Hibernate의 SchemaExport  도구에 의해 매핑 선언으로부터 (SQL DDL 문장들로) 자동적으로 생성될 때 이것이 특별히 유용하다. 모든 다른 프로퍼티들은 Hibernate의 디폴트 설정들을 사용하여 매핑되고, 디폴트 설정들은 당신이 가장 많은 시간을 필요로 하는 것이다. 데이터베이스 내의 테이블 CAT 은 다음과 같다:

 Column |         Type          | Modifiers
--------+-----------------------+-----------
 cat_id | character(32)         | not null
 name   | character varying(16) | not null
 sex    | character(1)          |
 weight | real                  |
Indexes: cat_pkey primary key btree (cat_id)

당신은 이제 수작업으로 당신의 데이터베이스 내에 이 테이블을 생성시킬 것이고, 만일 당신이 hbm2ddl 도구로 이 단계를 자동화 시키고자 원할 경우 20 장, 도구셋 안내를 읽어라. 이 도구는 테이블 정의, 맞춤형 컬럼 타입 컨스트레인트들, 유일 컨스트레인트들과 인덱스들을 포함하는, 전체 SQL DDL을 생성시킬 수 있다.

우리는 이제 Hibernate의 Session을 시작할 준비가 되어 있다. 그것은  persistence manager(영속 관리자)이고, 우리는 데이터베이스로 Cat를 저장하고 데이터베이스로부터 Cat를 검색하는데 그것을 사용한다. 그러나 먼저 우리는 SessionFactory로부터 Session (Hibernate의 작업 단위)를 얻어야 한다:

SessionFactory sessionFactory =
            new Configuration().configure().buildSessionFactory();

configure() 호출은 hibernate.cfg.xml 구성 파일을 로드시키고  Configuration  인스턴스를 초기화 시킨다. 당신이 SessionFactory(불변적임)를 빌드하기 이전에 당신은 Configuration에 접근함으로써 다른 프로퍼티들을 설정할 수 있다(그리고 심지어 매핑 메타데이터를 변경시킬 수 있다). 우리는 어디서 SessionFactory를 생성시키고 우리의 어플리케이션 속에서 어떻게 그것에 접근할 수 있나?

SessionFactory 는 대개 오직 한번만, 예를 들어 대개 load-on-startup 서블릿으로 시작 시에 빌드된다. 이것은 또한 당신이 당신의 서블릿들 내에 있는 인스턴스 변수 속에 그것을 유지하지 않을 것이지만 어떤 다른 위치에 유지시킬 것임을 의미한다. 더구나 우리는 어떤 종류의 Singleton을 필요로 하며, 따라서 우리는 어플리케이션 코드로 쉽게 SessionFactory 에 액세스 할 수 있다.  다음에 보여진 접근법은 두 문제 모두를 해결한다: 시작 구성과 SessionFactory에 대한 쉬운 접근.

우리는 HibernateUtil helper 클래스를 구현한다:

import org.hibernate.*;
import org.hibernate.cfg.*;

public class HibernateUtil {

    private static Log log = LogFactory.getLog(HibernateUtil.class);

    private static final SessionFactory sessionFactory;

    static {
        try {
            // Create the SessionFactory
            sessionFactory = new Configuration().configure().buildSessionFactory();
        } catch (Throwable ex) {
            // Make sure you log the exception, as it might be swallowed
            log.error("Initial SessionFactory creation failed.", ex);
            throw new ExceptionInInitializerError(ex);
        }
    }

    public static final ThreadLocal session = new ThreadLocal();

    public static Session currentSession() {
        Session s = (Session) session.get();
        // Open a new Session, if this Thread has none yet
        if (s == null) {
            s = sessionFactory.openSession();
            session.set(s);
        }
        return s;
    }

    public static void closeSession() {
        Session s = (Session) session.get();
        if (s != null)
            s.close();
        session.set(null);
    }
}

이 클래스는 static 초기자를 가진 SessionFactory를 처리할 뿐만 아니라 또한 현재의 쓰레드를 위한 Session 을 보관하는 ThreadLocal변수를 갖는다. 이 helper를 사용하려고 시도하기 전에 thread-local 변수에 대한 자바 개념을 이해해야 한다. 보다 복잡하고 강력한 HibernateUtil 클래스는  http://caveatemptor.hibernate.org/의 CaveatEmptor에서 찾을 수 있다.

 SessionFactory는 threadsafe이고, 많은 쓰레드들이 동시에 그것에 접근할 수 있고 Session들을 요청할 수 있다. 하나의 Session은 데이터베이스에 대해 한 개의 단위 작업을 나타내는 non-threadsafe 객체이다.  Session들은 SessionFactory로부터 열려지고 모든 작업이 완료될 때 닫혀진다. 당신의 서블릿의 process() 메소드 내에 있는 예제는 다음과 같을 수 있다(예외상황 처리 없이): 

Session session = HibernateUtil.currentSession();
Transaction tx = session.beginTransaction();

Cat princess = new Cat();
princess.setName("Princess");
princess.setSex('F');
princess.setWeight(7.4f);

session.save(princess);

tx.commit();
HibernateUtil.closeSession();

하나의 Session 내에서 모든 데이터베이스 오퍼레이션은 데이터베이스 오퍼레이션들(심지어 읽기 전용 오퍼레이션들 조차도)을 격리시키는 하나의 트랜잭션 내부에서 발생한다. 우리는 기본 트랜잭션 방도(우리의 경우, JDBC 틀내잭션들)로부터 추상화시키는데 Hibernates Transaction API 를 사용한다. 이것은 우리의 코드가 임의의 변경들 없이도 (JTA를 사용하는) 컨테이너-관리되는 트랜잭션들에 배치되는 것을 허용해준다.

당신이 원하는 만큼 당신이 HibernateUtil.currentSession();을 호출할 수 있고, 당신은 이 쓰레드의 현재 Session을 항상 얻을 것임을 노트하라. 당신은 서블릿 코드 내에서든 또는 서블릿 필터 내에서든 HTTP response가 전송되기 전에, 당신의 단위 작업이 완료된 후에 Session을 확실히 닫아야 한다.  두 번째 옵션의 좋은 측면은 쉬운 lazy 초기화이다: 뷰가 렌더링 될 때 Session이 여전히 열려져 있어서,  Hibernate는 당신이 현재 객체 그래프를 네비게이트 하는 동안 초기화 되지 않은 객체들을 로드시킬 수 있다. 

Hibernate는 데이터베이스로부터 객체들을 검색하는데 사용될 수 있는 다양한 메소드들을 갖고 있다. 가장 유연한 방법은 Hibernate Query Language (HQL)을 사용하는 것이다. Hibernate Query Language (HQL)은 배우기가 쉽고 SQL에 대한 강력한 객체 지향 확장이다:

Transaction tx = session.beginTransaction();

Query query = session.createQuery("select c from Cat as c where c.sex = :sex");
query.setCharacter("sex", 'F');
for (Iterator it = query.iterate(); it.hasNext();) {
    Cat cat = (Cat) it.next();
    out.println("Female Cat: " + cat.getName() );
}

tx.commit();

Hibernate는 또한 type-safe 질의들을 공식화 시키는데 사용될 수 있는 객체 지향 query by criteria API을 제공한다. 물론 Hibernate는 데이터베이스와의 모든 SQL 통신을 위해 PreparedStatement들과 파라미터 바인딩을 사용한다. 당신은 또한 Hibernate 직접적인 SQL 질의 특징을 사용할 수도 있거나 드문 경우에 Session 로부터 plain JDBC 커넥션을 얻을 수도 있다.

우리는 이 작은 튜토리얼 내에서 단지 Hibernate의 표면을 훑기만 했다. 우리는 우리의 예제들 속에 어떤 서블릿 지정적 코드를 포함하지 않음을 노트하라. 당신이 적합한지를 알려고 할 때 당신은 당신 자신의 서블릿을 생성시켜야 하고 Hibernate 코드를 삽입해야 한다. 

데이터 접근 계층으로서 Hibernate는 당신의 어플리케이션에 강하게 통합됨을 염두에 두라. 대개 모든 다른 레이어들은 영속 메커니즘에 의존했다. 당신은 이 설계의 함축을 확실히 이해하도록 하라.

보다 복잡한 어플리케이션 예제는 http://caveatemptor.hibernate.org/ 를 보고 http://caveatemptor.hibernate.org/에 있는 다른 튜토리얼들을 살펴보라.

Hibernate 아키텍처에 대한 (매우) 높은 수준의 개요: 

이 다이어그램은 어플리케이션에 영속화 서비스들(과 영속 객체들)을 제공하기 위해 데이터베이스와 컨피그레이션을 사용하는 Hibernate를 보여준다.

우리는 런타임 아키텍처에 대한 보다 상세한 뷰를 보여주고 싶다. 불행하게도, Hibernate는 유연하며 몇 가지 접근법들을 제공한다. 우리는 두 가지 극단을 보여줄 것이다. "경량급" 아키텍처는 그것 자신의 JDBC 커넥션들을 제공하고 그것 자신의 트랜잭션들을 관리하는 어플리케이션을 갖는다. 이 접근법은 Hibernate의 API의 최소 부분집합을 사용한다:

"전체 정수" 아키텍처는 기본 JDBC/JTA로부터 어플리케이션을 추상화 시키고 Hibernate로 하여금 상세한 것을 처리하게 한다.

다음은 다이어그램들 내에 있는 객체들에 대한 몇가지 정의들이다:

주어진 "경량급" 아키텍처의 경우, 어플리케이션은 JTA 또는 JDBC와 직접 대화하기 위해서 Transaction/TransactionFactory 과/또는 ConnectionProvider API들을 무시한다.

영속 클래스들의 인스턴스는 세개의 상태들 중 하나 일 수 있다. 그것들(상태들)은 영속  컨텍스트(persistence context)에 대해 정의된다. Hibernate Session 객체는 영속 컨텍스트이다:

JMX는 자바 컴포넌트 관리를 위한 J2EE 표준이다. Hibernate는 JMX 표준 서비스를 통해 관리될 수도 있다. 우리는 배포본 내에 MBean 구현, org.hibernate.jmx.HibernateService 을 제공한다.

JBoss 어플리케이션 서버 상에 Hibernae를 JMX 서비스로서 배치하는 방법에 대한 예제는 JBoss 사용자 가이드를 보길 바란다. JBoss 어플리케이션 서버 상에서, 만일 당신이 JMX를 사용하여 배치할 경우 당신은 또한 다음 이점들을 얻는다:

Hibernate는 JCA 커넥터로서 구성될 수도 있다. 상세한 것은 웹 사이트를 보길 바란다.

org.hibernate.cfg.Configuration 의 인스턴스는 어플리케이션의 Java 타입들을 SQL 데이터베이스 타입으로의 전체 매핑 집합을 표현한다. Configuration 은 (불변의) SessionFactory를 빌드하는데 사용된다. 매핑들은 여러 가지 XML 매핑 파일들로부터 컴파일 된다.

당신은 Configuration 인스턴스를 초기화 함으로써 Configuration 인스턴스를 얻을 수 있다. 다음은 (classpath 내에 있는) 두 개의 XML 매핑 파일 속에 정의된 매핑들로부터 데이터저장소를 설정하는 예제이다:

Configuration cfg = new Configuration()
    .addFile("Item.hbm.xml")
    .addFile("Bid.hbm.xml");

(때때로 더 나은) 다른 방법은 getResourceAsStream()을 사용하여 Hibernate로 하여금 매핑 파일을 로드시키도록 하는 것이다:

Configuration cfg = new Configuration()
    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class);

그런 다음 Hibernate는 classpath 내에 /org/hibernate/auction/Item.hbm.xml 과 /org/hibernate/auction/Bid.hbm.xml로 명명된 매핑 파일들을 룩업할 것이다. 이 접근법은 임의의 하드코딩된 파일 이름들을 제거한다. 

Configuration 은 또한 다양한 옵션 프로퍼티들을 지정한다: 

Configuration cfg = new Configuration()
    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class)
    .setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect")
    .setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test")
    .setProperty("hibernate.order_updates", "true");

이것은 컨피그레이션 프로퍼티들을 Hibernate에 전달하는 유일한 방법이 아니다. 여러 가지 옵션들은 다음을 포함한다:

hibernate.properties 는 당신이 빠르게 시작하고 원할 경우 가장 쉬운 접근법이다. 

Configuration 은 시작 시(startup-time) 객체로서 일단 SessionFactory가 생성되면 폐기되게끔 예정되어 있다. 

모든 매핑들이 Configuration에 의해 파싱되었을 때, 어플리케이션은 Session 인스턴스들에 대한 팩토리를 얻어야 한다. 이 팩토리는 모든 어플리케이션 쓰레드들에 의해 공유되도록 고안되었다: 

SessionFactory sessions = cfg.buildSessionFactory();

하지만 Hibernate는 당신의 어플리케이션이 하나 이상의 SessionFactory를 초기화 시키는 것을 허용한다. 이것은 당신이 하나 이상의 데이터베이스를 사용하는 경우에 유용하다. 

SessionFactory 는 사용자 제공 JDBC 커넥션 상에서 Session 을 열 수 있다. 이 설계 선택은 그것이 만족될 때마다 어플리케이션이 JDBC 커넥션들을 얻는 것을 자유롭게 해준다:

java.sql.Connection conn = datasource.getConnection();
Session session = sessions.openSession(conn);

// 어떤 데이터 액세스 작업을 행한다 

어플리케이션은 동일한 JDBC 커넥션 상에서 두 개의 동시적인 Session들 을 열지 않도록 주의해야 한다!

우리는 사용자 제공 JDBC 커넥션들을 권장하지 않는다. 왜냐하면 Hibernate가 캐싱을 불가능하게 할 것이기 때문이고(그것은 당신이 주어진 커넥션 상에서 실행할 수 있다는 사실을 알지 못한다) 대개 다음 옵션들 중 하나가 더 적절하기 때문이다.

대개 당신은 SessionFactory 를 생성시키고 당신을 위한 JDBC 커넥션들을 풀링시키고자 원한다. 만일 당신이 이 접근법을 취하라 경우, Session을 여는 것은 다음과 같이 간단하다:

Session session = sessions.openSession(); // 새로운 Session을 연다

데이터베이스에 대한 업근을 필요로 하는 어떤 것을 당신이 행하자 마자, JDBC 커넥션이 그 풀로부터 획득될 것이다.

이것이 동작하도록 하기 위해, 우리는몇몇 JDBC 커넥션 프로퍼티들을 Hibernate에 전달할 필요가 있다. 모든 Hibernate 프로퍼티 이름들과 의미들은 org.hibernate.cfg.Environment 클래스 상에 정의되어 있다.우리는 이제 JDBC 커넥션 구성을 위한 가장 중요한 설정들을 설명할 것이다.

당신이 다음 프로퍼티들을 설정할 경우, Hibernate는 java.sql.DriverManager를 사용하여 커넥션들을 획득(그리고 풀링)할 것이다.:

하지만 Hibernate 자신의 커넥션 풀링 알고리즘은 아주 기본적이다. 그것은 당신이 시작하는 것을 도와주려고 의도되었고 제품 시스템 용도 또는 퍼포먼스 테스트용으로 고안되지 않았다. 최상의 퍼포먼스와 안정성을 위해서는 제 3의 풀을 사용하라. 즉 hibernate.connection.pool_size 프로퍼티를 커넥션 풀 지정 설정들로 대체하라. 이것은 Hibernate의 내부 pool을 오프시킬 것이다. 예를 들어 당신은 C3P0를 사용할 수도 있다.

C3P0는 lib 디펙토리 속에 Hibernate에 배포된 오픈 소스 JDBC 커넥션 풀이다. 당신이 hibernate.c3p0.* 프로퍼티들을 설정할 경우  Hibernate는  커넥션 풀링을 위해 그것의 C3P0ConnectionProvider 를 사용할 것이다. 만일 당신이 Proxool 을 사용하고자 원할 경우 패키지화 된 hibernate.properties 를 참조하고 추가 정보는 Hibernate 웹 사이트를 참조하라.

다음은 C3P0에 대한 사용하는 예제 hibernate.properties 파일이다: 

hibernate.connection.driver_class = org.postgresql.Driver
hibernate.connection.url = jdbc:postgresql://localhost/mydatabase
hibernate.connection.username = myuser
hibernate.connection.password = secret
hibernate.c3p0.min_size=5
hibernate.c3p0.max_size=20
hibernate.c3p0.timeout=1800
hibernate.c3p0.max_statements=50
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect

어플리케이션 서버 내부의 용도로, 당신은 JNDI로 등록된 어플리케이션 서버 Datasource로부터 커넥션을 얻기 위해 항상 Hibernate를 구성해야 한다. 당신은 적어도 다음 프로퍼티들 중 하나를 설정할 필요가 잇을 것이다.

다음은 어플리케이션 서버 제공 JNDI 데이터소스용 예제 hibernate.properties 파일이다:

hibernate.connection.datasource = java:/comp/env/jdbc/test
hibernate.transaction.factory_class = \
    org.hibernate.transaction.JTATransactionFactory
hibernate.transaction.manager_lookup_class = \
    org.hibernate.transaction.JBossTransactionManagerLookup
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect

JNDI datasource로부터 얻어진 JDBC 커넥션들은 어플리케이션 서버의 컨테이너에 의해 관리되는 트랜잭션들에 자동적으로 참여할 것이다.

임의의 커넥션 프로퍼티들은 프로퍼티 이름 앞에 "hibernate.connnection" 을 첨가하여 부여될 수 있다. 예를 들어 당신은 hibernate.connection.charSet을 사용하여 charSet을 지정할 수도 있다.

당신은 org.hibernate.connection.ConnectionProvider 인터페이스를 구현함으로써 JDBC 커넥션들을 얻는 당신 자신의 플러그인 방도를 정의할수도 있다. 당신은 hibernate.connection.provider_class를 설정하여 맞춤형 구현을 선택할 수도 있다.

실행 시에 Hibernate의 행위를 제어하는 많은 다른 프로퍼티들이 존재한다. 모든 것이 옵션이지만 합당한 디폴트 값들을 갖는다. 

경고: 이들 프로퍼티들 중 몇몇은 ''system-level" 전용이다. 시스템 레벨 프로퍼티들은 오직 java -Dproperty=value 또는 hibernate.properties를 통해서만 설정될 수 있다. 그것들은 위에 설명된 다른 기법들에 의해 설정될 수 없다.  . 

hibernate.query.substitutions true=1, false=0

hibernate.query.substitutions toLowercase=LOWER

Hibernate는 Apache commons-logging를 사용하여 다양한 이벤트들을 로그시킨다. 

commons-logging 서비스는 (만일 당신이 classpath 내에 log4j.jar를 포함할 경우) Apache Log4j로 또는 (JDK1.4 이상의 버전에서 실행될 경우) JDK 1.4 로깅으로 직접 출력할 것이다. 당신은 http://jakarta.apache.org에서 Log4j를 다운로드 할 수 있다. Log4j를 사용하기 위해, 당신은 log4j.properties 파일을 당신의 classpath 내에 위치지울 필요가 있을 것이고, 예제 properties 파일은 Hibernate의  src/ 디렉토리 내에 배포되어 있다.

우리는 당신이 Hibernate의 로그 메시지들에 익숙해지는 것을 강력하게 권장한다. 많은 작업은 Hibernate 로그를 읽기 불가능하게 만들지 않게끔 가능한 한 상세하게 Hibernate 로그를 집어 넣었다. 그것은 본질적인 문제던지기 장치이다. 가장 흥미로운 로그 카테고리들이 다음에 있다:

Hibernate로 어플리케이션들을 개발할 때, 당신은 거의 항상 org.hibernate.SQL 카테고리에 대해 debug 모드로 설정하거나 hibernate.show_sql 프로퍼티를 이용가능하게 하여 작업해야 할 것이다.

 org.hibernate.cfg.NamingStrategy 인터페이스는 데이터베이스 객체들과 스키마 요소들에 대한 "네이밍 표준"을 지정하는 것을 당신에게 허용해준다.

당신은 Java 식별자들로부터 데이터베이스 식별자들을 자동적으로 생성시키거나 매핑 파일에 주어진 "논리적" 컬럼과 테이블 이름들을 "물리적" 테이블과 컬럼 이름들로 자동적으로 처리하는 규칙들을 제공할 수 있다. 이 특징은 반복되는 노이즈(예를 들어 TBL_접두어들)를 제거함으로써, 매핑 문서의 말많은 장황함을 감소시키도록 도와준다. Hibernate에 의해 사용되는 디폴트 방도는 아주 작은 작품이다.

당신은 매핑들을 추가하기 이전에 Configuration.setNamingStrategy()를 호출함으로써 다른 방도를 지정할 수 있다:

SessionFactory sf = new Configuration()
    .setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
    .addFile("Item.hbm.xml")
    .addFile("Bid.hbm.xml")
    .buildSessionFactory();

org.hibernate.cfg.ImprovedNamingStrategy 는 어떤 어플리케이션들에 대한 유용한 시작점일 수 있는 미리 빌드된 방도이다.

구성에 대한 다른 접근법은 hibernate.cfg.xml로 명명된 파일 속에 전체 구성을 지정하는 것이다. 이 파일은 hibernate.properties 파일에 대한 대용물로서 사용될 수 있거나, 만일 둘 다 존재할 경우에 프로퍼티들을 중복정의하는데 사용될 수 있다.

XML 구성 파일은 디폴트로 당신의 CLASSPATH의 루트에 존재하는 것이 기대된다. 다음은 예제이다:

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
    "-//Hibernate/Hibernate Configuration DTD//EN"
    "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <!-- a SessionFactory instance listed as /jndi/name -->
    <session-factory
        name="java:hibernate/SessionFactory">

        <!-- properties -->
        <property name="connection.datasource">java:/comp/env/jdbc/MyDB</property>
        <property name="dialect">org.hibernate.dialect.MySQLDialect</property>
        <property name="show_sql">false</property>
        <property name="transaction.factory_class">
            org.hibernate.transaction.JTATransactionFactory
        </property>
        <property name="jta.UserTransaction">java:comp/UserTransaction</property>

        <!-- mapping files -->
        <mapping resource="org/hibernate/auction/Item.hbm.xml"/>
        <mapping resource="org/hibernate/auction/Bid.hbm.xml"/>

        <!-- cache settings -->
        <class-cache class="org.hibernate.auction.Item" usage="read-write"/>
        <class-cache class="org.hibernate.auction.Bid" usage="read-only"/>
        <collection-cache class="org.hibernate.auction.Item.bids" usage="read-write"/>

    </session-factory>

</hibernate-configuration>

당신이 볼 수 있듯이, 이 접근법의 장점은 구성에 대한 매핑 파일 이름들을 구체화 시키는 것이다. hibernate.cfg.xml은 또한 당신이 Hibernate 캐시를 튜닝해야할 때 보다 편리하다. hibernate.properties 또는 hibernate.cfg.xml 어느 것을 사용하는가는 당신의 선택이다. XML 구문을 사용하는 위에 언급된 이점들을 제외하면 둘다 같은 것임을 노트하라.

Hibernate 구성을 사용할 경우, Hibernate 사용은 다음과 같이 간단하다

SessionFactory sf = new Configuration().configure().buildSessionFactory();

당신은 다음을 사용하여 다른 XML 구성 파일을 찾아낼 수 있다

SessionFactory sf = new Configuration()
    .configure("catdb.cfg.xml")
    .buildSessionFactory();

대부분의 자바 어플리케이션들은 고양이과들을 표현하는 영속 클래스를 필요로 한다.

package eg;
import java.util.Set;
import java.util.Date;

public class Cat {
    private Long id; // identifier

    private Date birthdate;
    private Color color;
    private char sex;
    private float weight;
    private int litterId;

    private Cat mother;
    private Set kittens = new HashSet();

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

    void setBirthdate(Date date) {
        birthdate = date;
    }
    public Date getBirthdate() {
        return birthdate;
    }

    void setWeight(float weight) {
        this.weight = weight;
    }
    public float getWeight() {
        return weight;
    }

    public Color getColor() {
        return color;
    }
    void setColor(Color color) {
        this.color = color;
    }

    void setSex(char sex) {
        this.sex=sex;
    }
    public char getSex() {
        return sex;
    }

    void setLitterId(int id) {
        this.litterId = id;
    }
    public int getLitterId() {
        return litterId;
    }

    void setMother(Cat mother) {
        this.mother = mother;
    }
    public Cat getMother() {
        return mother;
    }
    void setKittens(Set kittens) {
        this.kittens = kittens;
    }
    public Set getKittens() {
        return kittens;
    }
    
    // addKitten not needed by Hibernate
    public void addKitten(Cat kitten) {
    	kitten.setMother(this);
	kitten.setLitterId( kittens.size() ); 
        kittens.add(kitten);
    }
}

준수할 네 개의 주요 규칙들이 다음에 있다:

서브클래스는 또한 첫 번째 규칙들과 두 번째 규칙들을 주시해야 한다. 그것은 슈퍼클래스 Cat 로부터 그것의 identifier 프로퍼티를 상속받는다. 

package eg;

public class DomesticCat extends Cat {
        private String name;

        public String getName() {
                return name;
        }
        protected void setName(String name) {
                this.name=name;
        }
}

만일 당신이 영속 클래스들의 인스턴스들을 Set(many-valued 연관관계들에 대해 권장되는 방법)  속에 집어넣고자 원하고 detached 인스턴스들의 reattachment(재첨부)를 사용하려고 할 경우에 당신은 equals() 과 hashCode() 메소드들을 오버라이드 시켜야 한다.

Hibernate는 특정 session 범위 내에서만 persistent identity(데이터베이스 행)과 Java identity의 같음을 보장한다.  따라서 우리가 다른 세션들에서 검색된 인스턴스들을 혼합시키자마자, 우리가 Set들에 대해 유의미하게 만들고자 원할 경우,  우리는 equals() 와 hashCode()를 구현해야 한다.

가장 명백한 방법은 두 객체들의 identifier 값을 비교함으로써 equals()/hashCode()를 구현하는 것이다. 만일 그 값이 동일하다면, 둘다 동일한 데이터베이스 행이어야 하고, 그러므로 그것들은 같다(둘다 하나의 Set에 추가되는 경우에, 우리는 Set 속에서 하나의 요소만을 갖게 될 것이다). 불행하게도, 우리는 생성된 식별자들에 대해 그 접근법을 사용할 수 없다! Hibernate는 오직 identifier 값들을 영속화 되는 객체들에 할당할 것이고, 새로이 생성된 인스턴스는 임의의 identifier 값을 갖지 않을 것이다! 만일 인스턴스가 저장되지 않고 현재 Set 속에 있을 경우, 그것을 저장하는것은 하나의 identifier 값을 그 객체에게 할당할 것이다. 만일 equals()와  hashCode()가 identifier 값에 기초할 경우, hash 코드는 Set의 계약을 파기하여 변경될 것이다. 이 문제에 대한 전체 논의에 대해서는 Hibernate 웹 사이트를 보라. 이것은 Hibernate 쟁점이 아니지만, 객체 identity와 equality에 관한 통상의 자바 의미론임을 노트하라.

우리는 Business key equality를 사용하여 equals()와 hashCode()를 구현할 것 권장한다. Business key equality는 equals() 메소드가 비지니스 키, 즉 실세계에서 우리의 인스턴스를 식별하게 될 키(natural 후보 키)를 형성하는 프로퍼티들만을 비교한다는 점을 의미한다 :

public class Cat {

    ...
    public boolean equals(Object other) {
        if (this == other) return true;
        if ( !(other instanceof Cat) ) return false;

        final Cat cat = (Cat) other;

        if ( !cat.getLitterId().equals( getLitterId() ) ) return false;
        if ( !cat.getMother().equals( getMother() ) ) return false;

        return true;
    }

    public int hashCode() {
        int result;
        result = getMother().hashCode();
        result = 29 * result + getLitterId();
        return result;
    }

}

다음 특징들은 현재 실험적으로 고려되고 있으며 장래의 특징에서 변경될 수 있다.

영속 엔티티들은 반드시 실행시에 POJO 클래스들로 또는 자바빈즈 객체들로 표현되어야할 필요는 없다. Hibernate는 또한 (실행 시에 Map들을 가진 Map들을 사용하여) 동적인 모형들을 지원하고 DOM4J 트리로서 엔티티들의 표현을 지원한다. 이 접근법으로, 당신은 영속 클래스들을 작성하지 않고, 오직 매핑 파일들 만을 작성한다.

디폴트로, Hibernate는 통산의 POJO 모드로 동작한다. 당신은 default_entity_mode 구성 옵션을 사용하여 특별한 SessionFactory에 대해 디폴트 엔티티 표현 모드를 설정할 수 있다(표 3.3, “Hibernate 구성 프로퍼티들”을 보라).

다음 예제들은 Map들을 사용하는 표현을 설명한다. 먼저 매핑 파일에서, entity-name이 클래스 이름 대신에(또는 클래스 이름에 덧붙여) 선언되어야 한다:

<hibernate-mapping>

    <class entity-name="Customer">

        <id name="id"
            type="long"
            column="ID">
            <generator class="sequence"/>
        </id>

        <property name="name"
            column="NAME"
            type="string"/>

        <property name="address"
            column="ADDRESS"
            type="string"/>

        <many-to-one name="organization"
            column="ORGANIZATION_ID"
            class="Organization"/>

        <bag name="orders"
            inverse="true"
            lazy="false"
            cascade="all">
            <key column="CUSTOMER_ID"/>
            <one-to-many class="Order"/>
        </bag>

    </class>
    
</hibernate-mapping>

런타임 시에, 당신은 단지 HashMaps를 초기화 시키고 특별한 타입을 참조하는데 Hibernate 엔티티 이름을 사용한다:

Session s = openSession();
Transaction tx = s.beginTransaction();
Session s = openSession();

// 고객을 생성시킨다 
Map david = new HashMap();
david.put("name", "David");

// 조직을 생성시킨다 
Map foobar = new HashMap();
foobar.put("name", "Foobar Inc.");

// 양자를 연결한다
david.put("organization", foobar);

// 양자를 저장한다
s.save("Customer", david);
s.save("Organization", foobar);

tx.commit();
s.close();

Session dynamicSession = pojoSession.getSession(EntityMode.MAP);

// 고객을 생성한다
Map david = new HashMap();
david.put("name", "David");
dynamicSession.save("Customer", david);
...
dynamicSession.flush();
dynamicSession.close()
...
// pojoSession을 계속 진행한다

TODO: property 패키지와 proxy 패키지 내에 user-extension 프레임웍을 문서화 할 것.

객체/관계형 매핑들은 대개 XML 문서로 정의된다. 매핑 문서는 가독성이 있고 수작업 편집이 가능하도록 설계되어 있다. 매핑 언어는 매핑들이 테이블 선언들이 아닌, 영속 클래스 선언들로 생성된다는 의미에서 자바 중심적이다.

심지어 많은 Hibernate 사용자들이 수작업으로 XML을 작성하고자 선택할지라도, XDoclet, Middlegen, 그리고 AndroMDA를 포함하는, 매핑 문서를 생성시키는 많은 도구들이 존재한다는 점에 주목하라.

예제 매핑으로 시작하자:

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
      "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
          "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="eg">

        <class name="Cat" 
            table="cats"
            discriminator-value="C">
                
                <id name="id">
                        <generator class="native"/>
                </id>

                <discriminator column="subclass" 
                     type="character"/>

                <property name="weight"/>

                <property name="birthdate"
                    type="date" 
                    not-null="true" 
                    update="false"/>

                <property name="color"
                    type="eg.types.ColorUserType"
                    not-null="true"
                    update="false"/>

                <property name="sex"
                    not-null="true" 
                    update="false"/>

                <property name="litterId"
                    column="litterId"
                    update="false"/>

                <many-to-one name="mother"
                    column="mother_id"
                    update="false"/>

                <set name="kittens"
                    inverse="true"
                    order-by="litter_id">
                        <key column="mother_id"/>
                        <one-to-many class="Cat"/>
                </set>

                <subclass name="DomesticCat"
                    discriminator-value="D">

                        <property name="name" 
                            type="string"/>

                </subclass>

        </class>

        <class name="Dog">
                <!-- mapping for Dog could go here -->
        </class>

</hibernate-mapping>

우리는 이제 매핑 문서의 내용을 논의할 것이다. 우리는 Hibernate에 의해 실행 시에 사용되는 문서 요소들과 속성들 만을 설명할 것이다. 매핑 문서는 또한 스키마 내보내기 도구에 의해 내보내진 데이터베이스 스키마에 영향을 주는 어떤 특별한 옵션 속성들과 요소들을 포함한다. (예를 들어 not-null 속성.)

<hibernate-mapping
         schema="schemaName"                          (1)
         catalog="catalogName"                        (2)
         default-cascade="cascade_style"              (3)
         default-access="field|property|ClassName"    (4)
         default-lazy="true|false"                    (5)
         auto-import="true|false"                     (6)
         package="package.name"                       (7)
 />

<class
        name="ClassName"                              (1)
        table="tableName"                             (2)
        discriminator-value="discriminator_value"     (3)
        mutable="true|false"                          (4)
        schema="owner"                                (5)
        catalog="catalog"                             (6)
        proxy="ProxyInterface"                        (7)
        dynamic-update="true|false"                   (8)
        dynamic-insert="true|false"                   (9)
        select-before-update="true|false"             (10)
        polymorphism="implicit|explicit"              (11)
        where="arbitrary sql where condition"         (12)
        persister="PersisterClass"                    (13)
        batch-size="N"                                (14)
        optimistic-lock="none|version|dirty|all"      (15)
        lazy="true|false"                             (16)
        entity-name="EntityName"                      (17)
        check="arbitrary sql check condition"         (18)
        rowid="rowid"                                 (19)
        subselect="SQL expression"                    (20)
        abstract="true|false"                         (21)
        entity-name="EntityName"
/>

<class name="Summary">
    <subselect>
        select item.name, max(bid.amount), count(*)
        from item
        join bid on bid.item_id = item.id
        group by item.name
    </subselect>
    <synchronize table="item"/>
    <synchronize table="bid"/>
    <id name="name"/>
    ...
</class>

<id
        name="propertyName"                                     (1)
        type="typename"                                         (2)
        column="column_name"                                    (3)
        unsaved-value="null|any|none|undefined|id_value"        (4)
        access="field|property|ClassName">                      (5)

        <generator class="generatorClass"/>
</id>

<id name="id" type="long" column="cat_id">
        <generator class="org.hibernate.id.TableHiLoGenerator">
                <param name="table">uid_table</param>
                <param name="column">next_hi_value_column</param>
        </generator>
</id>

<id name="id" type="long" column="cat_id">
        <generator class="hilo">
                <param name="table">hi_value</param>
                <param name="column">next_value</param>
                <param name="max_lo">100</param>
        </generator>
</id>

<id name="id" type="long" column="cat_id">
        <generator class="seqhilo">
                <param name="sequence">hi_value</param>
                <param name="max_lo">100</param>
        </generator>
</id>

<id name="id" type="long" column="person_id">
        <generator class="sequence">
                <param name="sequence">person_id_sequence</param>
        </generator>
</id>

<id name="id" type="long" column="person_id" unsaved-value="0">
        <generator class="identity"/>
</id>

<id name="id" type="long" column="person_id">
        <generator class="select">
                <param name="key">socialSecurityNumber</param>
        </generator>
</id>

<composite-id
        name="propertyName"
        class="ClassName"
        unsaved-value="undefined|any|none"
        access="field|property|ClassName">

        <key-property name="propertyName" type="typename" column="column_name"/>
        <key-many-to-one name="propertyName class="ClassName" column="column_name"/>
        ......
</composite-id>

<composite-id>
        <key-property name="medicareNumber"/>
        <key-property name="dependent"/>
</composite-id>

<discriminator
        column="discriminator_column"                      (1)
        type="discriminator_type"                          (2)
        force="true|false"                                 (3)
        insert="true|false"                                (4)
        formula="arbitrary sql expression"                 (5)
/>

<discriminator
    formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end"
    type="integer"/>

<version
        column="version_column"                            (1)
        name="propertyName"                                (2)
        type="typename"                                    (3)
        access="field|property|ClassName"                  (4)
        unsaved-value="null|negative|undefined"            (5)
/>

<timestamp
        column="timestamp_column"           (1)
        name="propertyName"                 (2)
        access="field|property|ClassName"   (3)
        unsaved-value="null|undefined"      (4)
/>

<property
        name="propertyName"                 (1)
        column="column_name"                (2)
        type="typename"                     (3)
        update="true|false"                 (4)
        insert="true|false"                 (4)
        formula="arbitrary SQL expression"  (5)
        access="field|property|ClassName"   (6)
        lazy="true|false"                   (7)
        unique="true|false"                 (8)
        not-null="true|false"               (9)
        optimistic-lock="true|false"        (10)
/>

<property name="totalPrice"
    formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p
                WHERE li.productId = p.productId
                AND li.customerId = customerId
                AND li.orderNumber = orderNumber )"/>

<many-to-one
        name="propertyName"                                (1)
        column="column_name"                               (2)
        class="ClassName"                                  (3)
        cascade="cascade_style"                            (4)
        fetch="join|select"                                (5)
        update="true|false"                                (6)
        insert="true|false"                                (6)
        property-ref="propertyNameFromAssociatedClass"     (7)
        access="field|property|ClassName"                  (8)
        unique="true|false"                                (9)
        not-null="true|false"                              (10)
        optimistic-lock="true|false"                       (11)
        lazy="true|false"                                  (12)
        not-found="ignore|exception"                       (13)
        entity-name="EntityName"
/>

<many-to-one name="product" class="Product" column="PRODUCT_ID"/>

<property name="serialNumber" unique="true" type="string" column="SERIAL_NUMBER"/>

<many-to-one name="product" property-ref="serialNumber" column="PRODUCT_SERIAL_NUMBER"/>

<one-to-one
        name="propertyName"                                (1)
        class="ClassName"                                  (2)
        cascade="cascade_style"                            (3)
        constrained="true|false"                           (4)
        fetch="join|select"                                (5)
        property-ref="propertyNameFromAssociatedClass"     (6)
        access="field|property|ClassName"                  (7)
        formula="any SQL expression"                       (8)
        entity-name="EntityName"
/>

<one-to-one name="person" class="Person"/>

<one-to-one name="employee" class="Employee" constrained="true"/>

<class name="person" table="PERSON">
    <id name="id" column="PERSON_ID">
        <generator class="foreign">
            <param name="property">employee</param>
        </generator>
    </id>
    ...
    <one-to-one name="employee"
        class="Employee"
        constrained="true"/>
</class>

<many-to-one name="person" class="Person" column="PERSON_ID" unique="true"/>

<one-to-one name"employee" class="Employee" property-ref="person"/>

<component 
        name="propertyName"                 (1)
        class="className"                   (2)
        insert="true|false"                 (3)
        update="true|false"                 (4)
        access="field|property|ClassName"   (5)
        lazy="true|false"                   (6)
        optimistic-lock="true|false"        (7)
        unique="true|false"                 (8)
>
        
        <property ...../>
        <many-to-one .... />
        ........
</component>

<properties 
        name="logicalName"                  (1)
        insert="true|false"                 (2)
        update="true|false"                 (3)
        optimistic-lock="true|false"        (4)
        unique="true|false"                 (5)
>
        
        <property ...../>
        <many-to-one .... />
        ........
</properties>

<class name="Person">
    <id name="personNumber"/>
    ...
    <properties name="name" 
            unique="true" update="false">
        <property name="firstName"/>
        <property name="initial"/>
        <property name="lastName"/>
    </properties>
</class>

<many-to-one name="person" 
         class="Person" property-ref="name">
    <column name="firstName"/>
    <column name="initial"/>
    <column name="lastName"/>
</many-to-one>

<subclass
        name="ClassName"                              (1)
        discriminator-value="discriminator_value"     (2)
        proxy="ProxyInterface"                        (3)
        lazy="true|false"                             (4)
        dynamic-update="true|false"
        dynamic-insert="true|false"
        entity-name="EntityName">

        <property .... />
        .....
</subclass>

<hibernate-mapping>
    <subclass name="DomesticCat" extends="Cat" discriminator-value="D">
         <property name="name" type="string"/>
    </subclass>
</hibernate-mapping>

<joined-subclass
        name="ClassName"                    (1)
        table="tablename"                   (2)
        proxy="ProxyInterface"              (3)
        lazy="true|false"                   (4)
        dynamic-update="true|false"
        dynamic-insert="true|false"
        schema="schema"
        catalog="catalog"
        extends="SuperclassName"
        persister="ClassName"
        subselect="SQL expression"
        entity-name="EntityName">

        <key .... >

        <property .... />
        .....
</joined-subclass>

<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD//EN"
        "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="eg">

        <class name="Cat" table="CATS">
                <id name="id" column="uid" type="long">
                        <generator class="hilo"/>
                </id>
                <property name="birthdate" type="date"/>
                <property name="color" not-null="true"/>
                <property name="sex" not-null="true"/>
                <property name="weight"/>
                <many-to-one name="mate"/>
                <set name="kittens">
                        <key column="MOTHER"/>
                        <one-to-many class="Cat"/>
                </set>
                <joined-subclass name="DomesticCat" table="DOMESTIC_CATS">
                    <key column="CAT"/>
                    <property name="name" type="string"/>
                </joined-subclass>
        </class>

        <class name="eg.Dog">
                <!-- mapping for Dog could go here -->
        </class>

</hibernate-mapping>

<union-subclass
        name="ClassName"                    (1)
        table="tablename"                   (2)
        proxy="ProxyInterface"              (3)
        lazy="true|false"                   (4)
        dynamic-update="true|false"
        dynamic-insert="true|false"
        schema="schema"
        catalog="catalog"
        extends="SuperclassName"
        abstract="true|false"
        persister="ClassName"
        subselect="SQL expression"
        entity-name="EntityName">

        <property .... />
        .....
</union-subclass>

<join
        table="tablename"                        (1)
        schema="owner"                           (2)
        catalog="catalog"                        (3)
        fetch="join|select"                      (4)
        inverse="true|false"                     (5)
        optional="true|false">                   (6)
        
        <key ... />
        
        <property ... />
        ...
</join>

<class name="Person"
    table="PERSON">

    <id name="id" column="PERSON_ID">...</id>

    <join table="ADDRESS">
        <key column="ADDRESS_ID"/>
        <property name="address"/>
        <property name="zip"/>
        <property name="country"/>
    </join>
    ...

<key
        column="columnname"                      (1)
        on-delete="noaction|cascade"             (2)
        property-ref="propertyName"              (3)
        not-null="true|false"                    (4)
        update="true|false"                      (5)
        unique="true|false"                      (6)
/>

<column
        name="column_name"
        length="N"
        precision="N"
        scale="N"
        not-null="true|false"
        unique="true|false"
        unique-key="multicolumn_unique_key_name"
        index="index_name"
        sql-type="sql_type_name"
        check="SQL expression"/>

<formula>SQL expression</formula>

<many-to-one name="homeAddress" class="Address"
        insert="false" update="false">
    <column name="person_id" not-null="true" length="10"/>
    <formula>'MAILING'</formula>
</many-to-one>

<import class="java.lang.Object" rename="Universe"/>

<import
        class="ClassName"              (1)
        rename="ShortName"             (2)
/>

<any name="being" id-type="long" meta-type="string">
    <meta-value value="TBL_ANIMAL" class="Animal"/>
    <meta-value value="TBL_HUMAN" class="Human"/>
    <meta-value value="TBL_ALIEN" class="Alien"/>
    <column name="table_name"/>
    <column name="id"/>
</any>

<any
        name="propertyName"                      (1)
        id-type="idtypename"                     (2)
        meta-type="metatypename"                 (3)
        cascade="cascade_style"                  (4)
        access="field|property|ClassName"        (5)
        optimistic-lock="true|false"             (6)
>
        <meta-value ... />
        <meta-value ... />
        .....
        <column .... />
        <column .... />
        .....
</any>

당신은 매핑 문서 내에서 테이블 또는 컬럼 이름을 역인용기호(`)들 속에 넣어서 생성된 SQL에서 식별자를 인용부호 처리하도록 Hibernate에게 강제할 수도 있다. Hibernate는 SQL Dialect 에 대해 정확한 인용 스타일을 사용할 것이다(대개 이중 인용부호 이지만, SQL Server의 경우에는 모난 괄호들이고 MySQL의 경우에는 역인용부호(`)).

<class name="LineItem" table="`Line Item`">
    <id name="id" column="`Item Id`"/><generator class="assigned"/></id>
    <property name="itemNumber" column="`Item #`"/>
    ...
</class>

XML은 모든 사람들을 위한 것이 아니지만, Hibernate에서 O/R 매핑 메타데이터를 정의하는 몇몇 대안적인 방법들이 존재한다.

5.4.1. XDoclet 마크업 사용하기

많은 Hibernate 사용자들은 XDoclet @hibernate.tag들을 사용하여 소스 코드 속에 직접 매핑 정보를 삽입시키는 것을 선호한다.  우리는 이 문서에서 이 접근법을 다루지 않을 것이다. 왜냐하면 엄격하게 그것은 XDoclet의 부분으로 간주되기 때문이다. 하지만 우리는 XDoclet 매핑들을 가진 Cat 클래스에 관한 다음 예제를 포함한다.

package eg;
import java.util.Set;
import java.util.Date;

/**
 * @hibernate.class
 *  table="CATS"
 */
public class Cat {
    private Long id; // identifier
    private Date birthdate;
    private Cat mother;
    private Set kittens
    private Color color;
    private char sex;
    private float weight;

    /*
     * @hibernate.id
     *  generator-class="native"
     *  column="CAT_ID"
     */
    public Long getId() {
        return id;
    }
    private void setId(Long id) {
        this.id=id;
    }

    /**
     * @hibernate.many-to-one
     *  column="PARENT_ID"
     */
    public Cat getMother() {
        return mother;
    }
    void setMother(Cat mother) {
        this.mother = mother;
    }

    /**
     * @hibernate.property
     *  column="BIRTH_DATE"
     */
    public Date getBirthdate() {
        return birthdate;
    }
    void setBirthdate(Date date) {
        birthdate = date;
    }
    /**
     * @hibernate.property
     *  column="WEIGHT"
     */
    public float getWeight() {
        return weight;
    }
    void setWeight(float weight) {
        this.weight = weight;
    }

    /**
     * @hibernate.property
     *  column="COLOR"
     *  not-null="true"
     */
    public Color getColor() {
        return color;
    }
    void setColor(Color color) {
        this.color = color;
    }
    /**
     * @hibernate.set
     *  inverse="true"
     *  order-by="BIRTH_DATE"
     * @hibernate.collection-key
     *  column="PARENT_ID"
     * @hibernate.collection-one-to-many
     */
    public Set getKittens() {
        return kittens;
    }
    void setKittens(Set kittens) {
        this.kittens = kittens;
    }
    // addKitten not needed by Hibernate
    public void addKitten(Cat kitten) {
        kittens.add(kitten);
    }

    /**
     * @hibernate.property
     *  column="SEX"
     *  not-null="true"
     *  update="false"
     */
    public char getSex() {
        return sex;
    }
    void setSex(char sex) {
        this.sex=sex;
    }
}

XDoclet 와 Hibernate 에 관한 추가 예제들은 Hibernate 웹 사이트를 보라.

JDK 5.0은 언어 레벨에서 XDoclet-스타일의 주석들, type-safe와 컴파일 시 체킹을 도입했다. 이 메커니즘은 XDoclet 주석들 보다 더 강력하고 도구들과 IDE들에 의해 더 좋게 지원된다. 예를 들어 IntelliJ IDEA는 JDK 5.0 주석들에 대한 자동-완성 기능과 구문 강조를 지원한다. EJB 명세서의 새로운 개정판(JSR-220)은 엔티티 빈즈에 대한 프라이머리 메타데이터 메커니즘으로서 JDK 5.0 주석들을 사용한다. Hibernate3는 JSR-220의 EntityManager(영속 API)를 구현하고, 매핑 메타데이터에 대한 지원은 별도의 내려받기로서 Hibernate Annotations 패키지를 통해 이용 가능하다. EJB3 (JSR-220) 과 Hibernate3 metadata 양자가 지원된다.

다음은 EJB 엔티티 빈으로서 주석이 붙은 POJO 클래스에 관한 예제이다:

@Entity(access = AccessType.FIELD)
public class Customer implements Serializable {

    @Id;
    Long id;

    String firstName;
    String lastName;
    Date birthday;

    @Transient
    Integer age;

    @Dependent
    private Address homeAddress;

    @OneToMany(cascade=CascadeType.ALL,
               targetEntity="Order")
    @JoinColumn(name="CUSTOMER_ID")
    Set orders;

    // Getter/setter and business methods
}

JDK 5.0 주석들 (과 JSR-220)에 대한 지원은 여전히 작업이 진행 중이고 완성되지 않았음을 노트하라.

예를 들어 Hibernate는 영속 콜렉션-값을 가진 필드들이 인터페이스 타입으로서 선언되는 것을 필요로 한다:

public class Product {
    private String serialNumber;
    private Set parts = new HashSet();
    
    public Set getParts() { return parts; }
    void setParts(Set parts) { this.parts = parts; }
    public String getSerialNumber() { return serialNumber; }
    void setSerialNumber(String sn) { serialNumber = sn; }
}

실제 인터페이스는 java.util.Set, java.util.Collection, java.util.List, java.util.Map, java.util.SortedSet, java.util.SortedMap 또는 당신이 좋아하는 어떤 것일 수 있다!(여기서 "당신이 좋아하는 어떤 것"은 당신이 org.hibernate.usertype.UserCollectionType에 대한 구현을 작성해야 함을 의미한다.)

우리가 HashSet의 인스턴스를 가진 인스턴스 변수를 초기화 시켰던 방법을 주목하라. 이것은 새로이 초기화 된(비-영속) 인스턴스들을 가진 콜렉션 값 프로퍼티들을 초기화 시키는 최선의 방법이다. 당신이 -예를 들어 persist()를 호출하여- 인스턴스를 영속화 시킬 때 Hibernate는 실제로 HashSet을 Hibernate 자신의 Set 구현의 인스턴스로 대체시킬 것이다. 다음과 같은 오류들을 관찰하라:

Cat cat = new DomesticCat();
Cat kitten = new DomesticCat();
....
Set kittens = new HashSet();
kittens.add(kitten);
cat.setKittens(kittens);
session.persist(cat);
kittens = cat.getKittens(); // 좋다, kittens 콜렉션은 Set이다
(HashSet) cat.getKittens(); //오류!

Hibernate에 의해 도입된 영속 콜렉션들은 인터페이스 타입에 따라 HashMap, HashSet, TreeMap, TreeSet 또는 ArrayList과 같이 행위한다. 

콜렉션 인스턴스들은 value 타입들을 가진 통상의 특징을 갖는다. 그것들은 영속 객체에 의해 참조될 때 자동적으로 영속화 되고 참조 해제될 때 자동적으로 삭제된다. 만일 하나의 콜렉션이 하나의 영속 객체로부터 또 다른 영속 객체로 전달될 때, 그것의 요소들은 하나의 테이블로부터  다른 테이블로 이동될 수 있다. 두 개의 엔티티들은 동일한 콜렉션 인스턴스에 대한 참조를 공유하지 않는다. 기본 관계형 모형 때문에 콜렉션 값 프로퍼티들은 null 값 의미들을 지원하지 않는다; Hibernate는 null 콜렉션 참조와 공백의 콜렉션 사이를 구별 짓지 않는다.

당신은 이것의 어떤 것에 대해 너무 많이 걱정하지 않아도 될 것이다. 당신이 통상의 자바 콜렉션들을 사용하는 것과 동일한 방법으로 영속 콜렉션들을 사용하라. 단지 당신이 양방향 연관관계들에 대한 의미를 확실히 이해하도록 하라(나중에 논의됨).

콜렉션을 매핑하는데 사용되는 Hiberante 매핑 요소는 인터페이스의 타입에 의존한다. 예를 들어 <set> 요소는 Set 타입의 매핑 프로퍼티들에 사용된다.

<class name="Product">
    <id name="serialNumber" column="productSerialNumber"/>
    <set name="parts">
        <key column="productSerialNumber" not-null="true"/>
        <one-to-many class="Part"/>
    </set>
</class>

<set>과는 별도로, 또한 <list>, <map>, <bag>, <array>, <primitive-array> 매핑 요소들이 존재한다. <map> 요소가 대표적이다:

<map
    name="propertyName"                                         (1)
    table="table_name"                                          (2)
    schema="schema_name"                                        (3)
    lazy="true|false"                                           (4)
    inverse="true|false"                                        (5)
    cascade="all|none|save-update|delete|all-delete-orphan"     (6)
    sort="unsorted|natural|comparatorClass"                     (7)
    order-by="column_name asc|desc"                             (8)
    where="arbitrary sql where condition"                       (9)
    fetch="join|select|subselect"                               (10)
    batch-size="N"                                              (11)
    access="field|property|ClassName"                           (12)
    optimistic-lock="true|false"                                (13)
>

    <key .... />
    <map-key .... />
    <element .... />
</map>

<key column="productSerialNumber" not-null="true"/>

<key column="productSerialNumber" on-delete="cascade"/>

<list-index 
        column="column_name"                (1)
        base="0|1|..."/>

<map-key 
        column="column_name"                (1)
        formula="any SQL expression"        (2)
        type="type_name"                    (3)
        length="N"/>

<map-key-many-to-many
        column="column_name"                (1)
        formula="any SQL expression"        (2)
        class="ClassName"                   (3)
/>

많은 공통된 관계형 모형들을 다루는, 콜렉션들에 대해 생성될 수 있는 매핑들의 영역이 꽤 존재한다. 여러가지 매핑 선언들이 데이터베이스 테이블들로 변환되는 방법을 당신이 느끼려면 스키마 생성으로 실험하기를 우리는 제안한다.

<element
        column="column_name"                (1)
        formula="any SQL expression"        (2)
        type="typename"                     (3)
        length="N"
        precision="N"
        scale="N"
        not-null="true|false"
        unique="true|false"
/>

<many-to-many
        column="column_name"                               (1)
        formula="any SQL expression"                       (2)
        class="ClassName"                                  (3)
        fetch="select|join"                                (4)
        unique="true|false"                                (5)
        not-found="ignore|exception"                       (6)
        entity-name="EntityName"
    />

<set name="names" table="person_names">
    <key column="person_id"/>
    <element column="person_name" type="string"/>
</set>

<bag name="sizes" 
        table="item_sizes" 
        order-by="size asc">
    <key column="item_id"/>
    <element column="size" type="integer"/>
</bag>

<array name="addresses" 
        table="PersonAddress" 
        cascade="create">
    <key column="personId"/>
    <list-index column="sortOrder"/>
    <many-to-many column="addressId" class="Address"/>
</array>

<map name="holidays" 
        table="holidays" 
        schema="dbo" 
        order-by="hol_name asc">
    <key column="id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date" type="date"/>
</map>

<list name="carComponents" 
        table="CarComponents">
    <key column="carId"/>
    <list-index column="sortOrder"/>
    <composite-element class="CarComponent">
        <property name="price"/>
        <property name="type"/>
        <property name="serialNumber" column="serialNum"/>
    </composite-element>
</list>

<one-to-many 
        class="ClassName"                                  (1)
        not-found="ignore|exception"                       (2)
        entity-name="EntityName"/>

<map name="parts"
        cascade="all">
    <key column="productId" not-null="true"/>
    <map-key formula="partName"/>
    <one-to-many class="Part"/>
</map>

컴포넌트는 엔티티 참조가 아닌, value 타입으로서 영속화 되는 포함된 객체이다. "컴포넌트" 용어는 (아키텍처 수준의 컴포넌트들이 아닌) composition(구성, 조립,합성)에 대한 객체-지향적인 개념을 언급한다. 예를 들어 당신은 다음과 같이 개인을 모형화 시킬 수도 있다:

public class Person {
    private java.util.Date birthday;
    private Name name;
    private String key;
    public String getKey() {
        return key;
    }
    private void setKey(String key) {
        this.key=key;
    }
    public java.util.Date getBirthday() {
        return birthday;
    }
    public void setBirthday(java.util.Date birthday) {
        this.birthday = birthday;
    }
    public Name getName() {
        return name;
    }
    public void setName(Name name) {
        this.name = name;
    }
    ......
    ......
}

public class Name {
    char initial;
    String first;
    String last;
    public String getFirst() {
        return first;
    }
    void setFirst(String first) {
        this.first = first;
    }
    public String getLast() {
        return last;
    }
    void setLast(String last) {
        this.last = last;
    }
    public char getInitial() {
        return initial;
    }
    void setInitial(char initial) {
        this.initial = initial;
    }
}

이제 Name은 Person의 컴포넌트로서 영속화 될 수도 있다. Name 이 그것의 영속 프로퍼티들에 대한 getter 메소드와 setter 메소드를 정의하지만, 어떤 인터페이스들이나 identifier 프로퍼티들을 선언하는 것을 필요로 하지 않음을 주목하라. 

우리의 Hibernate 매핑은 다음과 같을 것이다:

<class name="eg.Person" table="person">
    <id name="Key" column="pid" type="string">
        <generator class="uuid.hex"/>
    </id>
    <property name="birthday" type="date"/>
    <component name="Name" class="eg.Name"> <!-- class attribute optional -->
        <property name="initial"/>
        <property name="first"/>
        <property name="last"/>
    </component>
</class>

person 테이블은 pid, birthday, initial, first, last 컬럼들을 가질 것이다.

모든 value 타입들처럼, 컴포넌트들은 공유된 참조들을 지원하지 않는다. 달리 말해, 두 명의 개인들은 동일한 이름을 가질 수 있지만, 두 개의 person 객체들은 오직 값 만이 "동일한", 두 개의 독립적인 name 객체들을 포함할 것이다. 컴포넌트의 null 값 의미는 특별한 용도를 위한 것이다. 포함된 객체를 다시 로드시킬 때, Hibernate는 모든 컴포넌트 컬럼들이 null일 경우에 전체 컴포넌트가 null이라고 가정할 것이다. 이것은 대부분의 용도로는 맞을 것이다.

컴포넌트의 프로퍼티들은 임의의 Hibernate 타입일 수 있다(콜렉션들, many-to-one 연관들, 다른 컴포넌트들, 기타). 내포된 컴포넌트들은 신종의 사용례로 간주되지 않을 것이다. Hibernate는 매우 잘 정제된 객체 모형을 지원하도록 고안되어있다.

<component> 요소는 컴포넌트 클래스의 프로퍼티는 포함되는 엔티티에 대한 참조로서 매핑시키는 <parent> 서브요소를 허용한다. 

<class name="eg.Person" table="person">
    <id name="Key" column="pid" type="string">
        <generator class="uuid.hex"/>
    </id>
    <property name="birthday" type="date"/>
    <component name="Name" class="eg.Name" unique="true">
        <parent name="namedPerson"/> <!-- reference back to the Person -->
        <property name="initial"/>
        <property name="first"/>
        <property name="last"/>
    </component>
</class>

컴포넌트들을 가진 콜렉션들이 지원된다(예를 들면 Name 타입을 가진 배열). <element> 태그를 <composite-element> 태그로 바꾸어서 당신의 컴포넌트 콜렉션을 선언하라.

<set name="someNames" table="some_names" lazy="true">
    <key column="id"/>
    <composite-element class="eg.Name"> <!-- class attribute required -->
        <property name="initial"/>
        <property name="first"/>
        <property name="last"/>
    </composite-element>
</set>

노트: 만일 당신이 composite 요소를 가진 Set를 정의할 경우, equals()와 hashCode()를 정확하게 구현하는 것이 매우 중요하다.

Composite 요소들은 컴포넌트들을 포함하지만 콜렉션들을 포함하지 않는다. 만일 당신의 composite 요소 자체가 컴포넌트들을 포함할 경우, <nested-composite-element> 태그를 사용하라. 이것은 꽤 신종의 경우-자체로 컴포넌트들을 갖고 있는 컴포넌트들을 가진 콜렉션-이다. 이 방도로 당신은 one-to-many 연관이 더 적절한지를 당신 스스로에게 질문하게 될 것이다. composite 요소를 다시 모델링하려고 시도하라 - 그러나 자바 모형들이 동일할지라도, 관계형 모형과 영속화 의미들은 여전히 약간 다르다.

당신이 <set>를 사용할 경우, composite 요소 매핑은 null 가능한 프로퍼티들을 지원하지 않음을 노트하길 바란다. Hibernate는 객체들을 삭제할 때 레코드를 식별하기 위해 각각의 컬럼들 값을 사용해야 하며, (composite 요소 테이블 내에 별도의 프라이머리 키 컬럼이 존재하지 않는다), 그것은 null 값들을 갖는 것이 불가능하다.  당신은 composite-요소 내에 오직 not-null 프로퍼티들을 해야 하거나 <list>, <map>, <bag> 또는 <idbag>을 선택해야 한다.

composite 요소의 특별하나 경우는 내포된 <many-to-one> 요소를 가진 composite 요소이다. 이같은 매핑은 many-to-many 연관 테이블의 특별한 컬럼들을 composite 요소 클래스로 매핑시키는 것을 당신에게 허용해준다. 다음은 Order로부터 Item으로의 many-to-many 연관이다. 여기서 purchaseDate, price, quantity 는 연관의 프로퍼티들이다:

<class name="eg.Order" .... >
    ....
    <set name="purchasedItems" table="purchase_items" lazy="true">
        <key column="order_id">
        <composite-element class="eg.Purchase">
            <property name="purchaseDate"/>
            <property name="price"/>
            <property name="quantity"/>
            <many-to-one name="item" class="eg.Item"/> <!-- class 속성은 옵션이다 -->
        </composite-element>
    </set>
</class>

물론, 양방향 연관 네비게이션의 경우, 다른 측 상에 있는 purchase에 대한 참조가 참조가 존재할 수 없다. 컴포넌트들이 value 타입들이고 공유된 참조들을 허용하지 않음을 기억하라. 하나의 Purchase는 Order를 가진 set 내에 있을 수 있지만, 그것은 동시에 Item에 의해 참조될 수 없다.

심지어 세겹의(또는 네 겹의, 기타) 연관들이 가능하다:

<class name="eg.Order" .... >
    ....
    <set name="purchasedItems" table="purchase_items" lazy="true">
        <key column="order_id">
        <composite-element class="eg.OrderLine">
            <many-to-one name="purchaseDetails class="eg.Purchase"/>
            <many-to-one name="item" class="eg.Item"/>
        </composite-element>
    </set>
</class>

composite 요소들은 다른 엔티티들에 대한 연관들과 동일한 구문을 사용하여 질의들 내에 나타날 수도 있다.

<composite-map-key> 요소는 당신이 컴포넌트 클래스를 Map의 키로서 매핑시키도록 한다. 당신은 컴포넌트 클래스 상에서 hashCode()와 equals()를 정확하게 오버라이드 시키도록 하라.

당신은 컴포넌트를 엔티티 클래스의 식별자로서 사용할 수도 있다. 당신의 컴포넌트 클래스는 어떤 사양들을 충족해야 한다:

노트: Hibernate3에서, 두 번째 사양은 Hibernate의 절대적으로 엄격한 사양이 아니다. 그러나 아무튼 그것을 행하라.

당신은 compsite 키들을 생성시키는데 IdentifierGenerator를 사용할 수 없다. 대신에 어플리케이션은 그것 자신의 식별자들을 할당해야 한다. 

통상의 <id> 선언 위치에 (내포된 <key-property> 요소들을 가진) <composite-id> 태그를 사용하라. 예를 들어, OrderLine 클래스는 Order의 (composite) 프라이머리 키에 의존하는 프라이머리 키를 갖는다.

<class name="OrderLine">
    
    <composite-id name="id" class="OrderLineId">
        <key-property name="lineId"/>
        <key-property name="orderId"/>
        <key-property name="customerId"/>
    </composite-id>
    
    <property name="name"/>
    
    <many-to-one name="order" class="Order"
            insert="false" update="false">
        <column name="orderId"/>
        <column name="customerId"/>
    </many-to-one>
    ....
    
</class>

이제 OrderLine 테이블을 참조하는 임의의 foreign 키들이 또한 compsite이다. 당신은 다른 클래스들에 대한 당신의 매핑 속에 이것을 선언해야 한다. OrderLine 에 대한 연관은 다음과 같이 매핑될 것이다:

<many-to-one name="orderLine" class="OrderLine">
<!-- the "class" attribute is optional, as usual -->
    <column name="lineId"/>
    <column name="orderId"/>
    <column name="customerId"/>
</many-to-one>

(<column> 태그가 모든 곳에서 column 속성에 대한 대안임을 노트하라.)

OrderLine에 대한 many-to-many 연관은 또한 composite foreign 키를 사용한다: 

<set name="undeliveredOrderLines">
    <key column name="warehouseId"/>
    <many-to-many class="OrderLine">
        <column name="lineId"/>
        <column name="orderId"/>
        <column name="customerId"/>
    </many-to-many>
</set>

Order 에서 OrderLine들의 콜렉션이 사용될 것이다: 

<set name="orderLines" inverse="true">
    <key>
        <column name="orderId"/>
        <column name="customerId"/>
    </key>
    <one-to-many class="OrderLine"/>
</set>

(<one-to-many> 요소는 통상적으로 컬럼들을 선언하지 않는다.)

만일 OrderLine 자체가 하나의 콜렉션을 소유할 경우, 그것은 또한 하나의 composite foreign 키를 갖는다.

<class name="OrderLine">
    ....
    ....
    <list name="deliveryAttempts">
        <key>   <!-- 콜렉션은 composite 키 타입을 상속받는다 -->
            <column name="lineId"/>
            <column name="orderId"/>
            <column name="customerId"/>
        </key>
        <list-index column="attemptId" base="1"/>
        <composite-element class="DeliveryAttempt">
            ...
        </composite-element>
    </set>
</class>

당신은 Map 타입의 프로퍼티를 매핑시킬 수도 있다:

<dynamic-component name="userAttributes">
    <property name="foo" column="FOO"/>
    <property name="bar" column="BAR"/>
    <many-to-one name="baz" class="Baz" column="BAZ_ID"/>
</dynamic-component>

<dynamic-component> 매핑의 의미는 <component>와 동일하다. 이런 종류의 매핑의 장점은 배치 시에 매핑 문서를 편집함으로써 그 bean의 실제 프로퍼티들을 결정하는 가용성이다. 매핑 문서에 대한 런타임 처리는 또한 DOM 파서를 사용하여 가능하다.  더 좋게는 당신이 Configuration  객체를 통해 Hibernate의 구성-시 메타모형에 액세스할 수 있다(그리고 그것을 변경시킬 수 있다)

Hibernate는 세 개의 기본적인 상속 매핑 방도들을 지원한다:

게다가 Hibernate는 네 번째의 약간 다른 종류의 다형성을 지원한다:

implicit polymorphism(함축적인 다형성)

동일한 상속 계층구조의 다른 가지들에 대해 다른 매핑 방도들을 사용하는 것이 가능하고, 전체 계층 구조를 가로질러 다형성을 성취하는데 함축적인 다형성을 사용하라. 하지만 Hibernate는 동일한 루트 <class> 요소 하에서 <subclass>, 그리고 <joined-subclass> 그리고 <union-subclass> 매핑들을 혼합하는 것을 지원하지 않는다. 동일한 <class> 요소 하에서 <subclass> 요소와 <join> 요소를 결합시킴으로써 table per hierarchy 방도와 table per subclass 방도를 함께 혼합시키는 것이 가능하다(아래를 보라).

우리가 CreditCardPayment, CashPayment, ChequePayment 구현자들을 가진 인터페이스 Payment를 갖고 있다고 가정하자. table per hierarchy 매핑은 다음과 같을 것이다: 

<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="PAYMENT_TYPE" type="string"/>
    <property name="amount" column="AMOUNT"/>
    ...
    <subclass name="CreditCardPayment" discriminator-value="CREDIT">
        <property name="creditCardType" column="CCTYPE"/>
        ...
    </subclass>
    <subclass name="CashPayment" discriminator-value="CASH">
        ...
    </subclass>
    <subclass name="ChequePayment" discriminator-value="CHEQUE">
        ...
    </subclass>
</class>

정확히 하나의 테이블이 필요하다. 이 매핑 방도에는 다음의 하나의 큰 제약이 존재한다: CCTYPE과 같이 서브 클래스들에 의해 선언된 컬럼들은 NOT NULL 컨스트레인트들을 가질 수 없다.

table per subclass 매핑은 다음과 같을 것이다:

<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="AMOUNT"/>
    ...
    <joined-subclass name="CreditCardPayment" table="CREDIT_PAYMENT">
        <key column="PAYMENT_ID"/>
        <property name="creditCardType" column="CCTYPE"/>
        ...
    </joined-subclass>
    <joined-subclass name="CashPayment" table="CASH_PAYMENT">
        <key column="PAYMENT_ID"/>
        ...
    </joined-subclass>
    <joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT">
        <key column="PAYMENT_ID"/>
        ...
    </joined-subclass>
</class>

네 개의 테이블들이 필요하다. 세 개의 서브클래스 테이블들은 슈퍼클래스 테이블에 대한 프라이머리 키 연관들을 갖는다(따라서 그 관계형 모형은 실제로 one-to-one 연관이다).

 table-per-subclass에 대한 Hibernate의 구현은 discriminator(판별자) 컬럼을 필요로 하지 않음을 노트하라.  다른 객체/관계형 매핑기들은 슈퍼클래스 테이블 속에 타입 discriminator 컬럼을 필요로 하는 table-per-subclass에 대한 다른 구현을 사용한다. Hibernate에 채택된 접근법은 구현하기가 훨씬 더 어렵지만 관계형 관점에서는 아마 틀림없이 보다 더 정확하다. 만일 당신이 table per subclass 방도를 대해 discriminator 컬럼을 사용하고 싶다면, 당신은 다음과 같이 <subclass>와 <join>의 사용을 결합시킬 수도 있다:

<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="PAYMENT_TYPE" type="string"/>
    <property name="amount" column="AMOUNT"/>
    ...
    <subclass name="CreditCardPayment" discriminator-value="CREDIT">
        <join table="CREDIT_PAYMENT">
            <property name="creditCardType" column="CCTYPE"/>
            ...
        </join>
    </subclass>
    <subclass name="CashPayment" discriminator-value="CASH">
        <join table="CASH_PAYMENT">
            ...
        </join>
    </subclass>
    <subclass name="ChequePayment" discriminator-value="CHEQUE">
        <join table="CHEQUE_PAYMENT" fetch="select">
            ...
        </join>
    </subclass>
</class>

선택적인 fetch="select" 선언은 슈퍼클래스를 질의할 때 outer join을 사용하여 ChequePayment 서브클래스 데이터를 페치시키지 않도록 Hibernate에게 알려준다.

당신은 다음 접근법을 사용하여 table per hierarchy 방도와 table per subclass 방도를 혼합시킬 수 있다:

<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="PAYMENT_TYPE" type="string"/>
    <property name="amount" column="AMOUNT"/>
    ...
    <subclass name="CreditCardPayment" discriminator-value="CREDIT">
        <join table="CREDIT_PAYMENT">
            <property name="creditCardType" column="CCTYPE"/>
            ...
        </join>
    </subclass>
    <subclass name="CashPayment" discriminator-value="CASH">
        ...
    </subclass>
    <subclass name="ChequePayment" discriminator-value="CHEQUE">
        ...
    </subclass>
</class>

이들 매핑 방도들 중 어떤 것에 대해, 루트 Payment 클래스에 대한 다형성 연관은 <many-to-one>을 사용하여 매핑된다.

<many-to-one name="payment" column="PAYMENT_ID" class="Payment"/>

우리가 table per concrete class 방도 매핑에 대해 취할 수 있는 두 가지 방법들이 존재한다. 첫 번째는 <union-subclass>를 사용하는 것이다.

<class name="Payment">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="AMOUNT"/>
    ...
    <union-subclass name="CreditCardPayment" table="CREDIT_PAYMENT">
        <property name="creditCardType" column="CCTYPE"/>
        ...
    </union-subclass>
    <union-subclass name="CashPayment" table="CASH_PAYMENT">
        ...
    </union-subclass>
    <union-subclass name="ChequePayment" table="CHEQUE_PAYMENT">
        ...
    </union-subclass>
</class>

세 개의 테이블들이 수반된다. 각각의 테이블은 상속된 프로퍼티들을 포함하여 그 클래스의 모든 프로퍼티들에 대한 컬럼들을 정의한다.

이 접근법의 제약은 만일 하나의 프로퍼티가 슈퍼클래스 상으로 매핑될 경우, 그 컬럼 이름은 모든 서브클래스 테이블들 상에서 같아야 한다는 점이다.(우리는 장래의 Hibernate 배포본에서 이 제약을 풀 수도 있다. )

<class name="CreditCardPayment" table="CREDIT_PAYMENT">
    <id name="id" type="long" column="CREDIT_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="CREDIT_AMOUNT"/>
    ...
</class>

<class name="CashPayment" table="CASH_PAYMENT">
    <id name="id" type="long" column="CASH_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="CASH_AMOUNT"/>
    ...
</class>

<class name="ChequePayment" table="CHEQUE_PAYMENT">
    <id name="id" type="long" column="CHEQUE_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="CHEQUE_AMOUNT"/>
    ...
</class>

<any name="payment" meta-type="string" id-type="long">
    <meta-value value="CREDIT" class="CreditCardPayment"/>
    <meta-value value="CASH" class="CashPayment"/>
    <meta-value value="CHEQUE" class="ChequePayment"/>
    <column name="PAYMENT_CLASS"/>
    <column name="PAYMENT_ID"/>
</any>

<class name="CreditCardPayment" table="CREDIT_PAYMENT">
    <id name="id" type="long" column="CREDIT_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="CREDIT_CARD" type="string"/>
    <property name="amount" column="CREDIT_AMOUNT"/>
    ...
    <subclass name="MasterCardPayment" discriminator-value="MDC"/>
    <subclass name="VisaPayment" discriminator-value="VISA"/>
</class>

<class name="NonelectronicTransaction" table="NONELECTRONIC_TXN">
    <id name="id" type="long" column="TXN_ID">
        <generator class="native"/>
    </id>
    ...
    <joined-subclass name="CashPayment" table="CASH_PAYMENT">
        <key column="PAYMENT_ID"/>
        <property name="amount" column="CASH_AMOUNT"/>
        ...
    </joined-subclass>
    <joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT">
        <key column="PAYMENT_ID"/>
        <property name="amount" column="CHEQUE_AMOUNT"/>
        ...
    </joined-subclass>
</class>

table per concrete-class 매핑 방도에 대한 "함축적인 다형성" 접근법에는 어떤 제약들이 존재한다. <union-subclass> 매핑들에 대해서는 다소 덜 제약적인 제약들이 존재한다:

다음 표는 Hibernate에서 table per concrete-class 매핑들에 대한 제약들, 그리고 함축적인 다형성에 대한 제약들을 보여준다.