Hibernate.orgCommunity Documentation

HIBERNATE - Persistencia relacional para Java idiomático

Documentación de referencia de Hibernate

3.5.6-Final

Advertencia legal

September 15, 2010


Prefacio
1. Tutorial
1.1. Parte 1 - La primera aplicación Hibernate
1.1.1. Configuración
1.1.2. La primera clase
1.1.3. El archivo de mapeo
1.1.4. Configuración de Hibernate
1.1.5. Construcción con Maven
1.1.6. Inicio y ayudantes
1.1.7. Carga y almacenamiento de objetos
1.2. Part 2 - Mapeo de asociaciones
1.2.1. Mapeo de la clase Person
1.2.2. Una asociación unidireccional basada en Set
1.2.3. Trabajo de la asociación
1.2.4. Colección de valores
1.2.5. Asociaciones bidireccionales
1.2.6. Trabajo con enlaces bidireccionales
1.3. Part 3 - La aplicación web EventManager
1.3.1. Escritura de un servlet básico
1.3.2. Procesamiento y entrega
1.3.3. Despliegue y prueba
1.4. Resumen
2. Arquitectura
2.1. Sinopsis
2.2. Estados de instancia
2.3. Integración JMX
2.4. Soporte JCA
2.5. Sesiones contextuales
3. Configuración
3.1. Configuración programática
3.2. Obtención de una SessionFactory
3.3. Conexiones JDBC
3.4. Parámetros de configuración opcionales
3.4.1. Dialectos de SQL
3.4.2. Recuperación por Unión Externa - Outer Join Fetching
3.4.3. Flujos Binarios
3.4.4. Caché de segundo nivel y de lectura
3.4.5. Sustitución de Lenguaje de Consulta
3.4.6. Estadísticas de Hibernate
3.5. Registros de mensajes (Logging)
3.6. Implementación de una NamingStrategy
3.7. Archivo de configuración XML
3.8. Integración con Servidores de Aplicaciones J2EE
3.8.1. Configuración de la estrategia de transacción
3.8.2. SessionFactory enlazado a JNDI
3.8.3. Administración de contexto de Sesión Actual con JTA
3.8.4. Despliegue JMX
4. Clases persistentes
4.1. Ejemplo simple de POJO
4.1.1. Implemente un constructor sin argumentos
4.1.2. Proporcione una propiedad identificadora (opcional)
4.1.3. Prefiera las clases no finales (opcional)
4.1.4. Declare métodos de acceso y de modificación para los campos persistentes (opcional)
4.2. Implementación de herencia
4.3. Implementando equals() y hashCode()
4.4. Modelos dinámicos
4.5. Tuplizers
4.6. EntityNameResolvers
5. Mapeo O/R Básico
5.1. Declaración de mapeo
5.1.1. Doctype
5.1.2. Mapeo de Hibernate
5.1.3. Clase
5.1.4. id
5.1.5. Generadores mejorados del identificador
5.1.6. Optimización del generador del identificador
5.1.7. composite-id
5.1.8. Discriminador
5.1.9. Versión (opcional)
5.1.10. Timestamp (opcional)
5.1.11. Propiedad
5.1.12. Many-to-one
5.1.13. One-to-one
5.1.14. Natural-id
5.1.15. Componente y componente dinámico
5.1.16. Propiedades
5.1.17. Subclase
5.1.18. joined-subclass
5.1.19. Union-subclass
5.1.20. Join
5.1.21. Key
5.1.22. Los elementos columna y fórmula
5.1.23. Import
5.1.24. Any
5.2. Tipos de Hibernate
5.2.1. Entidades y Valores
5.2.2. Tipos de valores básicos
5.2.3. Tipos de valor personalizados
5.3. Mapeo de una clase más de una vez
5.4. Identificadores SQL en comillas
5.5. Alternativas de metadatos
5.5.1. Utilización de marcado de XDoclet
5.5.2. Utlización de Anotaciones JDK 5.0
5.6. Propiedades generadas
5.7. Expresiones de lectura y escritura de columnas
5.8. Objetos de bases de datos auxiliares
6. Mapeos de colección
6.1. Colecciones persistentes
6.2. Mapeos de colección
6.2.1. Claves foráneas de colección
6.2.2. Elementos de collección
6.2.3. Colecciones indexadas
6.2.4. Colecciones de valores y asociaciones muchos-a-muchos
6.2.5. Asociaciones uno-a-muchos
6.3. Mapeos de colección avanzados
6.3.1. Colecciones ordenadas
6.3.2. Asociaciones bidireccionales
6.3.3. Asociaciones bidireccionales con colecciones indexadas
6.3.4. Asociaciones ternarias
6.3.5. Using an <idbag>
6.4. Ejemplos de colección
7. Mapeos de asociación
7.1. Introducción
7.2. Asociaciones Unidireccionales
7.2.1. Many-to-one
7.2.2. Uno-a-uno
7.2.3. Uno-a-muchos
7.3. Asociaciones unidireccionales con tablas de unión
7.3.1. Uno-a-muchos
7.3.2. Many-to-one
7.3.3. Uno-a-uno
7.3.4. Muchos-a-muchos
7.4. Asociaciones bidireccionales
7.4.1. uno-a-muchos / muchos-a-uno
7.4.2. Uno-a-uno
7.5. Asociaciones bidireccionales con tablas de unión
7.5.1. uno-a-muchos / muchos-a-uno
7.5.2. uno a uno
7.5.3. Muchos-a-muchos
7.6. Mapeos de asociación más complejos
8. Mapeo de componentes
8.1. Objetos dependientes
8.2. Colecciones de objetos dependientes
8.3. Componentes como índices de Mapeo
8.4. Componentes como identificadores compuestos
8.5. Componentes dinámicos
9. Mapeo de herencias
9.1. Las tres estrategias
9.1.1. Tabla por jerarquía de clases
9.1.2. Tabla por subclase
9.1.3. Tabla por subclase: utilizando un discriminador
9.1.4. Mezcla de tabla por jerarquía de clases con tabla por subclase
9.1.5. Tabla por clase concreta
9.1.6. Tabla por clase concreta utilizando polimorfismo implícito
9.1.7. Mezcla de polimorfismo implícito con otros mapeos de herencia
9.2. Limitaciones
10. Trabajo con objetos
10.1. Estados de objeto de Hibernate
10.2. Haciendo los objetos persistentes
10.3. Cargando un objeto
10.4. Consultas
10.4.1. Ejecución de consultas
10.4.2. Filtración de colecciones
10.4.3. Consultas de criterios
10.4.4. Consultas en SQL nativo
10.5. Modificación de objetos persistentes
10.6. Modificación de objetos separados
10.7. Detección automática de estado
10.8. Borrado de objetos persistentes
10.9. Replicación de objetos entre dos almacenamientos de datos diferentes
10.10. Limpieza (flushing) de la sesión
10.11. Persistencia transitiva
10.12. Utilización de metadatos
11. Read-only entities
11.1. Making persistent entities read-only
11.1.1. Entities of immutable classes
11.1.2. Loading persistent entities as read-only
11.1.3. Loading read-only entities from an HQL query/criteria
11.1.4. Making a persistent entity read-only
11.2. Read-only affect on property type
11.2.1. Simple properties
11.2.2. Unidirectional associations
11.2.3. Bidirectional associations
12. Transacciones y concurrencia
12.1. Ámbitos de sesión y de transacción
12.1.1. Unidad de trabajo
12.1.2. Conversaciones largas
12.1.3. Consideración de la identidad del objeto
12.1.4. Temas comúnes
12.2. Demarcación de la transacción de la base de datos
12.2.1. Entorno no administrado
12.2.2. Utilización de JTA
12.2.3. Manejo de excepciones
12.2.4. Tiempo de espera de la transacción
12.3. Control de concurrencia optimista
12.3.1. Chequeo de versiones de la aplicación
12.3.2. Sesión extendida y versionado automático
12.3.3. Objetos separados y versionado automático
12.3.4. Personalización del versionado automático
12.4. Bloqueo pesimista
12.5. Modos de liberación de la conexión
13. Interceptores y eventos
13.1. Interceptores
13.2. Sistema de eventos
13.3. Seguridad declarativa de Hibernate
14. Procesamiento por lotes
14.1. Inserciones de lotes
14.2. Actualizaciones de lotes
14.3. La interfaz de Sesión sin Estado
14.4. Operaciones de estilo DML
15. HQL: El lenguaje de consulta de Hibernate
15.1. Sensibilidad a mayúsculas
15.2. La cláusula from
15.3. Asociaciones y uniones (joins)
15.4. Formas de sintaxis unida
15.5. Referencia a la propiedad identificadora
15.6. La cláusula select
15.7. Funciones de agregación
15.8. Consultas polimórficas
15.9. La cláusula where
15.10. Expresiones
15.11. La cláusula order by
15.12. La cláusula group by
15.13. Subconsultas
15.14. Ejemplos de HQL
15.15. Declaraciones UPDATE y DELETE masivas
15.16. Consejos y Trucos
15.17. Componentes
15.18. Sintaxis del constructor de valores por fila
16. Consultas por criterios
16.1. Creación de una instancia Criteria
16.2. Límitando el conjunto de resultados
16.3. Orden de los resultados
16.4. Asociaciones
16.5. Recuperación dinámica de asociaciones
16.6. Consultas ejemplo
16.7. Proyecciones, agregación y agrupamiento
16.8. Consultas y subconsultas separadas
16.9. Consultas por identificador natural
17. SQL Nativo
17.1. Uso de una SQLQuery
17.1.1. Consultas escalares
17.1.2. Consultas de entidades
17.1.3. Manejo de asociaciones y colecciones
17.1.4. Devolución de entidades múltiples
17.1.5. Devolución de entidades no-administradas
17.1.6. Manejo de herencias
17.1.7. Parámetros
17.2. Consultas SQL nombradas
17.2.1. Utilización de la propiedad return para especificar explícitamente los nombres de columnas/alias
17.2.2. Utilización de procedimientos para consultas
17.3. Personalice SQL para crear, actualizar y borrar
17.4. Personalice SQL para cargar
18. Filtración de datos
18.1. Filtros de Hibernate
19. Mapeo XML
19.1. Trabajo con datos XML
19.1.1. Especificación de los mapeos de XML y de clase en conjunto
19.1.2. Especificación de sólo un mapeo XML
19.2. Mapeo de metadatos XML
19.3. Manipulación de datos XML
20. Mejoramiento del rendimiento
20.1. Estrategias de recuperación
20.1.1. Trabajo con asociaciones perezosas
20.1.2. Afinación de las estrategias de recuperación
20.1.3. Proxies de asociaciones de un sólo extremo
20.1.4. Inicialización de colecciones y proxies
20.1.5. Utilización de recuperación de lotes
20.1.6. Utilización de la recuperación por subselección
20.1.7. Perfiles de recuperación
20.1.8. Utilización de la recuperación perezosa de propiedades
20.2. El Caché de Segundo Nivel
20.2.1. Mapeos de caché
20.2.2. Estrategia: sólo lectura
20.2.3. Estrategia: lectura/escritura (read/write)
20.2.4. Estrategia: lectura/escritura no estricta
20.2.5. Estrategia: transaccional
20.2.6. Compatibilidad de proveedor de caché/estrategia de concurrencia
20.3. Gestión de cachés
20.4. El Caché de Consultas
20.4.1. Habilitación del caché de peticiones
20.4.2. Regiones de caché de consultas
20.5. Comprensión del rendimiento de Colecciones
20.5.1. Taxonomía
20.5.2. Las listas, mapas, idbags y conjuntos son las colecciones más eficientes de actualizar
20.5.3. Los Bags y las listas son las colecciones inversas más eficientes
20.5.4. Borrado de un sólo tiro
20.6. Control del rendimiento
20.6.1. Control de una SessionFactory
20.6.2. Métricas
21. Manual del conjunto de herramientas
21.1. Generación automática de esquemas
21.1.1. Personalización del esquema
21.1.2. Ejecución de la herramienta
21.1.3. Propiedades
21.1.4. Utilización de Ant
21.1.5. Actualizaciones incrementales de esquema
21.1.6. Utilización de Ant para actualizaciones incrementales de esquema
21.1.7. Validación de Esquema
21.1.8. Utilización de Ant para la validación de esquema
22. Ejemplo: Padre/Hijo
22.1. Nota sobre las colecciones
22.2. Uno-a-muchos bidireccional
22.3. Ciclo de vida en cascada
22.4. Cascadas y unsaved-value
22.5. Conclusión
23. Ejemplo: Aplicación de Weblog
23.1. Clases Persistentes
23.2. Mapeos de Hibernate
23.3. Código Hibernate
24. Ejemplo: mapeos varios
24.1. Empleador/Empleado
24.2. Autor/Obra
24.3. Cliente/Orden/Producto
24.4. Mapeos varios de ejemplo
24.4.1. Asociación uno-a-uno "Tipificada"
24.4.2. Ejemplo de clave compuesta
24.4.3. Muchos-a-muchos con atributo compartido de clave compuesta
24.4.4. Discriminación basada en contenido
24.4.5. Asociaciones sobre claves alternativas
25. Prácticas recomendadas
26. Consideraciones de la portabilidad de la base de datos
26.1. Aspectos básicos de la portabilidad
26.2. Dialecto
26.3. Resolución del dialecto
26.4. Generación del identificador
26.5. Funciones de la base de datos
26.6. Mapeos de tipo
Referencias

El trabajar con software orientado a objetos y con una base de datos relacional puede llegar a ser engorroso y puede llegar a tomar bastante tiempo en los entornos empresariales de hoy en día. Hibernate es una herramienta de mapeo objeto/relacional para entornos Java. El término de mapeo objeto/relacional (ORM) se refiere a la técnica de mapear una representación de datos desde un modelo de objeto a un modelo de datos relacionales con un esquema basado en SQL.

Hibernate no sólamente se ocupa del mapeo desde las clases Java a las tablas de las bases de datos (y desde los tipos de datos de Java a los tipos de datos de SQL), sino que también facilita la consulta y recuperación de datos. Esto puede reducir de manera importante el tiempo de desarrollo que se tomaría con el manejo de datos de forma manual en SQL y JDBC.

La meta de Hibernate es aliviar el trabajo del desarrollador en 95% de la persistencia de datos comunes relacionados con tareas de programación. Es posible que Hibernate no sea la mejor solución para aquellas aplicaciones centralizadas en datos que sólamente utilizan los procedimientos almacenados para implementar la lógica empresarial en la base de datos, Hibernate es mucho más útil con modelos de dominio orientados a objetos y con lógica empresarial middle-tier con base en Java. Sin embargo, Hibernate ciertamente le puede ayudar a eliminar o a encapsular código SQL específico del vendedor y le ayudará con la tarea común de traducción del grupo de resultados desde una representación tabular a un grafo de objetos.

Si usted es nuevo en el tema de Hibernate y del Mapeo Objeto/Relacional o inclusive en Java por favor siga los siguientes pasos:

  1. Read Capítulo 1, Tutorial for a tutorial with step-by-step instructions. The source code for the tutorial is included in the distribution in the doc/reference/tutorial/ directory.

  2. Read Capítulo 2, Arquitectura to understand the environments where Hibernate can be used.

  3. Déle un vistazo al directorio eg/ en la distribución de Hibernate. Este comprende una aplicación autónoma simple. Copie su compilador JDBC al directorio lib/ y edite etc/hibernate.properties, especificando los valores correctos para su base de datos. Desde un intérprete de comandos en el directorio de la distribución, escriba ant eg (utilizando Ant), o bajo Windows, escriba build eg.

  4. Use this reference documentation as your primary source of information. Consider reading [JPwH] if you need more help with application design, or if you prefer a step-by-step tutorial. Also visit http://caveatemptor.hibernate.org and download the example application from [JPwH].

  5. En el sitio web de Hibernate encontrará las respuestas a las preguntas más frecuentes.

  6. En el sitio web de Hibernate encontrará los enlaces a las demostraciones de terceros, ejemplos y tutoriales.

  7. El área de la comunidad en el sitio web de Hibernate es un buen recurso para encontrar patrones de diseño y varias soluciones de integración (Tomcat, JBoss AS, Struts, EJB, etc).

Si tiene alguna pregunta, diríjase al sitio web de Hibernate en donde encontrará un enlace al foro de usuarios. También proporcionamos un sistema de localización para reportes de errores JIRA y solicitud de funciones. Si está interesado en el desarrollo de Hibernate, únase a la lista de correo de los desarrolladores. Si le interesa traducir esta documentación a su propio idioma, contáctenos en la lista de correo de los desarrolladores.

JBoss Inc. proporciona soporte para desarrollo comercial, soporte para producción y entrenamiento (vea http://www.hibernate.org/SupportTraining/). Hibernate es un proyecto de Código Abierto Profesional y es un componente crítico de la suite de productos de JBoss Enterprise Middleware System (JEMS).

Dirigido a los nuevos usuarios, este capítulo brinda una introducción a Hibernate paso por paso, empezando con una aplicación simple usando una base de datos en memoria. Este tutorial se basa en un tutorial anterior que Michael Gloegl desarrolló. Todo el código se encuentra en el directorio tutorials/web de la fuente del proyecto.

Importante

Este tutorial se basa en que el usuario tenga conocimiento de Java y SQL. Si tiene un conocimiento muy limitado de JAVA o SQL, le aconsejamos que empiece con una buena introducción a esta tecnología antes de tratar de aprender sobre Hibernate.

Nota

La distribución contiene otra aplicación de ejemplo bajo el directorio fuente del proyecto tutorial/eg.

Para este ejemplo, vamos a configurar una aplicación base de datos pequeña que pueda almacenar eventos a los que queremos asistir e información sobre los anfitriones de estos eventos.

Nota

Aunque puede utilizar cualquier base de datos con la que se sienta bien, vamos a usar HSQLDB (una base de datos Java en-memoria) para evitar describir la instalación/configuración de cualquier servidor de base de datos en particular.

Lo primero que tenemos que hacer es configurar el entorno de desarrollo. Vamos a utilizar el "diseño estándar" apoyado por muchas herramientas de construcción tal como Maven. Maven, en particular, tiene un buen recurso que describe este diseño. Como este tutorial va a ser una aplicación web, vamos a crear y a utilizar los directorios src/main/java, src/main/resources y src/main/webapp.

Vamos a usar Maven en este tutorial, sacando ventaja de sus funcionalidades de administración de dependencias transitivas así como la habilidad de muchos IDEs para configurar automáticamente un proyecto para nosotros con base en el descriptor maven.


<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">

    <modelVersion
>4.0.0</modelVersion>

    <groupId
>org.hibernate.tutorials</groupId>
    <artifactId
>hibernate-tutorial</artifactId>
    <version
>1.0.0-SNAPSHOT</version>
    <name
>First Hibernate Tutorial</name>

    <build>
         <!-- we dont want the version to be part of the generated war file name -->
         <finalName
>${artifactId}</finalName>
    </build>

    <dependencies>
        <dependency>
            <groupId
>org.hibernate</groupId>
            <artifactId
>hibernate-core</artifactId>
        </dependency>

        <!-- Because this is a web app, we also have a dependency on the servlet api. -->
        <dependency>
            <groupId
>javax.servlet</groupId>
            <artifactId
>servlet-api</artifactId>
        </dependency>

        <!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend -->
        <dependency>
            <groupId
>org.slf4j</groupId>
            <artifactId
>slf4j-simple</artifactId>
        </dependency>

        <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist -->
        <dependency>
            <groupId
>javassist</groupId>
            <artifactId
>javassist</artifactId>
        </dependency>
    </dependencies>

</project
>

Sugerencia

It is not a requirement to use Maven. If you wish to use something else to build this tutorial (such as Ant), the layout will remain the same. The only change is that you will need to manually account for all the needed dependencies. If you use something like Ivy providing transitive dependency management you would still use the dependencies mentioned below. Otherwise, you'd need to grab all dependencies, both explicit and transitive, and add them to the project's classpath. If working from the Hibernate distribution bundle, this would mean hibernate3.jar, all artifacts in the lib/required directory and all files from either the lib/bytecode/cglib or lib/bytecode/javassist directory; additionally you will need both the servlet-api jar and one of the slf4j logging backends.

Guarde este archivo como pom.xml en el directorio raíz del proyecto.

Luego creamos una clase que representa el evento que queremos almacenar en la base de datos, es una clase JavaBean simple con algunas propiedades:

package org.hibernate.tutorial.domain;


import java.util.Date;
public class Event {
    private Long id;
    private String title;
    private Date date;
    public Event() {}
    public Long getId() {
        return id;
    }
    private void setId(Long id) {
        this.id = id;
    }
    public Date getDate() {
        return date;
    }
    public void setDate(Date date) {
        this.date = date;
    }
    public String getTitle() {
        return title;
    }
    public void setTitle(String title) {
        this.title = title;
    }
}

Esta clase utiliza convenciones de nombrado estándares de JavaBean para los métodos de propiedades getter y setter así como también visibilidad privada para los campos. Se recomienda este diseño, pero no se exige. Hibernate también puede acceder a los campos directamente, los métodos de acceso benefician la robustez de la refactorización.

La propiedad id tiene un valor identificador único para un evento en particular. Todas las clases de entidad persistentes necesitarán tal propiedad identificadora si queremos utilizar el grupo completo de funcionalidades de Hibernate (también algunas clases dependientes menos importantes). De hecho, la mayoría de las aplicaciones (en especial las aplicaciones web) necesitan distinguir los objetos por identificador, así que usted debe tomar esto como una funcionalidad más que una limitación. Sin embargo, usualmente no manipulamos la identidad de un objeto, por lo tanto, el método setter debe ser privado. Sólamente Hibernate asignará identificadores cuando se guarde un objeto. Como se puede ver, Hibernate puede acceder a métodos de acceso públicos, privados y protegidos, así como también a campos directamente públicos, privados y protegidos. Puede escoger y hacer que se ajuste a su diseño de su aplicación.

El constructor sin argumentos es un requerimiento para todas las clases persistentes, Hibernate tiene que crear objetos por usted utilizando Java Reflection. El constructor puede ser privado; sin embargo, se necesita la visibilidad del paquete para generar proxies en tiempo de ejecución y para la recuperación de datos de manera efectiva sin la instrumentación del código byte.

Duarde este archivo en el directorio src/main/java/org/hibernate/tutorial/domain.

Hibernate necesita saber cómo cargar y almacenar objetos de la clase persistente. En este punto es donde entra en juego el archivo de mapeo de Hibernate. Este archivo le dice a Hibernate a que tabla tiene que acceder en la base de datos, y que columnas debe utilizar en esta tabla.

La estructura básica de un archivo de mapeo se ve así:


<?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="org.hibernate.tutorial.domain">
[...]
</hibernate-mapping
>

El DTD de Hibernate es sofisticado. Puede utilizarlo para autocompletar los elementos y atributos XML de mapeo en su editor o IDE. Abrir el archivo DTD en su editor de texto es la manera más fácil para obtener una sinopsis de todos los elementos y atributos y para ver los valores por defecto, así como algunos de los comentarios. Note que Hibernate no cargará el fichero DTD de la web, sino que primero lo buscará en la ruta de clase de la aplicación. El archivo DTD se encuentra incluido en hibernate-core.jar (también en hibernate3.jar si está usando el paquete de la distribución).

Entre las dos etiquetas hibernate-mapping, incluya un elemento class. Todas las clases de entidad persistentes (de nuevo, podrían haber clases dependientes más adelante, las cuales no son entidades de primera clase) necesitan de dicho mapeo en una tabla en la base de datos SQL:


<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">

    </class>

</hibernate-mapping
>

Hasta ahora le hemos dicho a Hibernate cómo persistir y cargar el objeto de clase Event a la tabla EVENTS. Cada instancia se encuentra representada por una fila en esa tabla. Ahora podemos continuar mapeando la propiedad identificadora única a la clave primaria de la tabla. Ya que no queremos preocuparnos por el manejo de este identificador, configuramos la estrategia de generación del identificador de Hibernate para una columna clave primaria sustituta:


<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">
        <id name="id" column="EVENT_ID">
            <generator class="native"/>
        </id>
    </class>

</hibernate-mapping
>

El elemento id es la declaración de la propiedad identificadora. El atributo de mapeo name="id" declara el nombre de la propiedad JavaBean y le dice a Hibernate que utilice los métodos getId() y setId() para acceder a la propiedad. El atributo columna le dice a Hibernate qué columna de la tabla EVENTS tiene el valor de la llave principal.

El elemento anidado generator especifica la estrategia de generación del identificador (también conocidos como ¿cómo se generan los valores del identificador?). En este caso escogimos native, el cual ofrece un nivel de qué tan portátil es dependiendo del dialecto configurado de la base de datos. Hibernate soporta identificadores generados por la base de datos, globalmente únicos así como asignados por la aplicación. La generación del valor del identificador también es uno de los muchos puntos de extensión de Hibernate y puede conectar su propia estrategia.

Por último es necesario decirle a Hibernate sobre las porpiedades de clase de entidad que quedan. Por defecto, ninguna propiedad de la clase se considera persistente:



<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">
        <id name="id" column="EVENT_ID">
            <generator class="native"/>
        </id>
        <property name="date" type="timestamp" column="EVENT_DATE"/>
        <property name="title"/>
    </class>

</hibernate-mapping
>

Al igual que con el elemento id, el atributo name del elemento property le dice a Hibernate que métodos getter y setter utilizar. Así que en este caso, Hibernate buscará los métodos getDate(), setDate(), getTitle() y setTitle().

Nota

¿Por qué el mapeo de la propiedad date incluye el atributo column, pero el de title no? Sin el atributo column Hibernate utiliza, por defecto, el nombre de propiedad como nombre de la columna. Esto funciona bien para title. Sin embargo, date es una palabra clave reservada en la mayoría de las bases de datos, así que es mejor que la mapeamos a un nombre diferente.

El mapeo de title carece de un atributo type. Los tipos que declaramos y utilizamos en los archivos de mapeo no son tipos de datos Java. Tampoco son tipos de base de datos SQL. Estos tipos se llaman tipos de mapeo Hibernate , convertidores que pueden traducir de tipos de datos de Java a SQL y viceversa. De nuevo, Hibernate tratará de determinar el tipo correcto de conversión y de mapeo por sí mismo si el atributo type no se encuentra presente en el mapeo. En algunos casos esta detección automática (utilizando Reflection en la clase Java) puede que no tenga lo que usted espera o necesita. Este es el caso de la propiedad date. Hibernate no puede saber is la propiedad, la cual es de java.util.Date, debe mapear a una columna date, timestamp o time de SQL. Por medio de un convertidor timestamp, mapeamos la propiedad y mantenemos la información completa sobre la hora y fecha.

Sugerencia

Hibernate realiza esta determinación de tipo de mapeo usando reflection cuando se procesan los archivos de mapeo. Esto puede tomar tiempo y recursos así que el rendimiento al arrancar es importante entonces debe considerar el definir explícitamente el tipo a usar.

Guarde este archivo de mapeo como src/main/resources/org/hibernate/tutorial/domain/Event.hbm.xml.

En este momento debe tener la clase persistente y su archivo de mapeo. Ahora debe configurar Hibernate. Primero vamos a configurar HSQLDB para que ejecute en "modo de servidor"

Vamos a utilizar el plugin de ejecución Maven para lanzar el servidor HSQLDB ejecutando: mvn exec:java -Dexec.mainClass="org.hsqldb.Server" -Dexec.args="-database.0 file:target/data/tutorial".Lo verá iniciando y vinculandose a un enchufe TCP/IP, allí es donde nuestra aplicación se conectará más adelante. Si quiere dar inicio con una base de datos fresca durante este tutorial, apague HSQLDB, borre todos los archivos en el directorio target/data e inicie HSQLDB de nuevo.

Hibernate se conectará a la base de datos de parte de su aplicación así que necesita saber cómo obtener conexiones. Para este tutorial vamos a utilizar un pool de conexiones autónomo (opuesto a javax.sql.DataSource). Hibernate viene con soporte para dos pools de conexiones JDBC de código abierto de terceros: c3p0 y proxool. Sin embargo, vamos a utilizar el pool de conexiones incluido de Hibernate para este tutorial.

Atención

El pool de conexiones de Hibernate no está diseñado para utilizarse en producción. Le faltan varias funcionalidades que se encuentran en cualquier pool de conexiones decente.

Para la configuración de Hibernate, podemos utilizar un archivo hibernate.properties simple, un archivo hibernate.cfg.xml un poco más sofisticado, o incluso una configuración completamente programática. La mayoría de los usuarios prefieren el archivo de configuración XML:


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

<hibernate-configuration>

    <session-factory>

        <!-- Database connection settings -->
        <property name="connection.driver_class"
>org.hsqldb.jdbcDriver</property>
        <property name="connection.url"
>jdbc:hsqldb:hsql://localhost</property>
        <property name="connection.username"
>sa</property>
        <property name="connection.password"
></property>

        <!-- JDBC connection pool (use the built-in) -->
        <property name="connection.pool_size"
>1</property>

        <!-- SQL dialect -->
        <property name="dialect"
>org.hibernate.dialect.HSQLDialect</property>

        <!-- Enable Hibernate's automatic session context management -->
        <property name="current_session_context_class"
>thread</property>

        <!-- Disable the second-level cache  -->
        <property name="cache.provider_class"
>org.hibernate.cache.NoCacheProvider</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"
>update</property>

        <mapping resource="org/hibernate/tutorial/domain/Event.hbm.xml"/>

    </session-factory>

</hibernate-configuration
>

Nota

Observe que este archivo de configuración especifica un DTD diferente

Configure la SessionFactory de Hibernate. SessionFactory es una fábrica global responsable de una base de datos en particular. Si usted tiene varias bases de datos, para un inicio más fácil utilice varias configuraciones <session-factory> en varios archivos de configuración.

Los primeros cuatro elementos property contienen la configuración necesaria para la conexión JDBC. El elemento property dialecto especifica la variante SQL en particular que Hibernate genera.

Sugerencia

In most cases, Hibernate is able to properly determine which dialect to use. See Sección 26.3, “Resolución del dialecto” for more information.

La administración de la sesión automática de Hibernate para contextos de persistencia es particularmente útil en este contexto. La opción hbm2ddl.auto activa la generación automática de los esquemas de la base de datos directamente en la base de datos. Esto se puede desactivar, eliminando la opción de configuración o redirigiéndolo a un archivo con la ayuda de la tarea de Ant SchemaExport. Finalmente, agregue a la configuración el/los fichero(s) de mapeo para clases persistentes.

Guarde este archivo como hibernate.cfg.xml en el directorio src/main/resources.

Ahora vamos a construir el tutorial con Maven. Es necesario que tenga instalado Maven; se encuentra disponible en la página de descargas Maven. Maven leerá el archivo /pom.xml que creamos anteriormente y sabrá cómo realizar algunas tareas de proyectos básicos. Primero, vamos a ejecutar la meta compile para asegurarnos de que podemos compilar todo hasta el momento:

[hibernateTutorial]$ mvn compile
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building First Hibernate Tutorial
[INFO]    task-segment: [compile]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Compiling 1 source file to /home/steve/projects/sandbox/hibernateTutorial/target/classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009
[INFO] Final Memory: 5M/547M
[INFO] ------------------------------------------------------------------------

Es el momento de cargar y almacenar algunos objetos Event, pero primero tiene que completar la configuración con algo de código de infraestructura. Tiene que iniciar Hibernate construyendo un objeto org.hibernate.SessionFactory global y almacenarlo en algún lugar de fácil acceso en el código de la aplicación. Una org.hibernate.SessionFactory se utiliza para obtener instancias org.hibernate.Session. Una org.hibernate.Session representa una unidad de trabajo mono-hilo. La org.hibernate.SessionFactory es un objeto global seguro entre hilos que se instancia una sóla vez.

Vamos a crear una clase de ayuda HibernateUtil que se encargue del inicio y haga más práctico el acceso a org.hibernate.SessionFactory.

package org.hibernate.tutorial.util;


import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;
public class HibernateUtil {
    private static final SessionFactory sessionFactory = buildSessionFactory();
    private static SessionFactory buildSessionFactory() {
        try {
            // Create the SessionFactory from hibernate.cfg.xml
            return new Configuration().configure().buildSessionFactory();
        }
        catch (Throwable ex) {
            // Make sure you log the exception, as it might be swallowed
            System.err.println("Initial SessionFactory creation failed." + ex);
            throw new ExceptionInInitializerError(ex);
        }
    }
    public static SessionFactory getSessionFactory() {
        return sessionFactory;
    }
}

Guarde este código como src/main/java/org/hibernate/tutorial/util/HibernateUtil.java

Esta clase no sólamente produce la referencia org.hibernate.SessionFactory global en su inicializador estático, sino que también esconde el hecho de que utiliza un singleton estático. También puede que busque la referencia org.hibernate.SessionFactory desde JNDI en un servidor de aplicaciones en cualquier otro lugar.

Si usted le da un nombre a org.hibernate.SessionFactory en su archivo de configuración, de hecho, Hibernate tratará de vincularlo a JNDI bajo ese nombre después de que ha sido construido. Otra mejor opción es utilizar el despliegue JMX y dejar que el contenedor con capacidad JMX instancie y vincule un HibernateService a JNDI. Más adelante discutiremos estas opciones avanzadas.

Ahora necesita configurar un sistema de registro. Hibernate utiliza registros comunes le da dos opciones: Log4J y registros de JDK 1.4. La mayoría de los desarrolladores prefieren Log4J: copie log4j.properties de la distribución de Hibernate, se encuentra en el directorio etc/) a su directorio src, junto a hibernate.cfg.xml. Si desea tener una salida más verbosa que la que se proporcionó en la configuración del ejemplo entonces puede cambiar su configuración. Por defecto, sólo se muestra el mensaje de inicio de Hibernate en la salida estándar.

La infraestructura del tutorial está completa y estamos listos para hacer un poco de trabajo real con Hibernate.

We are now ready to start doing some real work with Hibernate. Let's start by writing an EventManager class with a main() method:

package org.hibernate.tutorial;


import org.hibernate.Session;
import java.util.*;
import org.hibernate.tutorial.domain.Event;
import org.hibernate.tutorial.util.HibernateUtil;
public class EventManager {
    public static void main(String[] args) {
        EventManager mgr = new EventManager();
        if (args[0].equals("store")) {
            mgr.createAndStoreEvent("My Event", new Date());
        }
        HibernateUtil.getSessionFactory().close();
    }
    private void createAndStoreEvent(String title, Date theDate) {
        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Event theEvent = new Event();
        theEvent.setTitle(title);
        theEvent.setDate(theDate);
        session.save(theEvent);
        session.getTransaction().commit();
    }
}

En createAndStoreEvent() creamos un nuevo objeto Event y se lo entregamos a Hibernate. En ese momento, Hibernate se encarga de SQL y ejecuta un INSERT en la base de datos.

A org.hibernate.Session is designed to represent a single unit of work (a single atomic piece of work to be performed). For now we will keep things simple and assume a one-to-one granularity between a Hibernate org.hibernate.Session and a database transaction. To shield our code from the actual underlying transaction system we use the Hibernate org.hibernate.Transaction API. In this particular case we are using JDBC-based transactional semantics, but it could also run with JTA.

¿Qué hace sessionFactory.getCurrentSession()? Primero, la puede llamar tantas veces como desee y en donde quiera, una vez consiga su org.hibernate.SessionFactory. El método getCurrentSession() siempre retorna la unidad de trabajo "actual". ¿Recuerda que cambiamos la opción de la configuración de este mecanismo a "thread" en src/main/resources/hibernate.cfg.xml? Por lo tanto, el contexto de una unidad de trabajo actual se encuentra vinculada al hilo de Java actual que ejecuta nuestra aplicación.

Una org.hibernate.Session se inicia cuando se realiza la primera llamada a getCurrentSession() para el hilo actual. Luego Hibernate la vincula al hilo actual. Cuando termina la transacción, ya sea por medio de guardar o deshacer los cambios, Hibernate desvincula automáticamente la org.hibernate.Session del hilo y la cierra por usted. Si llama a getCurrentSession() de nuevo, obtiene una org.hibernate.Session nueva y obtiene una nueva org.hibernate.Session unidad de trabajo.

En relación con la unidad del campo de trabajo, ¿Se debería utilizar org.hibernate.Session de Hibernate para ejecutar una o varias operaciones de la base de datos? El ejemplo anterior utiliza una org.hibernate.Session para una operación. Sin embargo, esto es pura coincidencia; el ejemplo simplemente no es lo suficientemente complicado para mostrar cualquier otro enfoque. El ámbito de una org.hibernate.Session de Hibernate es flexible pero nunca debe diseñar su aplicación para que utilice una nueva org.hibernate.Session de Hibernate para cada operación de la base de datos. Aunque lo utilizamos en los siguientes ejemplos, considere la sesión-por-operación como un anti-patrón. Más adelante en este tutorial, se muestra una aplicación web real, lo cual le ayudará a ilustrar esto.

See Capítulo 12, Transacciones y concurrencia for more information about transaction handling and demarcation. The previous example also skipped any error handling and rollback.

Para ejecutar esto, utilizaremos el plugin de ejecución Maven para llamar nuestra clase con la configuración de ruta de clase necesaria: mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="store"

Nota

Es posible que primero necesite realizar mvn compile.

Debe ver que Hibernate inicia y dependiendo de su configuración, también verá bastantes salidas de registro. Al final, verá la siguiente línea:

[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)

Este es el INSERT que Hibernate ejecuta.

Para listar los eventos almacenados se agrega una opción al método principal:

        if (args[0].equals("store")) {

            mgr.createAndStoreEvent("My Event", new Date());
        }
        else if (args[0].equals("list")) {
            List events = mgr.listEvents();
            for (int i = 0; i < events.size(); i++) {
                Event theEvent = (Event) events.get(i);
                System.out.println(
                        "Event: " + theEvent.getTitle() + " Time: " + theEvent.getDate()
                );
            }
        }

También agregamos un método listEvents():

    private List listEvents() {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        List result = session.createQuery("from Event").list();
        session.getTransaction().commit();
        return result;
    }

Here, we are using a Hibernate Query Language (HQL) query to load all existing Event objects from the database. Hibernate will generate the appropriate SQL, send it to the database and populate Event objects with the data. You can create more complex queries with HQL. See Capítulo 15, HQL: El lenguaje de consulta de Hibernate for more information.

Ahora podemos llamar nuestra nueva funcionalidad, de nuevo usando el plugin de ejecución Maven: mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="list"

Hasta ahora hemos mapeado una clase de entidad persistente a una tabla aislada. Vamos a construir sobre esto y agregaremos algunas asociaciones de clase. Vamos a agregar personas a la aplicación y vamos a almacenar una lista de eventos en las que participan.

Al agregar una colección de eventos a la clase Person, puede navegar fácilmente a los eventos de una persona en particular, sin ejecutar una petición explícita - llamando a Person#getEvents. En Hibernate, las asociaciones multi-valores se representan por medio de uno de los contratos del marco de colecciones Java; aquí escogimos un java.util.Set ya que la colección no contendrá elementos duplicados y el orden no es relevante para nuestros ejemplos.

public class Person {


    private Set events = new HashSet();
    public Set getEvents() {
        return events;
    }
    public void setEvents(Set events) {
        this.events = events;
    }
}

Antes de mapear esta asociación, considere el otro lado. Podriamos mantener esto unidireccional o podríamos crear otra colección en el Event, si queremos tener la habilidad de navegarlo desde ambas direcciones. Esto no es necesario desde un punto de vista funcional. Siempre puede ejeutar un pedido explícito para recuperar los participantes de un evento en particular. Esta es una elección de diseño que depende de usted, pero lo que queda claro de esta discusión es la multiplicidad de la asociación: "muchos" valuada en ambos lados, denominamos esto como una asociación muchos-a-muchos. Por lo tanto, utilizamos un mapeo muchos-a-muchos de Hibernate:


<class name="Person" table="PERSON">
    <id name="id" column="PERSON_ID">
        <generator class="native"/>
    </id>
    <property name="age"/>
    <property name="firstname"/>
    <property name="lastname"/>

    <set name="events" table="PERSON_EVENT">
        <key column="PERSON_ID"/>
        <many-to-many column="EVENT_ID" class="Event"/>
    </set>

</class
>

Hibernate soporta un amplio rango de mapeos de colección, el más común set. Para una asociación muchos-a-muchos o la relación de entidad n:m, se necesita una tabla de asociación. Cada fila en esta tabla representa un enlace entre una persona y un evento. El nombre de esta tabla se declara con el atributo table del elemento set. El nombre de la columna identificadora en la asociación, del lado de la persona, se define con el elemento key, el nombre de columna para el lado del evento se define con el atributo column del many-to-many. También tiene que informarle a Hibernate la clase de los objetos en su colección (la clase del otro lado de la colección de referencias).

Por consiguiente, el esquema de base de datos para este mapeo es:

    _____________        __________________
   |             |      |                  |       _____________
   |   EVENTS    |      |   PERSON_EVENT   |      |             |
   |_____________|      |__________________|      |    PERSON   |
   |             |      |                  |      |_____________|
   | *EVENT_ID   | <--> | *EVENT_ID        |      |             |
   |  EVENT_DATE |      | *PERSON_ID       | <--> | *PERSON_ID  |
   |  TITLE      |      |__________________|      |  AGE        |
   |_____________|                                |  FIRSTNAME  |
                                                  |  LASTNAME   |
                                                  |_____________|
 

Vamos a reunir a algunas personas y eventos en un nuevo método en EventManager:

    private void addPersonToEvent(Long personId, Long eventId) {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Person aPerson = (Person) session.load(Person.class, personId);
        Event anEvent = (Event) session.load(Event.class, eventId);
        aPerson.getEvents().add(anEvent);
        session.getTransaction().commit();
    }

Después de cargar una Person y un Event, simplemente modifique la colección utilizando los métodos normales de colección. No hay una llamada explícita a update() o save(); Hibernate detecta automáticamente que se ha modificado la colección y que se necesita actualizarla. Esto se denomina chequeo automático de desactualizaciones y también puede probarlo modificando el nombre o la propiedad de fecha de cualquiera de sus objetos. Mientras se encuentran en estado persistente, es decir, enlazado a una org.hibernate.Session de Hibernate en particular, Hibernate monitorea cualquier cambio y ejecuta SQL de un modo escribe-detrás. El proceso de sincronización del estado de la memoria con la base de datos, usualmente sólo al final de una unidad de trabajo, se denomina vaciado. En nuestro código la unidad de trabajo termina con guardar o deshacer los cambios de la transacción de la base de datos.

Puede cargar una persona y un evento en diferentes unidades de trabajo. También puede modificar un objeto fuera de una org.hibernate.Session, cuando no se encuentra en estado persistente (si antes era persistente denominamos a este estado separado ). Inclusive, puede modificar una colección cuando se encuentre separada:

    private void addPersonToEvent(Long personId, Long eventId) {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Person aPerson = (Person) session
                .createQuery("select p from Person p left join fetch p.events where p.id = :pid")
                .setParameter("pid", personId)
                .uniqueResult(); // Eager fetch the collection so we can use it detached
        Event anEvent = (Event) session.load(Event.class, eventId);
        session.getTransaction().commit();
        // End of first unit of work
        aPerson.getEvents().add(anEvent); // aPerson (and its collection) is detached
        // Begin second unit of work
        Session session2 = HibernateUtil.getSessionFactory().getCurrentSession();
        session2.beginTransaction();
        session2.update(aPerson); // Reattachment of aPerson
        session2.getTransaction().commit();
    }

La llamada a update hace que un objeto separado sea persistente de nuevo enlazándolo a una nueva unidad de trabajo, así que cualquier modificación que le realizó mientras estaba separado se puede guardar en la base de datos. Esto incluye cualquier modificación (adiciones o eliminaciones) que le hizo a una colección de ese objeto entidad.

Esto no se utiliza mucho en nuestro ejemplo, pero es un concepto importante que puede incorporar en su propia aplicación. Complete este ejercicio agregando una nueva acción al método main de EventManager y llámela desde la línea de comandos. Si necesita los identificadores de una persona y de un evento - el método save() los retorna (pueda que necesite modificar algunos de los métodos anteriores para retornar ese identificador):

        else if (args[0].equals("addpersontoevent")) {

            Long eventId = mgr.createAndStoreEvent("My Event", new Date());
            Long personId = mgr.createAndStorePerson("Foo", "Bar");
            mgr.addPersonToEvent(personId, eventId);
            System.out.println("Added person " + personId + " to event " + eventId);
        }

Esto fue un ejemplo de una asociación entre dos clases igualmente importantes: dos entidades. Como se mencionó anteriormente, hay otras clases y tipos en un modelo típico, usualmente "menos importantes". Algunos de ustedes las habrán visto, como un int o un java.lang.String. Denominamos a estas clases tipos de valor y sus instancias dependen de una entidad en particular. Las instancias de estos tipos no tienen su propia identidad, ni son compartidas entre entidades. Dos personas no referencian el mismo objeto firstname, incluso si tienen el mismo nombre. Los tipos de valor no sólo pueden encontrarse en el JDK, sino que también puede escribir por sí mismo clases dependientes como por ejemplo, Address o MonetaryAmount. De hecho, en una aplicación Hibernate todas las clases JDK se consideran como tipos de valor.

También puede diseñar una colección de tipos de valor. Esto es conceptualmente diferente de una colección de referencias a otras entidades, pero se ve casi igual en Java.

Vamos a agregar una colección de direcciones de correo electrónico a la entidad Person. Esto se representará como un java.util.Set de las instnaicas java.lang.String:

    private Set emailAddresses = new HashSet();


    public Set getEmailAddresses() {
        return emailAddresses;
    }
    public void setEmailAddresses(Set emailAddresses) {
        this.emailAddresses = emailAddresses;
    }

El mapeo de este Set es así:


        <set name="emailAddresses" table="PERSON_EMAIL_ADDR">
            <key column="PERSON_ID"/>
            <element type="string" column="EMAIL_ADDR"/>
        </set
>

La diferencia comparado con el mapeo anterior es el uso de la parte element, que le dice a Hibernate que la colección no contiene referencias a otra entidad, sino que es una colección de elementos que son tipos de valores, aquí especificamente de tipo String. El nombre en minúsculas le dice que es un tipo/conversor de mapeo de Hibernate. Una vez más, el atributo table del elemento set determina el nombre de la tabla para la colección. El elemento key define el nombre de la columna clave foránea en la tabla de colección. El atributo column en el elemento element define el nombre de la columna donde realmente se almacenarán los valores de la dirección de correo electrónico.

Este es el esquema actualizado:

  _____________        __________________
 |             |      |                  |       _____________
 |   EVENTS    |      |   PERSON_EVENT   |      |             |       ___________________
 |_____________|      |__________________|      |    PERSON   |      |                   |
 |             |      |                  |      |_____________|      | PERSON_EMAIL_ADDR |
 | *EVENT_ID   | <--> | *EVENT_ID        |      |             |      |___________________|
 |  EVENT_DATE |      | *PERSON_ID       | <--> | *PERSON_ID  | <--> |  *PERSON_ID       |
 |  TITLE      |      |__________________|      |  AGE        |      |  *EMAIL_ADDR      |
 |_____________|                                |  FIRSTNAME  |      |___________________|
                                                |  LASTNAME   |
                                                |_____________|
 

Puede ver que la clave principal de la tabla de colección es, de hecho, una clave compuesta que utiliza ambas columnas. Esto también implica que no pueden haber direcciones de correo electrónico duplicadas por persona, la cual es exactamente la semántica que necesitamos para un conjunto en Java.

Ahora, puede tratar de agregar elementos a esta colección, al igual que lo hicimos antes vinculando personas y eventos. Es el mismo código en Java.

    private void addEmailToPerson(Long personId, String emailAddress) {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Person aPerson = (Person) session.load(Person.class, personId);
        // adding to the emailAddress collection might trigger a lazy load of the collection
        aPerson.getEmailAddresses().add(emailAddress);
        session.getTransaction().commit();
    }

Esta vez no utilizamos una petición de búqueda - fetch - para dar inicio a la colección. Monitoree su registro SQL e intente de optimizar esto con una recuperación temprana.

A continuacion vamos a mapear una asociación bidireccional. Vamos a hacer que la asociación entre persona y evento funcione desde ambos lados en Java. El esquema de la base de datos no cambia así que todavía tendremos una multiplicidad muchos-a-muchos.

Primero, agregue una colección de participantes a la clase Event:

    private Set participants = new HashSet();


    public Set getParticipants() {
        return participants;
    }
    public void setParticipants(Set participants) {
        this.participants = participants;
    }

Ahora mapee este lado de la asociación en Event.hbm.xml.


        <set name="participants" table="PERSON_EVENT" inverse="true">
            <key column="EVENT_ID"/>
            <many-to-many column="PERSON_ID" class="events.Person"/>
        </set
>

Estos son mapeos normales de set en ambos documentos de mapeo. Note que los nombres de las columnas en key y many-to-many se intercambiaron en ambos documentos de mapeo. La adición más importante aquí es el atributo inverse="true" en el elemento set del mapeo de colección de Event.

Esto significa que Hibernate debe tomar el otro lado, la clase Person, cuando necesite encontrar información sobre el enlace entre las dos. Esto será mucho más fácil de entender una vez que vea como se crea el enlace bidireccional entre nuestras dos entidades.

Primero, recuerde que Hibernate no afecta la semántica normal de Java. ¿Cómo creamos un enlace entre Person y un Event en el ejemplo unidireccional? Agregue una instancia de Event a la colección de referencias de eventos de una instancia de Person. Si quiere que este enlace funcione bidireccionalmente, tiene que hacer lo mismo del otro lado, añadiendo una referencia Person a la colección en un Event. Este proceso de "establecer el enlace en ambos lados" es absolutamente necesario con enlaces bidireccionales.

Muchos desarrolladores programan a la defensiva y crean métodos de administración de enlaces para establecer correctamente ambos lados, (por ejemplo, en Person):

    protected Set getEvents() {

        return events;
    }
    protected void setEvents(Set events) {
        this.events = events;
    }
    public void addToEvent(Event event) {
        this.getEvents().add(event);
        event.getParticipants().add(this);
    }
    public void removeFromEvent(Event event) {
        this.getEvents().remove(event);
        event.getParticipants().remove(this);
    }

Los métodos get y set para la colección ahora se encuentran protegidos. Esto le permite a las clases en el mismo paquete y a las subclases acceder aún a los métodos, pero impide a cualquier otro que desordene las colecciones directamente. Repita los pasos para la colección del otro lado.

¿Y el atributo de mapeo inverse? Para usted y para Java, un enlace bidireccional es simplemente cuestión de establecer correctamente las referencias en ambos lados. Sin embargo, Hibernate no tiene suficiente información para organizar correctamente declaraciones INSERT y UPDATE de SQL (para evitar violaciones de restricciones). El hacer un lado de la asociación inverse le dice a Hibernate que lo considere un espejo del otro lado. Eso es todo lo necesario para que Hibernate resuelva todos los asuntos que surgen al transformar un modelo de navegación direccional a un esquema de base de datos SQL. Las reglas son muy simples: todas las asociaciones bidireccionales necesitan que uno de los lados sea inverse. En una asociación uno-a-muchos debe ser el lado-de-muchos; y en una asociación muchos-a-muchos, puede escoger cualquier lado.

Una aplicación web de Hibernate utiliza Session y Transaction casi como una aplicación autónoma. Sin embargo, algunos patrones comunes son útiles. Ahora puede escribir un EventManagerServlet. Este servlet puede enumerar todos los eventos almacenados en la base de datos y proporciona una forma HTML para ingresar eventos nuevos.

Primero necesitamos crear nuestro servlet de procesamiento básico. Ya que nuestro servlet solo maneja pedidos GET HTTP sólamente, solo implementaremos el método doGet():

package org.hibernate.tutorial.web;


// Imports
public class EventManagerServlet extends HttpServlet {
    protected void doGet(
            HttpServletRequest request,
            HttpServletResponse response) throws ServletException, IOException {
        SimpleDateFormat dateFormatter = new SimpleDateFormat( "dd.MM.yyyy" );
        try {
            // Begin unit of work
            HibernateUtil.getSessionFactory().getCurrentSession().beginTransaction();
            // Process request and render page...
            // End unit of work
            HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().commit();
        }
        catch (Exception ex) {
            HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().rollback();
            if ( ServletException.class.isInstance( ex ) ) {
                throw ( ServletException ) ex;
            }
            else {
                throw new ServletException( ex );
            }
        }
    }
}

Guarde este servlet como src/main/java/org/hibernate/tutorial/web/EventManagerServlet.java

El patrón aplicado aquí se llama sesión-por-petición. Cuando una petición llega al servlet, se abre una nueva Session de Hibernate por medio de la primera llamada a getCurrentSession() en el SessionFactory. Entonces se inicia una transacción de la base de datos. Todo acceso a los datos tiene que suceder dentro de una transacción, sin importar que los datos sean leídos o escritos . No utilice el modo auto-commit en las aplicaciones.

No utilice una nueva Session de Hibernate para cada operación de base de datos. Utilice una Session Hibernate que cubra el campo de todo el pedido. Utilice getCurrentSession() para vincularlo automáticamente al hilo de Java actual.

Después, se procesan las acciones posibles del pedido y se entrega la respuesta HTML. Llegaremos a esa parte muy pronto.

Finalmente, la unidad de trabajo termina cuando se completa el procesamiento y la entrega. Si surgió algún problema durante el procesamiento o la entrega , se presentará una excepción y la transacción de la base de datos se deshará. Esto completa el patrón session-per-request. En vez del código de demarcación de la transacción en todo servlet, también podría escribir un filtro de servlet. Véa el sitio web de Hibernate y el Wiki para obtener más información sobre este patrón llamado sesión abierta en vista. Lo necesitará tan pronto como considere representar su vista en JSP, no en un servlet.

Ahora puede implementar el procesamiento del pedido y la representación de la página.

        // Write HTML header

        PrintWriter out = response.getWriter();
        out.println("<html
><head
><title
>Event Manager</title
></head
><body
>");
        // Handle actions
        if ( "store".equals(request.getParameter("action")) ) {
            String eventTitle = request.getParameter("eventTitle");
            String eventDate = request.getParameter("eventDate");
            if ( "".equals(eventTitle) || "".equals(eventDate) ) {
                out.println("<b
><i
>Please enter event title and date.</i
></b
>");
            }
            else {
                createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate));
                out.println("<b
><i
>Added event.</i
></b
>");
            }
        }
        // Print page
       printEventForm(out);
       listEvents(out, dateFormatter);
       // Write HTML footer
       out.println("</body
></html
>");
       out.flush();
       out.close();

Dado que este estilo de codificación con una mezcla de Java y HTML no escalaría en una aplicación más compleja - tenga en cuenta que sólo estamos ilustrando los conceptos básicos de Hibernate en este tutorial. El código imprime una cabecera y un pie de página HTML. Dentro de esta página se imprime una forma HTML para entrada de eventos y se imprime una lista de todos los eventos en la base de datos. El primer método es trivial y su salida se realiza únicamente en HTML:

    private void printEventForm(PrintWriter out) {

        out.println("<h2
>Add new event:</h2
>");
        out.println("<form
>");
        out.println("Title: <input name='eventTitle' length='50'/><br/>");
        out.println("Date (e.g. 24.12.2009): <input name='eventDate' length='10'/><br/>");
        out.println("<input type='submit' name='action' value='store'/>");
        out.println("</form
>");
    }

El método listEvents() utiliza Hibernate Session vinculado al hilo actual para ejecutar una petición:

    private void listEvents(PrintWriter out, SimpleDateFormat dateFormatter) {


        List result = HibernateUtil.getSessionFactory()
                .getCurrentSession().createCriteria(Event.class).list();
        if (result.size() 
> 0) {
            out.println("<h2
>Events in database:</h2
>");
            out.println("<table border='1'
>");
            out.println("<tr
>");
            out.println("<th
>Event title</th
>");
            out.println("<th
>Event date</th
>");
            out.println("</tr
>");
            Iterator it = result.iterator();
            while (it.hasNext()) {
                Event event = (Event) it.next();
                out.println("<tr
>");
                out.println("<td
>" + event.getTitle() + "</td
>");
                out.println("<td
>" + dateFormatter.format(event.getDate()) + "</td
>");
                out.println("</tr
>");
            }
            out.println("</table
>");
        }
    }

Finalmente, la acción store se despacha al método createAndStoreEvent(), el cual también utiliza la Session del hilo actual:

    protected void createAndStoreEvent(String title, Date theDate) {

        Event theEvent = new Event();
        theEvent.setTitle(title);
        theEvent.setDate(theDate);
        HibernateUtil.getSessionFactory()
                .getCurrentSession().save(theEvent);
    }

El servlet se encuentra completo. Un pedido al servlet será procesado en una sola Session y Transaction. Como lo vimos antes en la aplicación autónoma, Hibernate puede enlazar automáticamente estos objetos al hilo actual de ejecución. Esto le da la libertad de utilizar capas en su código y acceder a la SessionFactory de cualquier manera que lo desee. Usualmente, usted utilizaría un diseño más sofisticado y movería el código de acceso de datos a los objetos de acceso de datos (el patrón DAO). Refiérase al Wiki de Hibernate para ver más ejemplos.

Para implementar esta aplicación para prueba debemos crear una Web ARchive (WAR). Primero debemos definir el descriptor WAR como src/main/webapp/WEB-INF/web.xml


<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <servlet>
        <servlet-name
>Event Manager</servlet-name>
        <servlet-class
>org.hibernate.tutorial.web.EventManagerServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name
>Event Manager</servlet-name>
        <url-pattern
>/eventmanager</url-pattern>
    </servlet-mapping>
</web-app
>

Para construir y desplegar llame a mvn package en su directorio de proyecto y copie el archivo hibernate-tutorial.war en su directorio webapp Tomcat.

Nota

If you do not have Tomcat installed, download it from http://tomcat.apache.org/ and follow the installation instructions. Our application requires no changes to the standard Tomcat configuration.

Una vez que se encuentre desplegado y que Tomcat esté ejecutando, acceda la aplicación en http://localhost:8080/hibernate-tutorial/eventmanager. Asegúrese de ver el registro de Tomcat para ver a Hibernate iniciar cuando llegue el primer pedido a su servlet (se llama al inicializador estático en HibernateUtil) y para obetener la salida detallada si ocurre alguna excepción.

El diagrama a continuación brinda una perspectiva a alto nivel de la arquitectura de Hibernate:

Este documento no incluye una sinopsis detallada de la arquitecturas en tiempo de ejecución disponibles; Hibernate es flexible y soporta diferentes enfoques. Sin embargo, mostraremos los dos extremos: la arquitectura "mínima" y la arquitectura "completa".

Este diagrama ilustra la manera en que Hibernate utiliza la base de datos y los datos de configuración para proporcionar servicios de persistencia y objetos persistentes a la aplicación.

La arquitectura "mínima" hace que la aplicación proporcione sus propias conexiones JDBC y que administre sus propias transacciones. Este enfoque utiliza un subgrupo mínimo de las APIs de Hibernate:

La arquitectura "completa" abstrae la aplicación de las APIs de JDBC/JTA y permite que Hibernate se encargue de los detalles.

He aquí algunas definiciones de los objetos en los diagramas:

SessionFactory (org.hibernate.SessionFactory)

Un caché threadsafe (inmutable) de mapeos compilados para una sola base de datos. Una fábrica de Session y un cliente de ConnectionProvider, SessionFactory puede mantener un caché opcional (de segundo nivel) de datos reusables entre transacciones a nivel de proceso o de clúster.

Session (org.hibernate.Session)

Un objeto mono-hebra, de corta vida que representa una conversación entre la aplicación y el almacenamiento persistente. Envuelve una conexión JDBC y es una fábrica de Transaction. Session mantiene un caché requerido de primer nivel de objetos persistentes, que se utiliza cuando se navega el gráfico de objetos o mientras se buscan objetos por identificador.

Objetos y colecciones persistentes

Objetos de corta vida, mono-hebra contienen un estado persistente así como una funcionalidad empresarial. Estos pueden ser JavaBeans/POJOs normales. Estos se encuentran asociados con exactamente una Session. Tan pronto como la Session se cierre, serán separados y estarán libres para utilizarlos en cualquier capa de aplicación, (por ejemplo, directamente como objetos de transferencia de datos hacia y desde la presentación).

Objetos y colecciones transitorios y separados

Instancias de clases persistentes que no se encuentran actualmente asociadas con una Session. Pueden haber sido instanciadas por la aplicación y aún no haber sido persistidas, o pueden haber sido instanciadas por una Session cerrada.

Transaction (org.hibernate.Transaction)

(Opcional) Un objeto de corta vida, mono-hebra que la aplicación utiliza para especificar unidades atómicas de trabajo. Abstrae la aplicación de las transacciones subyacentes JDBC, JTA o CORBA. En algunos casos, una Session puede extenderse sobre varias Transactiones. Sin embargo, la demarcación de la transacción, ya sea utilizando la API subyacente o Transaction, nunca es opcional.

ConnectionProvider (org.hibernate.connection.ConnectionProvider)

(Opcional) Una fábrica y pool de conexiones JDBC. Abstrae a la aplicación del Datasource o DriverManager subyacente. No se expone a la aplicación, pero puede ser extendido/implementado por el desarrollador.

TransactionFactory (org.hibernate.TransactionFactory)

(Opcional) Una fábrica de instancias de Transaction. No se expone a la aplicación pero puede ser extendido/implementado por el desarrollador.

Extension Interfaces

Hibernate ofrece un rango de interfaces de extensión opcionales que puede implementar para personalizar el comportamiento de su capa de persistencia. Para obtener más detalles, vea la documentación de la API.

Dada una arquitectura "sencilla", la aplicación evita las APIs de Transaction/TransactionFactory y/o ConnectionProvider, para comunicarse directamente con JTA o JDBC.

JMX es el estándar J2EE para la gestión de componentes Java. Hibernate se puede administrar por medio de un servicio estándar JMX. Brindamos una implementación de MBean en la distribución: org.hibernate.jmx.HibernateService.

Para ver un ejemplo de cómo desplegar Hibernate como un servicio JMX en un servidor de aplicaciones JBoss, por favor, refiérase al manual del usuario de JBoss. JBoss AS también proporciona estos beneficios si despliega utilizando JMX:

Para más información sobre estas opciones, consulte el Manual de Usuario de JBoss AS.

Another feature available as a JMX service is runtime Hibernate statistics. See Sección 3.4.6, “Estadísticas de Hibernate” for more information.

La mayoría de las aplicaciones que utilizan Hibernate necesitan alguna forma de sesiones "contextuales", en donde una sesión dada se encuentra en efecto en todo el campo de acción de un contexto dado. Sin embargo, a través de las aplicaciones la definición de lo que constituye un contexto es usualmente diferente y diferentes contextos definen diferentes campos de acción para la noción de actual. Las aplicaciones que utiliza Hibernate antes de la version 3.0 tienden a utilizar ya sea sesiones contextuales con base ThreadLocal desarrollados en casa, las clases ayudantes tales como HibernateUtil, o enfoques de terceros utilizados, como Spring o Pico, los cuales brindaban sesiones contextuales con base proxy/intercepción.

Comenzando con la version 3.0.1, Hibernate agregó el método SessionFactory.getCurrentSession(). Inicialmente, este asumió la utilización de las transacciones JTA, en donde la transacción JTA definia tanto el contexto como el campo de acción de una sesión actual. Dada la madurez de númerosas implementaciones JTA TransactionManager autónomas existentes, la mayoría, si no es que todas, las aplicaciones deberían utilizar la administración de transacciones JTA en el caso de que se deplieguen o no en un contenedor J2EE. Con base en esto, las sesiones contextuales basadas en JTA es todo lo que usted necesita utilizar.

Sin embargo, desde la versión 3.1, el procesamiento detrás de SessionFactory.getCurrentSession() ahora es conectable. Para ese fin, se ha añadido una nueva interfaz de extensión, org.hibernate.context.CurrentSessionContext, y un nuevo parámetro de configuración, hibernate.current_session_context_class para permitir la conexión del campo de acción y el contexto de definición de las sesiones actuales.

Refiérase a los Javadocs para la interfaz org.hibernate.context.CurrentSessionContext para poder ver una discusión detallada de su contrato. Define un método único, currentSession(), por medio del cual la implementación es responsable de rastrear la sesión contextual actual. Tal como viene empacada, Hibernate incluye tres implementaciones de esta interfaz:

The first two implementations provide a "one session - one database transaction" programming model. This is also known and used as session-per-request. The beginning and end of a Hibernate session is defined by the duration of a database transaction. If you use programmatic transaction demarcation in plain JSE without JTA, you are advised to use the Hibernate Transaction API to hide the underlying transaction system from your code. If you use JTA, you can utilize the JTA interfaces to demarcate transactions. If you execute in an EJB container that supports CMT, transaction boundaries are defined declaratively and you do not need any transaction or session demarcation operations in your code. Refer to Capítulo 12, Transacciones y concurrencia for more information and code examples.

El parámetro de configuración hibernate.current_session_context_class define cuales implementaciones org.hibernate.context.CurrentSessionContext deben utilizarse. Para compatibilidad con versiones anteriores, si este parámetro de configuración no está establecido pero si tiene configurado un org.hibernate.transaction.TransactionManagerLookup, Hibernate utilizará el org.hibernate.context.JTASessionContext. Usualmente el valor de este parámetro sólamente nombraría la clase de implementación a utilizar. Sin embargo, para las tres implementaciones incluídas existen tress nombres cortos: "jta", "thread" y "managed".

Hibernate está diseñado para operar en muchos entornos diferentes y por lo tanto hay un gran número de parámetros de configuración. Afortunadamente, la mayoría tiene valores predeterminados sensibles y Hibernate se distribuye con un archivo hibernate.properties de ejemplo en etc/ que muestra las diversas opciones. Simplemente ponga el fichero de ejemplo en su ruta de clase y personalícelo de acuerdo a sus necesidades.

Una instancia de org.hibernate.cfg.Configuration representa un conjunto entero de mapeos de los tipos Java de una aplicación a una base de datos SQL. La org.hibernate.cfg.Configuration se utiliza para construir una org.hibernate.SessionFactory inmutable. Los mapeos se compilan desde varios archivos de mapeo XML.

Puede obtener una instancia de org.hibernate.cfg.Configuration instanciándola directamente y especificando los documentos de mapeo XML. Si los archivos de mapeo están en la ruta de clase, utilice addResource(). Por ejemplo:

Configuration cfg = new Configuration()

    .addResource("Item.hbm.xml")
    .addResource("Bid.hbm.xml");

Una manera opcional es especificar la clase mapeada y dejar que Hibernate encuentre el documento de mapeo por usted:

Configuration cfg = new Configuration()

    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class);

Luego Hibernate buscará los archivos de mapeo llamados /org/hibernate/auction/Item.hbm.xml y /org/hibernate/auction/Bid.hbm.xml en la ruta de clase. Este enfoque elimina cualquier nombre de archivo establecido manualmente.

Una org.hibernate.cfg.Configuration también le permite especificar las propiedades de configuración. Por ejemplo:

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");

Esta no es la única manera de pasar propiedades de configuración a Hibernate. Algunas opciones incluyen:

Si quiere empezar rápidamente hibernate.properties es el enfoque más fácil.

La org.hibernate.cfg.Configuration está concebida como un objeto de tiempo de inicio que se va a descartar una vez se crea una SessionFactory.

Se aconseja que la org.hibernate.SessionFactory cree y almacene en pool conexiones JDBC por usted Si adopta este enfoque, el abrir una org.hibernate.Session es tan simple como:

Session session = sessions.openSession(); // open a new Session

En el momento en que inicie una tarea que requiera acceso a la base de datos, se obtendrá una conexión JDBC del pool.

Para que esto funcione, primero necesita pasar algunas las propiedades de conexión JDBC a Hibernate. Todos los nombres de las propiedades de Hibernate y su semántica están definidas en la clase org.hibernate.cfg.Environment. Ahora describiremos las configuraciones más importantes para la conexión JDBC.

Hibernate obtendrá y tendrá en pool las conexiones utilizando java.sql.DriverManager si configura las siguientes propiedades:


Sin embargo, el algoritmo de pooling de la conexión propia de Hibernate es algo rudimentario. Está concebido para ayudarle a comenzar y no para utilizarse en un sistema de producción ni siquiera para pruebas de rendimiento. Para alcanzar un mejor rendimiento y estabilidad debe utilizar un pool de terceros. Sólo remplace la propiedad hibernate.connection.pool_size con configuraciones específicas del pool de conexiones. Esto desactivará el pool interno de Hibernate. Por ejemplo, es posible utilizar C3P0.

C3P0 es un pool de conexiones JDBC de código abierto distribuido junto con Hibernate en el directorio lib. Hibernate utilizará su org.hibernate.connection.C3P0ConnectionProvider para pooling de conexiones si establece propiedades hibernate.c3p0.*. Si quiere utilizar Proxool refiérase a hibernate.properties incluído en el paquete y al sitio web de Hibernate para obtener más información.

Aquí hay un archivo hibernate.properties de ejemplo para c3p0:

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

Para su utilización dentro de un servidor de aplicaciones, casi siempre usted debe configurar Hibernate para obtener conexiones de un javax.sql.Datasource del servidor de aplicaciones registrado en JNDI. Necesitará establecer al menos una de las siguientes propiedades:


He aquí un archivo hibernate.properties de ejemplo para una fuente de datos JNDI provisto por un servidor de aplicaciones:

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

Las conexiones JDBC obtenidas de una fuente de datos JNDI participarán automáticamente en las transacciones del servidor de aplicaciones administradas por el contenedor.

Pueden darse propiedades de conexión arbitrarias anteponiendo "hibernate.connnection" al nombre de propiedad de la conexión. Por ejemplo, puede especificar una propiedad de conexión charSet usando hibernate.connection.charSet.

Puede definir su propia estrategia plugin para obtener conexiones JDBC implementando la interfaz org.hibernate.connection.ConnectionProvider y especificando su propia implementación personalizada por medio de la propiedad hibernate.connection.provider_class.

Hay otras propiedades que controlan el comportamiento de Hibernate en tiempo de ejecución. Todas son opcionales y tienen valores razonables por defecto.

Tabla 3.3. Propiedades de Configuración de Hibernate

Nombre de la propiedadPropósito
hibernate.dialect El nombre de clase de un org.hibernate.dialect.Dialect de Hibernate, el cual le permite que genere un SQL optimizado para una base de datos relacional en particular.

e.g. full.classname.of.Dialect

En la mayoría de los casos Hibernate podrá de hecho seleccionar la implementación org.hibernate.dialect.Dialect correcta con base en los JDBC metadata que el controlador JDBC retorna.

hibernate.show_sql Escribe todas las declaraciones SQL a la consola. Esta es una alternativa para establecer la categoria de registro org.hibernate.SQL a debug.

e.g. true | false

hibernate.format_sql Imprime el SQL en el registro y la consola.

e.g. true | false

hibernate.default_schema Califica los nombres de tabla sin calificar con el esquema/espacio de tabla dado en el SQL generado.

e.g. SCHEMA_NAME

hibernate.default_catalog Califica los nombres de tabla sin calificar con el catálogo dado en el SQL generado.

e.g. CATALOG_NAME

hibernate.session_factory_name Automáticamente se vinculará el org.hibernate.SessionFactory a este nombre en JNDI después de que se ha creado.

e.g. jndi/composite/name

hibernate.max_fetch_depth Establece una "profundidad" máxima del árbol de recuperación por unión externa (outer join) para asociaciones de un sólo extremo (uno-a-uno, muchos-a-uno). Un 0 deshabilita la recuperación por unión externa predeterminada.

ej. los valores recomendados entre 0 y 3

hibernate.default_batch_fetch_size Establece un tamaño por defecto para la recuperación en lote de asociaciones de Hibernate.

ej. valores recomendados 4, 8, 16

hibernate.default_entity_mode Establece un modo predeterminado de representación de entidades para todas las sesiones abiertas desde esta SessionFactory

dynamic-map, dom4j, pojo

hibernate.order_updates Obliga a Hibernate a ordenar las actualizaciones SQL por el valor de la clave principal de los items a actualizar. Esto resultará en menos bloqueos de transacción en sistemas altamente concurrentes.

e.g. true | false

hibernate.generate_statistics De habilitarse, Hibernate colectará estadísticas útiles para la afinación de rendimiento.

e.g. true | false

hibernate.use_identifier_rollback De habilitarse, cuando se borren los objetos las propiedades identificadoras generadas se resetearán a losvalores establecidos por defecto.

e.g. true | false

hibernate.use_sql_comments De activarse, Hibernate generará comentarios dentro del SQL, para una depuración más fácil, por defecto es false.

e.g. true | false


Tabla 3.4. Propiedades de JDBC y Conexiones de Hibernate

Nombre de la propiedadPropósito
hibernate.jdbc.fetch_size Un valor distinto de cero que determina el tamaño de recuperación de JDBC (llama a Statement.setFetchSize()).
hibernate.jdbc.batch_size Un valor distinto de cero habilita que Hibernate utilice las actualizaciones en lote de JDBC2.

ej. valores recomendados entre 5 y 30

hibernate.jdbc.batch_versioned_data Set this property to true if your JDBC driver returns correct row counts from executeBatch(). It is usually safe to turn this option on. Hibernate will then use batched DML for automatically versioned data. Defaults to false.

e.g. true | false

hibernate.jdbc.factory_class Selecciona un org.hibernate.jdbc.Batcher personalizado. La mayoría de las aplicaciones no necesitarán esta propiedad de configuración.

eg. classname.of.BatcherFactory

hibernate.jdbc.use_scrollable_resultset Habilita a Hibernate para utilizar los grupos de resultados deslizables de JDBC2. Esta propiedad sólamente es necesaria cuando se utilizan conexiones JDBC provistas por el usuario. En el caso contrario Hibernate utiliza los metadatos de conexión.

e.g. true | false

hibernate.jdbc.use_streams_for_binary Utiliza flujos (streams) al escribir/leer tipos binary o serializable a/desde JDBC. Propiedad a nivel de sistema

e.g. true | false

hibernate.jdbc.use_get_generated_keys Habilita el uso de PreparedStatement.getGeneratedKeys() de JDBC3 para recuperar claves generadas nativamente después de insertar. Requiere un controlador JDBC3+ y un JRE1.4+. Establézcalo como falso si su controlador tiene problemas con los generadores del identificador de Hibernate. Por defecto, se intenta determinar las capacidades del controlador utilizando los metadatos de conexión.

e.g. true|false

hibernate.connection.provider_class EL nombre de clase de un org.hibernate.connection.ConnectionProvider personalizado que proporcione conexiones JDBC a Hibernate.

e.g. classname.of.ConnectionProvider

hibernate.connection.isolation Establece el nivel de aislamiento de la transacción JDBC. Comprueba java.sql.Connection para valores significativos pero observe que la mayoría de las bases de datos no soportan todos los niveles de aislamiento y algunos definen nivekes de aislamiento adicionales y no estándares.

e.g. 1, 2, 4, 8

hibernate.connection.autocommit Habilita un guardado automático (autocommit) para las conexiones JDBC en pool (no se recomienda).

e.g. true | false

hibernate.connection.release_mode Especifica el momento en que Hibernate debe liberar las conexiones JDBC. Por defecto, una conexión JDBC es retenida hasta que la sesión se cierra o se desconecta explícitamente. Para una fuente de datos JTA del servidor de aplicaciones, debe utilizar after_statement para liberar agresivamente las conexiones después de cada llamada JDBC. Para una conexión no JTA, frecuentemente tiene sentido el liberar la conexión al final de cada transacción, el utilizarafter_transaction. auto escogerá after_statement para las estrategias de transacción JTA y CMT y after_transaction para la estrategia JDBC de transacción.

e.g. auto (default) | on_close | after_transaction | after_statement

This setting only affects Sessions returned from SessionFactory.openSession. For Sessions obtained through SessionFactory.getCurrentSession, the CurrentSessionContext implementation configured for use controls the connection release mode for those Sessions. See Sección 2.5, “Sesiones contextuales”

hibernate.connection.<propertyName> Pasar la propiedad JDBC <propertyName> a DriverManager.getConnection().
hibernate.jndi.<propertyName> Pasar la propiedad <propertyName> al InitialContextFactory JNDI.



Tabla 3.7. Propiedades Misceláneas

Nombre de la propiedadPropósito
hibernate.current_session_context_class Supply a custom strategy for the scoping of the "current" Session. See Sección 2.5, “Sesiones contextuales” for more information about the built-in strategies.

e.g. jta | thread | managed | custom.Class

hibernate.query.factory_class Elige la implementación de análisis sintáctico HQL.

ej. org.hibernate.hql.ast.ASTQueryTranslatorFactory o org.hibernate.hql.classic.ClassicQueryTranslatorFactory

hibernate.query.substitutions Se utiliza para mapear desde tokens en consultas Hibernate a tokens SQL. (por ejemplo, los tokens pueden ser nombres de función o literales).

e.g. hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC

hibernate.hbm2ddl.auto Exporta o valida automáticamente DDL de esquema a la base de datos cuando se crea la SessionFactory. Con create-drop se desechará el esquema de la base de datos cuando la SessionFactory se cierre explícitamente.

e.g. validate | update | create | create-drop

hibernate.bytecode.use_reflection_optimizer

Enables the use of bytecode manipulation instead of runtime reflection. This is a System-level property and cannot be set in hibernate.cfg.xml. Reflection can sometimes be useful when troubleshooting. Hibernate always requires either CGLIB or javassist even if you turn off the optimizer.

e.g. true | false

hibernate.bytecode.provider

Both javassist or cglib can be used as byte manipulation engines; the default is javassist.

e.g. javassist | cglib


Siempre configure la propiedad hibernate.dialect a la subclase correcta org.hibernate.dialect.Dialect para su base de datos. Si especifica un dialecto, Hibernate utilizará valores predeterminados de manera sensible para algunas de las otras propiedades enumeradas anteriormente, ahorrándole el esfuerzo de especificarlas manualmente.


Hibernate utiliza Simple Logging Facade for Java (SLF4J) con el fin de registrar varios eventos del sistema. SLF4J puede direccionar su salida de registro a varios marcos de trabajo de registro (NOP, Simple, log4j versión 1.2, JDK 1.4 logging, JCL o logback) dependiendo de su enlace escogido. Con el fin de configurar el registro necesitará slf4j-api.jar en su ruta de clase junto con el archivo jar para su enlace preferido - slf4j-log4j12.jar en el caso de Log4J. Consulte la documentación SLF4J para obtener mayores detalles. Para usar Log4j también necesitará poner un archivo log4j.properties en su ruta de clase. Un archivo de propiedades de ejemplo se distribuye junto con Hibernate en el directorio src/.

Le recomendamos bastante que se familiarice con los mensajes de registro de Hibernate. Se ha trabajado bastante para hacer que los registros de Hibernate sean tan detallados como sea posible, sin hacerlos ilegibles. Es un dispositivo esencial en la resolución de problemas. Las categorías de registro más interesantes son las siguientes:


Al desarrollar aplicaciones con Hibernate, casi siempre debe trabajar con debug habilitado para la categoría org.hibernate.SQL o, alternativamente, la propiedad hibernate.show_sql habilitada.

Un enfoque alternativo de configuración es especificar una configuración completa en un archivo llamado hibernate.cfg.xml. Este archivo se puede utilizar como un remplazo del archivo hibernate.properties o en el caso de que ambos se encuentren presentes, para sobrescribir propiedades.

El archivo de configuración XML por defecto se espera en la raíz de su CLASSPATH. Este es un ejemplo:


<?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 collection="org.hibernate.auction.Item.bids" usage="read-write"/>

    </session-factory>

</hibernate-configuration
>

La ventaja de este enfoque es la externalización de los nombres de los archivos de mapeo a la configuración. El hibernate.cfg.xml también es más práctico una vez que haya afinado el caché de Hibernate. Puede escoger ya sea hibernate.properties o hibernate.cfg.xml. Ambos son equivalentes, excepto por los beneficios de utilizar la sintaxis XML que mencionados anteriormente.

Con la configuración XML, iniciar Hibernate es tan simple como:

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

Puede seleccionar un fichero de configuración XML diferente utilizando:

SessionFactory sf = new Configuration()

    .configure("catdb.cfg.xml")
    .buildSessionFactory();

Hibernate tiene los siguientes puntos de integración con la infraestructura J2EE:

Dependiendo de su entorno, podría tener que establecer la opción de configuración hibernate.connection.aggressive_release como true si su servidor de aplicaciones muestra excepciones "contención de conexión".

La API de Session de Hibernate es independiente de cualquier demarcación de transacción en su arquitectura. Si deja que Hibernate utilice JDBC directamente, a través de un pool de conexiones, puede comenzar y acabar sus transacciones llamando la API de JDBC. Si ejecuta en un servidor de aplicaciones J2EE, puede que quiera utilizar transacciones administradas por bean y llamar la API de JTA y UserTransaction cuando sea necesario.

Para mantener su código portable entre estos dos (y otros) entornos le recomendamos la API de Transaction de Hibernate, que envuelve y oculta el sistema subyacente. Tiene que especificar una clase fábrica para las instancias de Transaction estableciendo la propiedad de configuración hibernate.transaction.factory_class de Hibernate.

Existen tres opciones estándares o incorporadas:

También puede definir sus propias estrategias de transacción (por ejemplo, para un servicio de transacción CORBA).

Algunas funcionalidades en Hibernate (por ejemplo, el caché de segundo nivel, las sesiones contextuales, etc.) requieren acceso al TransactionManager de JTA en un entorno administrado. En un servidor de aplicaciones tiene que especificar cómo Hibernate debe obtener una referencia al TransactionManager, ya que J2EE no estandariza un sólo mecanismo:


Una SessionFactory de Hibernate vinculada a JNDI puede simplificar la búsqueda de la fábrica y la creación de nuevas Sessiones. Sin embargo, esto no se relaciona con un Datasource vinculado a JNDI; simplemente que ambos utilizan el mismo registro.

Si desea tener la SessionFactory vinculada a un espacio de nombres de JNDI, especifique un nombre (por ejemplo, java:hibernate/SessionFactory) utilizando la propiedad hibernate.session_factory_name. Si se omite esta propiedad, la SessionFactory no será vinculada a JNDI. Esto es particularmente útil en entornos con una implementación JNDI de sólo lectura por defecto (por ejemplo, en Tomcat).

Al vincular la SessionFactory a JNDI, Hibernate utilizará los valores de hibernate.jndi.url, hibernate.jndi.class para instanciar un contexto inicial. Si éstos no se especifican, se utilizará el InitialContext por defecto.

Hibernate colocará automáticamente la SessionFactory en JNDI después de que llame a cfg.buildSessionFactory(). Esto significa que tendrá al menos esta llamada en algún código de inicio o clase de utilidad en su aplicación, a menos de que utilice el despliegue JMX con el HibernateService (esto se discute más adelante en mayor detalle).

Si utiliza una SessionFactory JNDI, un EJB or cualquier otra clase puede llegar a obtener el SessionFactory utilizando una búsqueda JNDI.

Le recomendamos que vincule el SessionFactory a JNDI en un entorno administrado y que de otra manera, use un singleton static. Para proteger su código de aplicación de estos detalles, también le recomendamos que esconda el código de búsqueda real para una SessionFactory en una clase de ayuda como HibernateUtil.getSessionFactory(). Note que dicha clase también es una manera práctica de iniciar Hibernate— vea el capítulo 1.

The easiest way to handle Sessions and transactions is Hibernate's automatic "current" Session management. For a discussion of contextual sessions see Sección 2.5, “Sesiones contextuales”. Using the "jta" session context, if there is no Hibernate Session associated with the current JTA transaction, one will be started and associated with that JTA transaction the first time you call sessionFactory.getCurrentSession(). The Sessions retrieved via getCurrentSession() in the "jta" context are set to automatically flush before the transaction completes, close after the transaction completes, and aggressively release JDBC connections after each statement. This allows the Sessions to be managed by the life cycle of the JTA transaction to which it is associated, keeping user code clean of such management concerns. Your code can either use JTA programmatically through UserTransaction, or (recommended for portable code) use the Hibernate Transaction API to set transaction boundaries. If you run in an EJB container, declarative transaction demarcation with CMT is preferred.

La línea cfg.buildSessionFactory() todavía se tiene que ejecutar en algún sitio para obtener una SessionFactory en JNDI. Puede hacer esto ya sea en un bloque inicializador static (como aquel en HibernateUtil) o bien puede desplegar Hibernate como un servicio administrado.

Hibernate se distribuye con org.hibernate.jmx.HibernateService para desplegar en un servidor de aplicaciones con capacidades JMX, como JBoss AS. El despliegue y la configuracón reales son específicos del vendedor. He aquí un ejemplo de jboss-service.xml para JBoss 4.0.x:


<?xml version="1.0"?>
<server>

<mbean code="org.hibernate.jmx.HibernateService"
    name="jboss.jca:service=HibernateFactory,name=HibernateFactory">

    <!-- Required services -->
    <depends
>jboss.jca:service=RARDeployer</depends>
    <depends
>jboss.jca:service=LocalTxCM,name=HsqlDS</depends>

    <!-- Bind the Hibernate service to JNDI -->
    <attribute name="JndiName"
>java:/hibernate/SessionFactory</attribute>

    <!-- Datasource settings -->
    <attribute name="Datasource"
>java:HsqlDS</attribute>
    <attribute name="Dialect"
>org.hibernate.dialect.HSQLDialect</attribute>

    <!-- Transaction integration -->
    <attribute name="TransactionStrategy">
        org.hibernate.transaction.JTATransactionFactory</attribute>
    <attribute name="TransactionManagerLookupStrategy">
        org.hibernate.transaction.JBossTransactionManagerLookup</attribute>
    <attribute name="FlushBeforeCompletionEnabled"
>true</attribute>
    <attribute name="AutoCloseSessionEnabled"
>true</attribute>

    <!-- Fetching options -->
    <attribute name="MaximumFetchDepth"
>5</attribute>

    <!-- Second-level caching -->
    <attribute name="SecondLevelCacheEnabled"
>true</attribute>
    <attribute name="CacheProviderClass"
>org.hibernate.cache.EhCacheProvider</attribute>
    <attribute name="QueryCacheEnabled"
>true</attribute>

    <!-- Logging -->
    <attribute name="ShowSqlEnabled"
>true</attribute>

    <!-- Mapping files -->
    <attribute name="MapResources"
>auction/Item.hbm.xml,auction/Category.hbm.xml</attribute>

</mbean>

</server
>

Este archivo se implementa en un directorio llamado META-INF y se encuentra empacado en un archivo JAR con la extensión .sar (archivo de servicio). También necesita empacar Hibernate, sus bibliotecas de terceros requeridas, sus clases persistentes compiladas, así como sus archivos de mapeo en el mismo archivo. Sus beans empresariales (usualmente beans de sesión) se pueden dejar en su propio archivo JAR, pero puede incluir este archivo EJB JAR en el archivo de servicio principal para obtener una unidad desplegable en vivo (sin apagarlo). Consulte la documentación de JBoss AS para obtener más información sobre el servicio JMX y la implementación de EJB.

Las clases presistentes son clases en una aplicación que implementan las entidades del problema empresarial (por ejemplo, Customer y Order en una aplicación de comercio electrónico). No se considera que todas las instancias de una clase persistente estén en estado persistente. Por ejemplo, una instancia puede ser transitoria o separada.

Hibernate funciona mejor si estas clases siguen algunas reglas simples, también conocidas como el modelo de programación POJO (Plain Old Java Object). Sin embargo, ninguna de estas reglas son requerimientos rígidos. De hecho, Hibernate3 asume muy poco acerca de la naturaleza de sus objetos persistentes. Puede expresar un modelo de dominio en otras formas (por ejemplo, utilizando árboles de instancias de Map).

La mayoría de aplicaciones Java requieren una clase persistente que represente a los felinos. Por ejemplo:

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

En las siguientes secciones vamos a explorar en mayor detalle las cuatro reglas principales de las clases persistentes.

Tiene que sobrescribir los métodos equals() y hashCode() si:

Hibernate garantiza la equivalencia de identidad persistente (fila de base de datos) y de identidad Java sólamente dentro del ámbito de una sesión en particular. De modo que en el momento en que mezcla instancias recuperadas en sesiones diferentes, tiene que implementar equals() y hashCode() si desea tener una semántica significativa para Sets.

La forma más obvia es implementar equals()/hashCode() comparando el valor identificador de ambos objetos. Si el valor es el mismo, ambos deben ser la misma fila de la base de datos ya que son iguales. Si ambos son agregados a un Set, sólo tendremos un elemento en el Set). Desafortunadamente, no puede utilizar este enfoque con identificadores generados. Hibernate sólo asignará valores identificadores a objetos que son persistentes; una instancia recién creada no tendrá ningún valor identificador. Además, si una instancia no se encuentra guardada y está actualmente en un Set, al guardarla se asignará un valor identificador al objeto. Si equals() y hashCode() están basados en el valor identificador, el código hash podría cambiar, rompiendo el contrato del Set. Consulte el sitio web de Hibernate y allí encontrará una discusión completa sobre este problema. Este no es un problema de Hibernate, sino de la semántica normal de Java de identidad de objeto e igualdad.

Le recomendamos implementar equals() y hashCode() utilizando igualdad de clave empresarial (Business key equality). Igualdad de clave empresarial significa que el método equals() sólamente compara las propiedades que forman la clave empresarial. Esta es una clave que podría identificar nuestra instancia en el mundo real (una clave candidata 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;
    }
}

A business key does not have to be as solid as a database primary key candidate (see Sección 12.1.3, “Consideración de la identidad del objeto”). Immutable or unique properties are usually good candidates for a business key.

Las entidades persistentes no necesariamente tienen que estar representadas como clases POJO o como objetos JavaBean en tiempo de ejecución. Hibernate también soporta modelos dinámicos (utilizando Mapeos de Mapeos en tiempo de ejecución) y la representación de entidades como árboles de DOM4J. No escriba clases persistentes con este enfoque, sólamente archivos de mapeo.

By default, Hibernate works in normal POJO mode. You can set a default entity representation mode for a particular SessionFactory using the default_entity_mode configuration option (see Tabla 3.3, “Propiedades de Configuración de Hibernate”).

Los siguientes ejemplos demuestran la representación utilizando Mapeos. Primero, en el archivo de mapeo tiene que declararse un entity-name en lugar de, o además de un nombre de clase:


<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
>

Aunque las asociaciones se declaran utilizando nombres de clase destino, el tipo destino de una asociación puede ser además una entidad dinámica en lugar de un POJO.

Después de establecer el modo de entidad predeterminado como dynamic-map para la SessionFactory, puede trabajar en tiempo de ejecución con Mapeos de Mapeos:

Session s = openSession();

Transaction tx = s.beginTransaction();
// Create a customer
Map david = new HashMap();
david.put("name", "David");
// Create an organization
Map foobar = new HashMap();
foobar.put("name", "Foobar Inc.");
// Link both
david.put("organization", foobar);
// Save both
s.save("Customer", david);
s.save("Organization", foobar);
tx.commit();
s.close();

Una de las ventajas principales de un mapeo dinámico es el rápido tiempo de entrega del prototipado sin la necesidad de implementar clases de entidad. Sin embargo, pierde el chequeo de tipos en tiempo de compilación y muy probablemente tendrá que tratar con muchas excepciones en tiempo de ejecución. Gracias al mapeo de Hibernate, el esquema de base de datos se puede normalizar y volver sólido, permitiendo añadir una implementación apropiada del modelo de dominio más adelante.

Los modos de representación de entidad se pueden establecer por Session:

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


// Create a customer
Map david = new HashMap();
david.put("name", "David");
dynamicSession.save("Customer", david);
...
dynamicSession.flush();
dynamicSession.close()
...
// Continue on pojoSession

Tenga en cuenta que la llamada a getSession() utilizando un EntityMode está en la API de Session, no en la de SessionFactory. De esta forma, la nueva Session comparte la conexión JDBC, la transacción y otra información de contexto. Esto significa que no tiene que llamar a flush() ni a close() en la Session secundaria, y también tiene que dejar el manejo de la transacción y de la conexión a la unidad de trabajo primaria.

More information about the XML representation capabilities can be found in Capítulo 19, Mapeo XML.

org.hibernate.tuple.Tuplizer y sus subinterfaces son las responsables de administrar una representación en particular de un dato, dadas las representaciones de org.hibernate.EntityMode. Si un dato dado se considera como una estructura de datos entonces un tuplizer es la cosa que sabe como crear tal estructura de datos y sabe como extraer e insertar valores en dicha estructura de datos. Por ejemplo, para el modo de entidad POJO, el tuplizer correspondiente sabe como crear el POJO por medio de su constructor. También sabe como acceder a las propiedades POJO utilizando los accesores de propiedad definidos.

Hay dos tipos altos de niveles de Tuplizers, representados por las interfaces org.hibernate.tuple.entity.EntityTuplizer y org.hibernate.tuple.component.ComponentTuplizer. Los EntityTuplizers son los responsables de administrar los contratos mencionados anteriormente en relación con las entidades mientras que los ComponentTuplizers hacen lo mismo para los componentes.

Los usuarios también pueden enchufar sus propios tuplizers. Tal vez necesite que una implementación java.util.Map diferente de java.util.HashMap se utilice en el modo de entidad de mapeo dinámico. O quizás necesite definir una estrategia de generación proxy diferente de la que se utiliza por defecto. Se pueden obtener ambas al definir una implementación tuplizer personalizada. Las definiciones de los tuplizers se encuentran sujetas a la entidad o componente de mapeo que se supone que tienen que administrar. Regresando al ejemplo de nuestra entidad de cliente:


<hibernate-mapping>
    <class entity-name="Customer">
        <!--
            Override the dynamic-map entity-mode
            tuplizer for the customer entity
        -->
        <tuplizer entity-mode="dynamic-map"
                class="CustomMapTuplizerImpl"/>

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

        <!-- other properties -->
        ...
    </class>
</hibernate-mapping>


public class CustomMapTuplizerImpl
        extends org.hibernate.tuple.entity.DynamicMapEntityTuplizer {
    // override the buildInstantiator() method to plug in our custom map...
    protected final Instantiator buildInstantiator(
            org.hibernate.mapping.PersistentClass mappingInfo) {
        return new CustomMapInstantiator( mappingInfo );
    }

    private static final class CustomMapInstantiator
            extends org.hibernate.tuple.DynamicMapInstantitor {
        // override the generateMap() method to return our custom map...
            protected final Map generateMap() {
                    return new CustomMap();
            }
    }
}

La interfaz org.hibernate.EntityNameResolver es un contrato para resolver el nombre de la entidad de una instancia de entidad dada. La interfaz define un solo método resolveEntityName, el cual se le pasa la instancia entidad y se espera que retorne el nombre de entidad apropriado (se permite nulo e indicaría que el resolvedor no sabe cómo resolver el nombre de la entidad de la instancia de entidad dada). Generalmente hablando, un org.hibernate.EntityNameResolver será más útil en el caso de modelos dinámicos. Un ejemplo puede ser el usar interfaces con proxis como su modelo de dominio. La suite de prueba de hibernate tiene un ejemplo de este estilo exacto de uso bajo el org.hibernate.test.dynamicentity.tuplizer2. Aquí está algo del código de ese paquete para su ilustración.

/**

 * A very trivial JDK Proxy InvocationHandler implementation where we proxy an interface as
 * the domain model and simply store persistent state in an internal Map.  This is an extremely
 * trivial example meant only for illustration.
 */
public final class DataProxyHandler implements InvocationHandler {
        private String entityName;
        private HashMap data = new HashMap();
        public DataProxyHandler(String entityName, Serializable id) {
                this.entityName = entityName;
                data.put( "Id", id );
        }
        public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
                String methodName = method.getName();
                if ( methodName.startsWith( "set" ) ) {
                        String propertyName = methodName.substring( 3 );
                        data.put( propertyName, args[0] );
                }
                else if ( methodName.startsWith( "get" ) ) {
                        String propertyName = methodName.substring( 3 );
                        return data.get( propertyName );
                }
                else if ( "toString".equals( methodName ) ) {
                        return entityName + "#" + data.get( "Id" );
                }
                else if ( "hashCode".equals( methodName ) ) {
                        return new Integer( this.hashCode() );
                }
                return null;
        }
        public String getEntityName() {
                return entityName;
        }
        public HashMap getData() {
                return data;
        }
}
/**
 *
 */
public class ProxyHelper {
    public static String extractEntityName(Object object) {
        // Our custom java.lang.reflect.Proxy instances actually bundle
        // their appropriate entity name, so we simply extract it from there
        // if this represents one of our proxies; otherwise, we return null
        if ( Proxy.isProxyClass( object.getClass() ) ) {
            InvocationHandler handler = Proxy.getInvocationHandler( object );
            if ( DataProxyHandler.class.isAssignableFrom( handler.getClass() ) ) {
                DataProxyHandler myHandler = ( DataProxyHandler ) handler;
                return myHandler.getEntityName();
            }
        }
        return null;
    }
    // various other utility methods ....
}
/**
 * The EntityNameResolver implementation.
 * IMPL NOTE : An EntityNameResolver really defines a strategy for how entity names should be
 * resolved.  Since this particular impl can handle resolution for all of our entities we want to
 * take advantage of the fact that SessionFactoryImpl keeps these in a Set so that we only ever
 * have one instance registered.  Why?  Well, when it comes time to resolve an entity name,
 * Hibernate must iterate over all the registered resolvers.  So keeping that number down
 * helps that process be as speedy as possible.  Hence the equals and hashCode impls
 */
public class MyEntityNameResolver implements EntityNameResolver {
    public static final MyEntityNameResolver INSTANCE = new MyEntityNameResolver();
    public String resolveEntityName(Object entity) {
        return ProxyHelper.extractEntityName( entity );
    }
    public boolean equals(Object obj) {
        return getClass().equals( obj.getClass() );
    }
    public int hashCode() {
        return getClass().hashCode();
    }
}
public class MyEntityTuplizer extends PojoEntityTuplizer {
        public MyEntityTuplizer(EntityMetamodel entityMetamodel, PersistentClass mappedEntity) {
                super( entityMetamodel, mappedEntity );
        }
        public EntityNameResolver[] getEntityNameResolvers() {
                return new EntityNameResolver[] { MyEntityNameResolver.INSTANCE };
        }
    public String determineConcreteSubclassEntityName(Object entityInstance, SessionFactoryImplementor factory) {
        String entityName = ProxyHelper.extractEntityName( entityInstance );
        if ( entityName == null ) {
            entityName = super.determineConcreteSubclassEntityName( entityInstance, factory );
        }
        return entityName;
    }
    ...
}
        

Con el fin de registrar un org.hibernate.EntityNameResolver los usuarios deben:

  1. Implementar un Tuplizer personalizado, implementando el método getEntityNameResolvers.

  2. Registrarlo con el org.hibernate.impl.SessionFactoryImpl (el cual es la clase de implementación para org.hibernate.SessionFactory) usando el método registerEntityNameResolver.

Los mapeos objeto/relacional usualmente se definen en un documento XML. El documento de mapeo está diseñado para que se pueda leer y editar a mano. El lenguaje de mapeo está centrado en Java, lo que significa que los mapeos se construyen alrededor de declaraciones de clases persistentes y no alrededor de declaraciones de tablas.

Observe que, incluso aunque muchos de los usuarios de Hibernate eligen escribir el XML a mano, existe un número de herramientas para generar el documento de mapeo, incluyendo XDoclet, Middlegen y AndroMDA.

Este es un ejemplo de mapeo:


<?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
>

Ahora vamos a discutir el contenido del documento de mapeo. Sólamente describiremos los elementos y atributos del documento que Hibernate utiliza en tiempo de ejecución. El documento de mapeo también comprende algunos atributos y elementos extra opcionales que afectan los esquemas de la base de datos exportados por la herramienta de exportación de esquemas (por ejemplo, el atributo not-null).

Todos los mapeos XML deben declarar el tipo de documento que se muestra. El DTD en sí se puede encontrar en la URL mencionada anteriormente, en el directorio hibernate-x.x.x/src/org/hibernate , o en hibernate3.jar. Hibernate siempre buscará el DTD primero en la ruta de clase. Si el DTD realiza búsquedas utilizando una conexión de Internet, verifique que su declaración DTD frente al contenido de su ruta de clase.

Hibernate tratará primero de resolver los DTDs en su ruta de clase. La manera en que lo hace es registrando una implementación org.xml.sax.EntityResolver personalizada con el SAXReader que utiliza para leer los archivos xml. Este EntityResolver personalizado reconoce dos diferentes espacios de nombre del identificador del sistema.

Este es un ejemplo de la utilización de los espacios de nombre del usuario:


<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC '-//Hibernate/Hibernate Mapping DTD 3.0//EN' 'http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd' [
<!ENTITY version "3.5.6-Final">
<!ENTITY today "September 15, 2010">

    <!ENTITY types SYSTEM "classpath://your/domain/types.xml">


]>


<hibernate-mapping package="your.domain">
    <class name="MyEntity">
        <id name="id" type="my-custom-id-type">
            ...
        </id>
    <class>
    &types;
</hibernate-mapping>

En donde types.xml es un recurso en el paquete your.domain y comprende un typedef personalizado.

Este elemento tiene varios atributos opcionales. Los atributos schema y catalog especifican que las tablas a las que se refiere en este mapeo pertenecen al esquema y/o catálogo mencionado(s). De especificarse, los nombres de tablas serán calificados por el nombre del esquema y del catálogo dados. De omitirse, los nombres de las tablas no serán calificados. El atributo default-cascade especifica qué estilo de cascada se debe asumir para las propiedades y colecciones que no especifican un atributo cascade. Por defecto, el atributo auto-import nos permite utilizar nombres de clase sin calificar en el lenguaje de consulta.

<hibernate-mapping
         schem(1)a="schemaName"
         catal(2)og="catalogName"
         defau(3)lt-cascade="cascade_style"
         defau(4)lt-access="field|property|ClassName"
         defau(5)lt-lazy="true|false"
         auto-(6)import="true|false"
         packa(7)ge="package.name"
 />

1

schema (opcional): El nombre de un esquema de la base de datos.

2

catalog (opcional): El nombre de un catálogo de la base de datos.

3

default-cascade (opcional - por defecto es none): Un estilo de cascada por defecto.

4

default-access (opcional - por defecto es property): La estrategia que Hibernate debe utilizar para acceder a todas las propiedades. Puede ser una implementación personalizada de PropertyAccessor.

5

default-lazy (opcional - por defecto es true): El valor por defecto para los atributos lazy no especificados de mapeos de clase y de colección.

6

auto-import (opcional - por defecto es true): Especifica si podemos utilizar nombres de clases no calificados de clases en este mapeo en el lenguaje de consulta.

7

package (opcional): Especifica un prefijo de paquete que se debe utilizar para los nombres de clase no calificados en el documento de mapeo.

Si tiene dos clases persistentes con el mismo nombre (sin calificar), debe establecer auto-import="false". Se presentará una excepción si usted intenta asignar dos clases al mismo nombre "importado".

El elemento hibernate-mapping le permite anidar varios mapeos <class> persistentes, como se mostró anteriormente. Sin embargo, es una buena práctica (y algunas herramientas esperan) que mapee sólamente una clase persistente, o a una sóla jerarquía de clases, en un archivo de mapeo y nombrarlo como la superclase persistente. Por ejemplo, Cat.hbm.xml, Dog.hbm.xml, o si utiliza herencia, Animal.hbm.xml.

Puede declarar una clase persistente utilizando el elemento class. Por ejemplo:

<class
        name="(1)ClassName"
        table=(2)"tableName"
        discri(3)minator-value="discriminator_value"
        mutabl(4)e="true|false"
        schema(5)="owner"
        catalo(6)g="catalog"
        proxy=(7)"ProxyInterface"
        dynami(8)c-update="true|false"
        dynami(9)c-insert="true|false"
        select(10)-before-update="true|false"
        polymo(11)rphism="implicit|explicit"
        where=(12)"arbitrary sql where condition"
        persis(13)ter="PersisterClass"
        batch-(14)size="N"
        optimi(15)stic-lock="none|version|dirty|all"
        lazy="(16)true|false"
        entity(17)-name="EntityName"
        check=(18)"arbitrary sql check condition"
        rowid=(19)"rowid"
        subsel(20)ect="SQL expression"
        abstra(21)ct="true|false"
        node="element-name"
/>

1

name (opcional): El nombre completamente calificado de la clase Java persistente (o interfaz). Si se omite este atributo, se asume que el mapeo es para una entidad que no es POJO.

2

table (opcional - por defecto es el nombre de la clase no calificado): El nombre de su tabla en la base de datos.

3

discriminator-value (opcional - predeterminado al nombre de la clase): Un valor que distingue subclases individuales, usado para el comportamiento polimórfico. Los valores aceptables incluyen null y not null.

4

mutable (opcional, por defecto es true): Especifica que las instancias de la clase (no) son mutables.

5

schema (opcional): Sobrescribe el nombre del esquema especificado por el elemento raíz <hibernate-mapping>.

6

catalog (opcional): Sobrescribe el nombre del catálogo especificado por el elemento raíz <hibernate-mapping>.

7

proxy (opcional): Especifica una interfaz a utilizar para los proxies de inicialización perezosa. Puede especificar el nombre mismo de la clase.

8

dynamic-update (opcional, por defecto es false): Especifica que el SQL UPDATE debe ser generado en tiempo de ejecución y puede contener sólamente aquellas columnas cuyos valores hayan cambiado.

9

dynamic-insert (opcional, por defecto es false): Especifica que el SQL INSERT debe ser generado en tiempo de ejecución y debe contener sólamente aquellas columnas cuyos valores no son nulos.

10

select-before-update (opcional, por defecto es false): Especifica que Hibernate nunca debe realizar un UPDATE SQL a menos de que se tenga certeza de que realmente se haya modificado un objeto. Sólo cuando un objeto transitorio ha sido asociado con una sesión nueva utilizando update()), Hibernate realizará una SQL SELECT extra para determinar si realmente se necesita un UPDATE.

11

polymorphism (opcional, por defecto es implicit): Determina si se utiliza polimorfismo de consulta implícito o explícito.

12

where (opcional) especifica una condición SQL WHERE arbitraria para utilizarla en la recuperación de objetos de esta clase.

13

persister (opcional): Especifica un ClassPersister personalizado.

14

batch-size (opcional, por defecto es 1) especifica un "tamaño de lote" para buscar instancias de esta clase por identificador.

15

optimistic-lock (opcional, por defecto es version): Determina la estrategia optimista de bloqueo.

(16)

lazy (opcional): La recuperación perezosa se puede deshabilitar por completo al establecer lazy="false".

(17)

entity-name (optional - defaults to the class name): Hibernate3 allows a class to be mapped multiple times, potentially to different tables. It also allows entity mappings that are represented by Maps or XML at the Java level. In these cases, you should provide an explicit arbitrary name for the entity. See Sección 4.4, “Modelos dinámicos” and Capítulo 19, Mapeo XML for more information.

(18)

check (opcional): Una expresión SQL utilizada para generar una restricción check multi-filas para la generación automática de esquemas.

(19)

rowid (opcional): Hibernate puede utilizar los llamados ROWIDs en las bases de datos. Por ejemplo, en Oracle, Hibernate puede utilizar la columna extra rowid para actualizaciones rápidas si usted establece esta opción como rowid. Un ROWID es un detalle de implementación y representa la posición física de la tupla almacenada.

(20)

subselect (opcional): Mapea una entidad inmutable y de sólo lectura a una subselección de base de datos. Es útil si quiere tener una vista en vez de una tabla base. Vea a continuación para obtener más información.

(21)

abstract (opcional): Utilizado para marcar superclases abstractas en las jerarquías <union-subclass>.

Es perfectamente aceptable que la clase persistente mencionada sea una interfaz. Puede declarar clases que implementan esa interfaz utilizando el elemento <subclass>. Puede persistir cualquier clase interna estática. Debe especificar el nombre de la clase utilizando la forma estándar, por ejemplo, e.g.Foo$Bar.

Las clases inmutables, mutable="false", no pueden ser actualizadas o borradas por la aplicación. Esto le permite a Hibernate realizar ciertas optimizaciones menores de rendimiento.

El atributo opcional proxy activa la inicialización perezosa de instancias persistentes de la clase. Hibernate inicialmente retornará proxies CGLIB que implementan la interfaz mencionada. El objeto persistente real será cargado cuando se invoque un método del proxy. Vea "Inicialización de colecciones y proxies" a continuación.

Por polimorfismo implícito se entiende que las instancias de la clase serán devueltas por una consulta que mencione cualquier superclase, o interfaz implementada, o la clase misma; y que las instancias de cualquier subclase de la clase serán retornadas por una petición que nombra a la clase misma. Por polimorfismo explícito se entiende que las instancias de la clase serán devueltas sólo por consultas que mencionen explícitamente la clase. Las consultas que mencionen la clase retornarán sólo instancias de subclases mapeadas dentro de esta declaración <class> como una <subclass> o <joined-subclass>. Para la mayoría de los propósitos el valor por defecto, polymorphism="implicit", resulta apropiado. El polimorfismo explícito es útil cuando dos clases diferentes se encuentran mapeadas a la misma tabla. Esto permite tener una clase "liviana" que contenga un subconjunto de columnas de la tabla.

El atributo persister le permite personalizar la estrategia de persistencia para la clase. Por ejemplo, puede especificar su propia subclase de org.hibernate.persister.EntityPersister, o incluso puede proporcionar una implementación completamente nueva de la interfaz org.hibernate.persister.ClassPersister que implemente, por ejemplo, la persistencia por medio de llamadas a procedimientos almacenados, serialización a archivos planos o LDAP. Para ver un ejemplo simple (de "persistencia" a una Hashtable) consulte org.hibernate.test.CustomPersister.

Los valores de dynamic-update y dynamic-insert no son heredados por las subclases y por lo tanto deben especificarse en los elementos <subclass> o <joined-subclass>. Aunque en algunos casos, estos ajustes pueden incrementar el rendimiento, de hecho en otros casos, podrían disminuirlo.

El uso de select-before-update disminuirá el rendimiento. Es muy útil prevenir que se llame innecesariamente a un disparador de actualización de la base de datos al volver a unir un gráfico de instancias separadas a una Session.

Si activa dynamic-update, usted tendrá la opción de estrategias de bloqueo optimistas:

Le recomendamos mucho que utilice columnas de versión/sello de fecha para el bloqueo optimista con Hibernate. Esta estrategia optimiza el rendimiento y maneja correctamente las modificaciones realizadas a las instancias separadas, (por ejemplo, cuando se utiliza Session.merge()).

Para un mapeo de Hibernate, no hay diferencia entre una vista y una tabla base. Esto es transparente a nivel de base de datos, aunque algunos DBMS no soportan correctamente las vistas, especialmente con las actualizaciones. A veces usted quiere utilizar una vista, pero no puede crear una en la base de datos (por ejemplo, con un esquema heredado). En este caso, usted puede mapear una entidad inmutable de sólo lectura a una expresión de subconsulta SQL dada.


<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
>

Declara las tablas con las cuales se debe sincronizar esta entidad, asegurándose de que el auto-vaciado ocurra correctamente y que las consultas frente a la entidad derivada no devuelvan datos desactualizados. El <subselect> se encuentra disponible tanto como un atributo y como un elemento anidado de mapeo.

Las clases mapeadas tienen que declarar la columna de clave primaria de la tabla de la base de datos. La mayoría de las clases también tendrán una propiedad de estilo Javabeans que tenga el identificador único de una instancia. El elemento <id> define el mapeo de esa propiedad a la columna de clave primaria.

<id
        name="(1)propertyName"
        type="(2)typename"
        column(3)="column_name"
        unsave(4)d-value="null|any|none|undefined|id_value"
        access(5)="field|property|ClassName">
        node="element-name|@attribute-name|element/@attribute|."

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

1

name (opcional): El nombre de la propiedad del identificador. s

2

type (opcional): un nombre que indica el tipo de Hibernate.

3

column (opcional - por defecto es el nombre de la propiedad): El nombre de la columna de la clave principal.

4

unsaved-value (opcional - por defecto es un valor "sensible"): Un valor de la propiedad identificadora que indica que una instancia está recién instanciada (sin guardar), distinguiéndola de las instancias separadas que fueron guardadas o cargadas en una sesión previa.

5

access (opcional - por defecto es property): La estrategia que Hibernate debe utilizar para acceder al valor de la propiedad.

Si se omite el atributo name, se asume que la clase no tiene propiedad identificadora.

El atributo unsaved-value casi nunca se necesita en Hibernate3.

Hay una declaración <composite-id> opcional para permitir acceso a los datos heredados con claves compuestas. Le disuadimos seriamente de su utilización para cualquier otra cosa.

El elemento hijo opcional <generator> nombra una clase Java utilizada para generar identificadores únicos para instancias de la clase persistente. De requerirse algún parámetro para configurar o inicializar la instancia del generador, se pasa utilizando el elemento <param>.


<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
>

Todos los generadores implementan la interfaz org.hibernate.id.IdentifierGenerator. Esta es una interfaz muy simple. Algunas aplicaciones pueden decidir brindar sus propias implementaciones especializadas. Sin embargo, Hibernate provee un rango de implementaciones ya incorporadas. Los nombres de atajo para los generadores incorporados son los siguientes:

increment

genera indentificadores de tipo long, short o int que sólamente son únicos cuando ningún otro proceso está insertando datos en la misma tabla. No lo utilice en un clúster.

identity

soporta columnas de identidad en DB2, MySQL, MS SQL Server, Sybase y HypersonicSQL. El identificador devuelto es de tipo long, short o int.

sequence

usa una secuencia en DB2, PostgreSQL, Oracle, SAP DB, McKoi o un generador en Interbase. El identificador devuelto es de tipo long, short o int.

hilo

utiliza un algoritmo alto/bajo para generar eficientemente identificadores de tipo long, short o int, dada una tabla y columna como fuente de valores altos (por defecto hibernate_unique_key y next_hi respectivamente). El algoritmo alto/bajo genera identificadores que son únicos sólamente para una base de datos particular.

seqhilo

utiliza un algoritmo alto/bajo para generar eficientemente identificadores de tipo long, short o int, dada una secuencia de base de datos.

uuid

utiliza un algoritmo UUID de 128 bits para generar identificadores de tipo cadena, únicos dentro de una red (se utiliza la direccón IP). El UUID se codifica como una cadena hexadecimal de 32 dígitos de largo.

guid

utiliza una cadena GUID generada por base de datos en MS SQL Server y MySQL.

native

selecciona identity, sequence o hilo dependiendo de las capacidades de la base de datos subyacente.

assigned

deja a la aplicación asignar un identificador al objeto antes de que se llame a save(). Esta es la estrategia por defecto si no se especifica un elemento <generator>.

select

recupera una clave principal asignada por un disparador de base de datos seleccionando la fila por alguna clave única y recuperando el valor de la clave principal.

foreign

utiliza el identificador de otro objeto asociado. Generalmente se usa en conjunto cón a una asociación de clave principal <one-to-one>.

sequence-identity

una estrategia de generación de secuencias especilizadas que utiliza una secuencia de base de datos para el valor real de la generación, pero combina esto junto con JDBC3 getGeneratedKeys para devolver el valor del identificador generado como parte de la ejecución de la declaración de inserción. Esta estrategia está soportada sólamente en los controladores 10g de Oracle destinados para JDK1.4. Los comentarios en estas declaraciones de inserción están desactivados debido a un error en los controladores de Oracle.

Desde el lanzamiento 3.2.3, hay 2 nuevos generadores, los cuales representan una nueva reflexión sobre dos aspectos diferentes de la generación del identificador. El primer aspecto es qúe tan portátil es la base de datos; el segudno es la optimización. La optimización significa que no tiene que preguntarle a la base de datos por toda petición de un nuevo valor identificador. Estos dos nuevos generadores tienen el propósito de tomar el lugar de algunos de los generadores nombrados que describimos anteriormente, empezando por 3.3.x. Sin embargo, están incluídos en los lanzamientos actuales y puede ser referenciados por FQN.

El primero de estos nuevos generadores es org.hibernate.id.enhanced.SequenceStyleGenerator, el cual tiene el propósito, primero, de ser el reemplazo para el generador sequence y segundo, de ser un generador de portabilidad mejor que native. Esto se debe a que native generalmente escoge entre identity y sequence, los cuales tienen una gran diferencia semántica que puede crear problemas sutiles en las aplicaciones mirando la portabilidad. Sin embargo, org.hibernate.id.enhanced.SequenceStyleGenerator, logra la portabilidad de una manera diferente. Escoge entre una tabla o una secuencia en la base de datos para almacenar sus valores en subida, dependiendo de las capacidades del dialecto que se está utilizando. La diferencia enter esto y native es que el almacenamiento basado en tablas y secuencias tienen la misma semántica. De hecho, las secuencias son exactamente lo que Hibernate trata de emular con sus generadores basados en tablas. Este generador tiene un número de parámetros de configuración:

El segundo de estos nuevos generadores es org.hibernate.id.enhanced.TableGenerator, el cual tiene el propósito, primero, de reemplazar el generador table, auqnue de hecho funciona como org.hibernate.id.MultipleHiLoPerTableGenerator, y segundo, como una re-implementación de org.hibernate.id.MultipleHiLoPerTableGenerator que utiliza la noción de los optimizadores enchufables. Esencialmente, este generador define una tabla capaz de mantener un número de valores de incremento diferentes de manera simultánea usando múltiples filas tecleadas claramente. Este generador tiene un número de parámetros de configuración:

  • table_name (opcional - por defecto es hibernate_sequences): el nombre de la tabla a utilizar.

  • value_column_name (opcional - por defecto es next_val): el nombre de la columna en la tabla que se utiliza para mantener el valor.

  • segment_column_name (opcional - por defecto es sequence_name): el nombre de la columna en la tabla que se utiliza para mantener la "llave segmento". Este es el valor que identifica que valor de incremento utilizar.

  • segment_value (opcional - por defecto es default): El valor "llave segmento" para el segmento desde el cual queremos sacar los valores de incremento para este generador.

  • segment_value_length (opcional - por defecto es 255): Se utiliza para la generación de esquemas; el tamaño de la columna a crear esta columna de llave de segmento.

  • initial_value (opcional - por defecto es 1): El valor inicial a recuperar de la tabla.

  • increment_size (opcional - por defecto es 1): El valor por el cual deben diferir las llamadas subsecuentes a la tabla.

  • optimizer (optional - defaults to ): See Sección 5.1.6, “Optimización del generador del identificador”

For identifier generators that store values in the database, it is inefficient for them to hit the database on each and every call to generate a new identifier value. Instead, you can group a bunch of them in memory and only hit the database when you have exhausted your in-memory value group. This is the role of the pluggable optimizers. Currently only the two enhanced generators (Sección 5.1.5, “Generadores mejorados del identificador” support this operation.

  • none (generalmente este el es valor predeterminado si no se especifica un optimizador): esto no realizará ninguna optimización y accederá a la base de datos para toda petición.

  • hilo: aplica un algoritmo hi/lo a los valores recuperados de la base de datos. Se espera que los valores de la base de datos para este optimizador sean secuenciales. Los valores recuperados de la estructura de la base de datos para este optimizador indican el "número del grupo". El increment_size se multiplica por ese valor en la memoria para definir un grupo "hi value".

  • pooled: como en el caso de hilo, este optimizador trata de minimizar el número de hits a la base de datos. Sin embargo, aquí simplemente almacenamos el valor inicial para el "siguiente grupo" en la estructura de la base de datos en lugar de un valor secuencial en combinación con un algoritmo de agrupamiento en-memoria. Aquí, increment_size ser refiere a los valores que provienen de la base de datos.


<composite-id
        name="propertyName"
        class="ClassName"
        mapped="true|false"
        access="field|property|ClassName">
        node="element-name|."

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

Una tabla con clave compuesta se puede mapear con múltiples propiedades de la clase como propiedades identificadoras. El elemento <composite-id> acepta los mapeos de propiedad <key-property> y los mapeos <key-many-to-one> como elementos hijos.


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

La clase persistente tiene que sobrescribir equals() y hashCode() para implementar la igualdad del identificador compuesto. También tiene que implementar Serializable.

Desafortunadamente, este enfoque significa que un objeto persistente es su propio identificador. No existe otra "asa" conveniente más que el objeto mismo. Debe instanciar una instancia de la clase persistente y poblar sus propiedades identificadoras antes de que pueda load() el estado persistente asociado a una clave compuesta. Este enfoque lo denominamos un identificador compuesto incluído y no lo recomendamos para aplicaciones serias.

Un segundo enfoque es lo que denominamos un identificador compuesto mapeado, en donde las propiedades del identificador nombradas dentro del elemento <composite-id> son duplicadas tanto en la clase persistente como en la clase identificadora separada.


<composite-id class="MedicareId" mapped="true">
        <key-property name="medicareNumber"/>
        <key-property name="dependent"/>
</composite-id
>

En este ejemplo, tanto la clase identificadora compuesta MedicareId como la clase de entidad misma tienen propiedades denominadas medicareNumber y dependent. La clase identificadora tiene que sobrescribir equals() y hashCode() e implementar Serializable. La desventaja principal de este enfoque es la duplicación de código.

Los siguientes atributos se utilizan para especificar un identificador compuesto mapeado:

We will describe a third, even more convenient approach, where the composite identifier is implemented as a component class in Sección 8.4, “Componentes como identificadores compuestos”. The attributes described below apply only to this alternative approach:

  • name (opcional, se necesita para este enfoque): Una propiedad de tipo componente que tiene el identificador compuesto. Consulte el capítulo 9 para obtener mayor información.

  • access (opcional - por defecto es property): La estrategia que Hibernate utiliza para acceder al valor de la propiedad.

  • class (opcional - por defecto es el tipo de propiedad determinado por la reflección): la clase componente utilizada como un identificador compuesto. Vea la siguiente sección para obtener mayor información.

Este tercer enfoque, un componente identificador es el que recomendamos para casi todas las aplicaciones.

Se necesita el elemento <discriminator> para la persistencia polimórfica utilizando la estrategia de mapeo de tabla-por-jerarquía-de-clases. Declara una columna discriminadora de la tabla. La columna discriminidora contiene valores de marca que le dicen a la capa de persistencia qué subclase instanciar para una fila en particular. Se puede utilizar un conjunto restringido de tipos: string, character, integer, byte, short, boolean, yes_no, true_false.

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

1

column (opcional - por defecto es class) el nombre de la columna discriminadora.

2

type (opcional - por defecto es string) un nombre que indica el tipo Hibernate.

3

force (opcional - por defecto es false) "fuerza" a Hibernate para especificar los valores discriminadores permitidos incluso cuando se recuperan todas las instancias de la clase raíz.

4

insert (opcional - por defecto es true): establecido como false si su columna discriminadora también es parte de un identificador mapeado compuesto. Lle dice a Hibernate que no incluya la columna en los SQLs INSERT.

5

formula (opcional): una expresión SQL arbitraria que se ejecuta cuando se tenga que evaluar un tipo. Permite la discriminación con base en el contenido.

Los valores reales de la columna discriminadora están especificados por el atributo discriminator-value de los elementos <class> y <subclass>.

El atributo force es sólamente útil si la tabla contiene filas con valores discriminadores "extra" que no estén mapeados a una clase persistente. Generalmente este no es el caso.

El atributo formula le permite declarar una expresión SQL arbitraria que será utilizada para evaluar el tipo de una fila. Por ejemplo:


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

El elemento <version> es opcional e indica que la tabla contiene datos versionados. Esto es particularmente útil si planea utilizar transacciones largas. Vea a continuación para obtener mayor información:

<version
        column(1)="version_column"
        name="(2)propertyName"
        type="(3)typename"
        access(4)="field|property|ClassName"
        unsave(5)d-value="null|negative|undefined"
        genera(6)ted="never|always"
        insert(7)="true|false"
        node="element-name|@attribute-name|element/@attribute|."
/>

1

column (opcional - por defecto es el nombre de la propiedad): El nombre de la columna que tiene el número de la versión.

2

name: El nombre de una propiedad de la clase persistente.

3

type (opcional - por defecto es integer): El tipo del número de la versión.

4

access (opcional - por defecto es property): La estrategia que Hibernate utiliza para acceder al valor de la propiedad.

5

unsaved-value (opcional - por defecto es undefined): Un valor de la propiedad de versión que indica que una instancia se encuentra recién instanciada (sin guardar), distinguiéndola de las instancias separadas que se guardaron o se cargaron en una sesión previa. undefined especifica que se debe utilizar el valor de la propiedad identificadora.

6

generated (opcional - por defecto es never): Especifica que este valor de la propiedad de la versión es generado por la base de datos. Vea la discusión de las propiedades generadas para obtener mayor información.

7

insert (opcional - por defectos es true): Especifica si la columna de la versión debe incluirse en las declaraciones de inserción SQL. Se puede configurar como false si la columna de la base de datos se define con un valor predeterminado de 0.

Los números de versión pueden ser de tipo Hibernate long, integer, short, timestamp o calendar.

Una propiedad de versión o de sello de fecha nunca debe ser nula para una instancia separada. Hibernate detectará cualquier instancia con una versión o sello de fecha nulo como transitoria, sin importar qué otras estrategias unsaved-value se hayan especificado. El declarar una propiedad de versión o sello de fecha nulable es una forma fácil de evitar cualquier problema con la re-unión transitiva en Hibernate. Es especialmente útil para la gente que utiliza identificadores asignados o claves compuestas.

El elemento opcional <timestamp> indica que la tabla contiene datos con sellos de fecha. Esto brinda una alternativa al versionado. Los sellos de tiempo (timestamps) son por naturaleza una implementación menos segura del bloqueo optimista. Sin embargo, a veces la aplicación puede usar los sellos de fecha de otras maneras.

<timestamp
        column(1)="timestamp_column"
        name="(2)propertyName"
        access(3)="field|property|ClassName"
        unsave(4)d-value="null|undefined"
        source(5)="vm|db"
        genera(6)ted="never|always"
        node="element-name|@attribute-name|element/@attribute|."
/>

1

column (opcional - por defecto es el nombre de la propiedad): El nombre de una columna que tiene el sello de fecha.

2

name: El nombre de una propiedad del estilo JavaBeans de tipo Java Date o Timestamp de la clase persistente.

3

access (opcional - por defecto es property): La estrategia que Hibernate utiliza para acceder al valor de la propiedad.

4

unsaved-value (opcional - por defecto es null): Un valor de propiedad de versión que indica que una instancia está recién instanciada (sin guardar), distinguiéndola de instancias separadas que hayan sido guardadas o cargadas en una sesión previa. Undefined especifica que debe utilizarse el valor de la propiedad identificadora.

5

source (opcional - por defecto es vm): ¿Desde dónde debe recuperar Hibernate el valor del sello de fecha? ¿Desde la base de datos o desde la MVJ actual? Los sellos de fecha con base en la base de datos provocan un gasto general debido a que Hibernate tiene que llegar hasta la base de datos para poder determinar el "siguiente valor". Es más seguro utilizarlo en entornos con clústers. No todos los Dialects soportan la recuperación del sello de fecha actual de la base de datos. Los otros pueden ser poco seguros para utilizarlos como bloqueo debido a la falta de precisión (por ejemplo, Oracle 8).

6

generated (opcional - por defecto es never): Especifica que este valor de la propiedad del sello de fecha en realidad es generado por la base de datos. Consulte la discusión de las propiedades generadas para obtener mayor información.

El elemento <property> declara una propiedad persistente estilo JavaBean de la clase.

<property
        name="(1)propertyName"
        column(2)="column_name"
        type="(3)typename"
        update(4)="true|false"
        insert(4)="true|false"
        formul(5)a="arbitrary SQL expression"
        access(6)="field|property|ClassName"
        lazy="(7)true|false"
        unique(8)="true|false"
        not-nu(9)ll="true|false"
        optimi(10)stic-lock="true|false"
        genera(11)ted="never|insert|always"
        node="element-name|@attribute-name|element/@attribute|."
        index="index_name"
        unique_key="unique_key_id"
        length="L"
        precision="P"
        scale="S"
/>

1

name: el nombre de la propiedad, con la letra inicial en minúscula.

2

column (opcional - por defecto es el nombre de la propiedad): El nombre de la columna de la tabla de base de datos mapeada. Esto se puede especificar también con los elemento(s) anidado(s) <column>.

3

type (opcional): un nombre que indica el tipo de Hibernate.

4

update, insert (opcional - por defecto es true): Especifica que las columnas mapeadas deben ser incluídas en las declaraciones SQL UPDATE y/o INSERT . Especificando ambas como false permite una propiedad "derivada", cuyo valor se inicia desde alguna otra propiedad que mapee a la misma columna (o columnas) o por un disparador u otra aplicación.

5

formula (opcional): una expresión SQL que define el valor para una propiedad computada. Las propiedades computadas no tienen una columna mapeada propia.

6

access (opcional - por defecto es property): La estrategia que Hibernate utiliza para acceder al valor de la propiedad.

7

lazy (opcional - por defecto es false): Especifica que se debe recuperar perezosamente esta propiedad cuando se acceda por primera vez la variable de instancia. Requiere instrumentación de código byte en tiempo de compilación.

8

unique (opcional): Activa la generación DDL de una restricción de unicidad para las columnas. Además, permite que ésta sea el objetivo de una property-ref.

9

not-null (opcional): Activa la generación DDL de una restricción de nulabilidad para las columnas.

10

optimistic-lock (opcional - por defecto es true): Especifica que las actualizaciones a esta propiedad requieren o no de la obtención de un bloqueo optimista. En otras palabras, determina si debe ocurrir un incremento de versión cuando la propiedad se encuentre desactualizada.

11

generated (opcional - por defecto es never): Especifica que este valor de la propiedad es de hecho generado por la base de datos. Consulte discusión sobre las propiedades generadas para obtener mayor información.

escribanombre puede ser:

Si no especifica un tipo, Hibernate utilizará reflección sobre la propiedad mencionada para deducir el tipo Hibernate correcto. Hibernate intentará interpretar el nombre de la clase de retorno del getter de la propiedad utilizando las reglas 2, 3 y 4 en ese mismo orden. En algunos casos necesitará el atributo type. Por ejemplo, para distinguir entre Hibernate.DATE y Hibernate.TIMESTAMP, o especificar un tipo personalizado.

El atributo access le permite controlar el cómo Hibernate accederá a la propiedad en tiempo de ejecución. Por defecto, Hibernate llamará al par de getter/setter de la propiedad. Si usted especifica access="field", Hibernate se saltará el par get/set y accederá al campo directamente utilizando reflección. Puede especificar su propia estrategia de acceso a la propiedad mencionando una clase que implemente la interfaz org.hibernate.property.PropertyAccessor.

Una funcionalidad especialmente poderosa son las propiedades derivadas. Estas propiedades son, por definición, de sólo lectura. El valor de la propiedad se computa en tiempo de carga. Usted declara la computación como una expresión SQL y ésta se traduce como una cláusula de subconsulta SELECT en la consulta SQL que carga una instancia:



<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 )"/>

Puede referenciar la tabla de las entidades sin declarar un alias o una columna particular. En el ejemplo dado sería customerId. También puede utilizar el elemento anidado de mapeo <formula> si no quiere utilizar el atributo.

Una asociación ordinaria a otra clase persistente se declara utilizando el elemento many-to-one. El modelo relacional es una asociación muchos-a-uno; una clave foránea en una tabla referencia la columna (o columnas) de la clave principal de la tabla destino.

<many-to-one
        name="(1)propertyName"
        column(2)="column_name"
        class=(3)"ClassName"
        cascad(4)e="cascade_style"
        fetch=(5)"join|select"
        update(6)="true|false"
        insert(6)="true|false"
        proper(7)ty-ref="propertyNameFromAssociatedClass"
        access(8)="field|property|ClassName"
        unique(9)="true|false"
        not-nu(10)ll="true|false"
        optimi(11)stic-lock="true|false"
        lazy="(12)proxy|no-proxy|false"
        not-fo(13)und="ignore|exception"
        entity(14)-name="EntityName"
        formul(15)a="arbitrary SQL expression"
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        index="index_name"
        unique_key="unique_key_id"
        foreign-key="foreign_key_name"
/>

1

name: El nombre de la propiedad.

2

column (opcional): El nombre de la columna de la clave foránea. Esto también se puede especificar por medio de uno o varios elementos anidados <column>.

3

class (opcional - por defecto es el tipo de la propiedad determinado por reflección): El nombre de la clase asociada.

4

cascade (opcional) especifica qué operaciones deben ir en cascada desde el objeto padre hasta el objeto asociado.

5

fetch (opcional - por defecto es select): Escoge entre la recuperación de unión exterior (outer-join) o la recuperación por selección secuencial.

6

update, insert (opcional - por defecto es true) especifica que las columnas mapeadas deben ser incluídas en las declaraciones SQL UPDATE y/o INSERT. El establecer ambas como false permite una asociación puramente "derivada" cuyo valor es inicializado desde alguna otra propiedad que mapea a la misma columna (o columnas), por un disparador o por otra aplicación.

7

property-ref: (opcional): El nombre de una propiedad de la clase asociada que se encuentra unida a su llave foránea. Si no se especifica, se utiliza la llave principal de la clase asociada.

8

access (opcional - por defecto es property): La estrategia que Hibernate utiliza para acceder al valor de la propiedad.

9

unique (opcional): Activa la generación DDL de una restricción de unicidad para la columna de clave foránea. Además, permite que éste sea el objetivo de una property-ref. puede hacer que la asociación sea de multiplicidad uno-a-uno.

10

not-null (opcional): Activa la generación DDL de una restricción de nulabilidad para las columnas de clave foránea.

11

optimistic-lock (opcional - por defecto es true): Especifica que las actualizaciones a esta propiedad requieren o no de la obtención de un bloqueo optimista. En otras palabras, determina si debe ocurrir un incremento de versión cuando la propiedad se encuentre desactualizada.

12

lazy (opcional - por defecto es proxy): Por defecto, las asociaciones de punto único van con proxies. lazy="no-proxy" especifica que esta propiedad debe ser recuperada perezosamente cuando se acceda por primera vez a la variable de instancia. Requiere instrumentación del código byte en tiempo de compilación. lazy="false" especifica que la asociación siempre será recuperada tempranamente.

13

not-found (opcional - por defecto es exception): Especifica cómo se manejarán las claves foráneas que referencian las filas que hacen falta. ignore tratará una fila perdida como una asociación nula.

14

entity-name (opcional): El nombre de entidad de la clase asociada.

15

formula (opcional): una expresión SQL que define el valor para una clave foránea computada.

Setting a value of the cascade attribute to any meaningful value other than none will propagate certain operations to the associated object. The meaningful values are divided into three categories. First, basic operations, which include: persist, merge, delete, save-update, evict, replicate, lock and refresh; second, special values: delete-orphan; and third, all comma-separated combinations of operation names: cascade="persist,merge,evict" or cascade="all,delete-orphan". See Sección 10.11, “Persistencia transitiva” for a full explanation. Note that single valued, many-to-one and one-to-one, associations do not support orphan delete.

Este es un ejemplo de una declaración típica muchos-a-uno:


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

El atributo property-ref se debe utilizar sólamente para el mapeo de datos heredados donde una clave foránea referencia una clave única de la tabla asociada, distinta de la clave principal. Este es un modelo relacional complicado y confuso. Por ejemplo, si la clase Product tuviera un número único serial que no es la clave principal, el atributo unique controla la generación de DDL de Hibernate con la herramienta SchemaExport.


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

Entonces el mapeo para OrderItem puede utilizar:


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

Sin embargo, esto ciertamente no se aconseja.

Si la clave única referenciada abarca múltiples propiedades de la entidad asociada, debe mapear las propiedades dentro de un elemento nombrado <properties>.

Si la clave única referenciada es propiedad de un componente, usted puede especificar una ruta de propiedad:


<many-to-one name="owner" property-ref="identity.ssn" column="OWNER_SSN"/>

Una asociación uno-a-uno (one-to-one) a otra clase persistente se declara utilizando un elemento one-to-one.

<one-to-one
        name="(1)propertyName"
        class=(2)"ClassName"
        cascad(3)e="cascade_style"
        constr(4)ained="true|false"
        fetch=(5)"join|select"
        proper(6)ty-ref="propertyNameFromAssociatedClass"
        access(7)="field|property|ClassName"
        formul(8)a="any SQL expression"
        lazy="(9)proxy|no-proxy|false"
        entity(10)-name="EntityName"
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        foreign-key="foreign_key_name"
/>

1

name: El nombre de la propiedad.

2

class (opcional - por defecto es el tipo de la propiedad determinado por reflección): El nombre de la clase asociada.

3

cascade (opcional) especifica qué operaciones deben ir en cascada desde el objeto padre hasta el objeto asociado.

4

constrained (opcional): especifica que una restricción de clave foránea en la clave principal de la tabla mapeada referencia la tabla de la clase asociada. Esta opción afecta el orden en que van en la cascada save() y delete() y determina si la asociación puede ser virtualizada por proxies. La herramienta de exportación de esquemas también lo utiliza.

5

fetch (opcional - por defecto es select): Escoge entre la recuperación de unión exterior (outer-join) o la recuperación por selección secuencial.

6

property-ref (opcional): El nombre de una propiedad de la clase asociada que esté unida a la clave principal de esta clase. Si no se especifica, se utiliza la clave principal de la clase asociada.

7

access (opcional - por defecto es property): La estrategia que Hibernate utiliza para acceder al valor de la propiedad.

8

formula (opcional): Casi todas las asociaciones uno-a-uno mapean a la clave principal de la entidad propietaria. Si este no es el caso, puede especificar otra columna, o columnas, o una expresión para unir utilizando una fórmula SQL. Para un obtener un ejemplo consulte org.hibernate.test.onetooneformula.

9

lazy (opcional - por defecto es proxy): Por defecto, las asociaciones de punto único van con proxies. lazy="no-proxy" especifica que esta propiedad debe ser traída perezosamente cuando se acceda por primera vez la variable de instancia. Requiere instrumentación del código byte en tiempo de compilación. lazy="false" especifica que la asociación siempre será recuperada tempranamente. Observe que si constrained="false", la aplicación de proxies es imposible e Hibernate recuperará tempranamente la asociación.

10

entity-name (opcional): El nombre de entidad de la clase asociada.

Existen dos variedades de asociaciones uno-a-uno:

Las asociaciones de claves principales no necesitan una columna extra de la tabla. Si dos filas están relacionadas por la asociación entonces las dos filas de tablas comparten el mismo valor de clave principal. Para que dos objetos estén relacionados por una asociación de clave principal, asegúrese de que se les asigne el mismo valor de identificador.

Para una asociación de clave principal, agregue los siguientes mapeos a Employee y Person respectivamente:


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

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

Asegúrese de que las claves principales de las filas relacionadas en las tablas PERSON y EMPLOYEE sean iguales. Utilizamos una estrategia especial de generación de identificador de Hibernate denominada foreign:


<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
>

A una instancia recién guardada de Person se le asigna el mismo valor de clave principal que se le asignó a la instancia Employee referida por la propiedad employee de esa Person.

Opcionalmente, una clave foránea con una restricción de unicidad, desde Employee a Person, se puede expresar como:


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

Esta asociación puede hacerse bidireccional agregando lo siguiente al mapeo de Person:


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

El elemento <component> mapea propiedades de un objeto hijo a columnas de la tabla de la clase padre. Los componentes pueden, a su vez, declarar sus propias propiedades, componentes o colecciones. Vea a continuación los "componentes":

<component
        name="(1)propertyName"
        class=(2)"className"
        insert(3)="true|false"
        update(4)="true|false"
        access(5)="field|property|ClassName"
        lazy="(6)true|false"
        optimi(7)stic-lock="true|false"
        unique(8)="true|false"
        node="element-name|."
>

        <property ...../>
        <many-to-one .... />
        ........
</component
>

1

name: El nombre de la propiedad.

2

class (opcional - por defecto es el tipo de la propiedad determinado por reflección): El nombre de la clase del componente (hijo).

3

insert: ¿Las columnas mapeadas aparacen en INSERTs SQL?

4

update: ¿Las columnas mapeadas aparacen en UPDATEs SQL?

5

access (opcional - por defecto es property): La estrategia que Hibernate utiliza para acceder al valor de la propiedad.

6

lazy (opcional - por defecto es false): Especifica que este componente debe ser recuperado perezosamente cuando se acceda a la variable de instancia por primera vez. Requiere instrumentación de código byte en tiempo de compilación.

7

optimistic-lock (opcional - por defecto es true): Especifica que las actualizaciones de este componente requieren o no la adquisición de un bloqueo optimista. Determina si debe ocurrir un incremento de versión cuando esta propiedad se encuentra desactualizada.

8

unique (opcional - por defecto es false): Especifica que existe una restricción de unicidad sobre todas las columnas mapeadas del componente.

Las etiquetas hijas <property> mapean propiedades de la clase hija a las columnas de la tabla.

El elemento <component> permite un subelemento <parent> que mapea una propiedad de la clase del componente como una referencia a la entidad contenedora.

The <dynamic-component> element allows a Map to be mapped as a component, where the property names refer to keys of the map. See Sección 8.5, “Componentes dinámicos” for more information.

El elemento <properties> permite la definición de un grupo de propiedades lógico con nombre de una clase. El uso más importante de la contrucción es que permite que una combinación de propiedades sea el objetivo de una property-ref. También es una forma práctica de definir una restricción de unicidad multicolumna. Por ejemplo:

<properties
        name="(1)logicalName"
        insert(2)="true|false"
        update(3)="true|false"
        optimi(4)stic-lock="true|false"
        unique(5)="true|false"
>

        <property ...../>
        <many-to-one .... />
        ........
</properties
>

1

name: El nombre lógico del agrupamiento. No es un nombre de propiedad.

2

insert: ¿Las columnas mapeadas aparacen en INSERTs SQL?

3

update: ¿Las columnas mapeadas aparacen en UPDATEs SQL?

4

optimistic-lock (opcional - por defecto es true): Especifica que las actualizaciones de estas propiedades requieren o no de la adquisición de un bloqueo optimista. Determina si debe ocurrir un incremento de versión cuando estas propiedades están desactualizadas.

5

unique (opcional - por defecto es false): Especifica que existe una restricción de unicidad sobre todas las columnas mapeadas del componente.

Por ejemplo, si tenemos el siguiente mapeo de <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
>

Puede que tenga alguna asociación de datos heredados que se refiera a esta clave única de la tabla de Person, en lugar de la clave principal:


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

No recomendamos el uso de este tipo de cosas fuera del contexto del mapeo de datos heredados.

Se puede mapear cada subclase a su propia tabla. Esto se llama una estrategia de mapeo tabla-por-subclase. El estado heredado se recupera uniendo con la tabla de la superclase. Para hacer esto utilice elemento <joined-subclass>. Por ejemplo:

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

        <key .... >

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

1

name: El nombre de clase completamente calificado de la subclase.

2

table: El nombre de tabla de la subclase.

3

proxy (opcional): Especifica una clase o interfaz que se debe utilizar para proxies de inicialización perezosa.

4

lazy (opcional, por defecto es true): El establecer lazy="false" desactiva el uso de la recuperación perezosa.

No se necesita una columna discriminadora para esta estrategia de mapeo. Sin embargo, cada subclase debe declarar una columna de tabla que tenga el identificador del objeto utilizando el elemento <key>. El mapeo mencionado al comienzo del capítulo se reescribiría así:


<?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
>

For information about inheritance mappings see Capítulo 9, Mapeo de herencias.

Al utilizar el elemento <join>, es posible mapear las propiedades de una clase a varias tablas que tengan una relación uno-a-uno. Por ejemplo:

<join
        table=(1)"tablename"
        schema(2)="owner"
        catalo(3)g="catalog"
        fetch=(4)"join|select"
        invers(5)e="true|false"
        option(6)al="true|false">

        <key ... />

        <property ... />
        ...
</join
>

1

table: El nombre de la tabla unida.

2

schema (opcional): Sobrescribe el nombre del esquema especificado por el elemento raíz <hibernate-mapping>.

3

catalog (opcional): Sobrescribe el nombre del catálogo especificado por el elemento raíz <hibernate-mapping>.

4

fetch (opcional - por defecto es join): Si se establece como join, por defecto, Hibernate utilizará una unión interior (inner join) para recuperar un <join> definido por una clase o sus superclases. Utilizará una unión externa (outer join) para un <join> definido por una subclase. Si se establece como select, entonces Hibernate utilizará una selección secuencial para un <join> definido en una subclase. Esto se publicará sólamente si una fila representa una instancia de la subclase. Las uniones interiores todavía serán utilizadas para recuperar un <join> definido por la clase y sus superclases.

5

inverse (opcional - por defecto es false): De activarse, Hibernate no tratará de insertar o actualizar las propiedades definidas por esta unión.

6

optional (opcional - por defecto es false): De activarse, Hibernate insertará una fila sólo si las propiedades definidas por esta unión son no-nulas. Siempre utilizará una unión externa para recuperar las propiedades.

Por ejemplo, la información domiciliaria de una persona se puede mapear a una tabla separada, preservando a la vez la semántica de tipo de valor para todas las propiedades:


<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>
    ...

Con frecuencia, esta funcionalidad sólamente es útil para los modelos de datos heredados. Recomendamos menos tablas que clases y un modelo de dominio más detallado. Sin embargo, es útil para cambiar entre estrategias de mapeo de herencias en una misma jerarquía, como se explica más adelante.

Hasta ahora hemos visto el elemento <key> unas cuantas veces. Aparece en cualquier sitio en que el elemento padre de mapeo defina una unión a una nueva tabla que referencie la clave principal de la tabla original. También define la clave foránea en la tabla unida:

<key
        column(1)="columnname"
        on-del(2)ete="noaction|cascade"
        proper(3)ty-ref="propertyName"
        not-nu(4)ll="true|false"
        update(5)="true|false"
        unique(6)="true|false"
/>

1

column (opcional): El nombre de la columna de la clave foránea. Esto también se puede especificar por medio de uno o varios elementos anidados <column>.

2

on-delete (opcional - por defecto es noaction): Especifica si la restricción de clave foránea tiene el borrado en cascada activado a nivel de base de datos.

3

property-ref (opcional): Especifica que la clave foránea referencia columnas que no son la clave principal de la tabla original. Se proporciona para los datos heredados.

4

not-null (opcional): Especifica que las columnas de la clave foránea son no nulables. Esto se implica cuando la clave foránea también es parte de la clave principal.

5

update (opcional): Especifica que la clave foránea nunca se debe actualizar. Esto se implica cuando la clave foránea también es parte de la clave principal.

6

unique (opcional): Especifica que la clave foránea debe tener una restricción de . Esto se implica cuando la clave foránea también es la clave principal.

Para los sistemas en donde el rendimiento es importante, todas las claves deben ser definidas on-delete="cascade". Hibernate utiliza una restricción ON CASCADE DELETE a nivel de base de datos, en vez de muchas declaraciones DELETE individuales. Tenga en cuenta que esta funcionalidad evita la estrategia de bloqueo optimista normal de Hibernate para datos versionados.

Los atributos not-null y update son útiles al mapear una asociación uno a muchos unidireccional. Si mapea una unidireccional uno a muchos a una clave foránea no nulable, tiene que declarar la columna clave utilizando <key not-null="true">.

Los elementos de mapeo que acepten un atributo column aceptarán opcionalmente un subelemento <column>. De manera similar, <formula> es una alternativa al atributo formula. Por ejemplo:


<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"
        default="SQL expression"
        read="SQL expression"
        write="SQL expression"/>

<formula
>SQL expression</formula
>

La mayoría de los atributos en column proporcionan una manera de personalizar el DDL durante la generación del esquema automático. Los atributos read y write le permiten especificar SQL personalizado que Hibernate utilizará para acceder el valor de la columna. Para obtener mayor información sobre esto, consulte la discusión sobre expresiones de lectura y escritura de columnas.

Los elementos column y formula incluso se pueden combinar dentro del mismo mapeo de propiedad o asociación para expresar, por ejemplo, condiciones de unión exóticas.


<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
>

Hay un tipo más de mapeo de propiedad. El elemento de mapeo <any> define una asociación polimórfica a clases desde múltiples tablas. Este tipo de mapeo necesita más de una columna. La primera columna contiene el tipo de la entidad asociada. Las columnas restantes contienen el identificador. Es imposible especificar una restricción de clave foránea para este tipo de asociación. Esta no es la manera usual de mapear asociaciones polimórficas y sólamente debe usar esto en casos especiales. Por ejemplo, para registros de auditoría, datos de sesión de usuario, etc.

El atributo meta-type le permite especificar a la aplicación un tipo personalizado que mapea los valores de columnas de la base de datos a clases persistentes que tengan propiedades identificadoras del tipo especificado por id-type. Tiene que especificar el mapeo de valores del meta-tipo a nombres de clase.


<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="(1)propertyName"
        id-typ(2)e="idtypename"
        meta-t(3)ype="metatypename"
        cascad(4)e="cascade_style"
        access(5)="field|property|ClassName"
        optimi(6)stic-lock="true|false"
>
        <meta-value ... />
        <meta-value ... />
        .....
        <column .... />
        <column .... />
        .....
</any
>

1

name: el nombre de la propiedad.

2

id-type: el tipo del identificador.

3

meta-type (opcional - por defecto es string): Cualquier tipo que se permita para un mapeo discriminador.

4

cascade (opcional- por defecto es none): el estilo de cascada.

5

access (opcional - por defecto es property): La estrategia que Hibernate utiliza para acceder al valor de la propiedad.

6

optimistic-lock (opcional - por defecto es true): Especifica si las actualizaciones de esta propiedad requieren o no de la adquisición del bloqueo optimista. Define si debe ocurrir un incremento de versión cuando esta propiedad está desactualizada.

En relación con el servicio de persistencia, los objetos a nivel de lenguaje Java se clasifican en dos grupos:

Una entidad existe independientemente de cualquier otro objeto que referencie a la entidad. Compare esto con el modelo habitual de Java en donde un objeto no referenciado es recolectado como basura. Las entidades deben ser guardadas y borradas explícitamente. Sin embargo, los grabados y borrados se pueden tratar en cascada desde una entidad padre a sus hijos. Esto es diferente al modelo de persistencia de objetos por alcance (ODMG) y corresponde más a cómo se utilizan habitualmente los objetos de aplicación en sistemas grandes. Las entidades soportan referencias circulares y compartidas, que también pueden ser versionadas.

El estado persistente de una entidad consta de las referencias a otras entidades e instancias de tipo valor. Los valores son primitivos: colecciones (no lo que está dentro de la colección), componentes y ciertos objetos inmutables. A diferencia de las entidades, los valores en particular las colecciones y los componentes, son persistidos y borrados por alcance. Como los objetos valor y primitivos son persistidos y borrados junto con sus entidades contenedoras, no se pueden versionar independientemente. Los valores no tienen identidad independiente, por lo que dos entidades o colleciones no los pueden compartir.

Hasta ahora, hemos estado utilizando el término "clase persistente" para referirnos a entidades. Continuaremos haciéndolo así. Sin embargo, no todas la clases con estado persistente definidas por el usuario son entidades. Un componente es una clase definida por el usuario con semántica de valor. Una propiedad Java de tipo java.lang.String también tiene semántica de valor. Dada esta definición, podemos decir que todos los tipo (clases) provistos por el JDK tienen una semántica de tipo valor en Java, mientras que los tipos definidos por el usuario se pueden mapear con semántica de tipo valor o de entidad. La desición corre por cuenta del desarrollador de la aplicación. Una clase entidad en un modelo de dominio son las referencias compartidas a una sola instancia de esa clase, mientras que la composición o agregación usualmente se traducen a un tipo de valor.

Volveremos a revisar ambos conceptos a lo largo de este manual de referencia.

EL desafío es mapear el sistema de tipos de Java ( la definición de entidades y tipos de valor de los desarrolladores al sistema de tipos de SQL/la base de datos. El puente entre ambos sistemas lo brinda Hibernate. Para las entidades utilizamos <class>, <subclass>, etc. Para los tipos de valor utilizamos <property>, <component>, etc, usualmente con un atributo type. El valor de este atributo es el nombre de un tipo de mapeo de Hibernate. Hibernate proporciona un rango de mapeos para tipos de valores del JDK estándar. Puede escribir sus propios mapeos de tipo e implementar sus estrategias de conversión personalizadas.

Todos los tipos incorporados de Hibernate soportan la semántica de nulos, a excepción de las colecciones.

Los tipos de mapeo básicos incorporados se pueden categorizar así:

integer, long, short, float, double, character, byte, boolean, yes_no, true_false

Mapeos de tipos de primitivos de Java o de clases de envoltura a los tipos de columna SQL (específica del vendedor). boolean, yes_no y true_false son codificaciones alternativas a boolean de Java o java.lang.Boolean.

string

Un mapeo del tipo java.lang.String a VARCHAR (u Oracle VAARCHAR2).

date, time, timestamp

Mapeos de tipo desde java.util.Date y sus subclases a tipos SQL DATE, TIME y TIMESTAMP (o equivalente).

calendar, calendar_date

Mapeos de tipo desde java.util.Date y tipos SQL TIMESTAMP y DATE (o equivalente).

big_decimal, big_integer

Mapeos de tipo desde java.math.BigDecimal y java.math.BigInteger a NUMERIC (o NUMBER de Oracle).

locale, timezone, currency

Mapeos de tipo desde java.util.Locale, java.util.TimeZone y java.util.Currency a VARCHAR (o VARCHAR2 de Oracle). Las instancias de Locale y Currency son mapeadas a sus códigos ISO. Las instancias de TimeZone son mapeadas a sus ID.

class

Un mapeo de tipo java.lang.Class a VARCHAR (o VARCHAR2 de Oracle). Una Class es mapeada a su nombre completamente calificado.

binary

Mapea arreglos de bytes a un tipo binario SQL apropiado.

text

Mapea cadenas largas de Java al tipo SQL CLOB o TEXT.

serializable

Mapea tipos serializables Java a un tipo binario SQL apropiado. También puede indicar el tipo serializable de Hibernate con el nombre de una clase o interfaz serializable Java que no sea por defecto un tipo básico.

clob, blob

Mapeos de tipo para las clases JDBC java.sql.Clob y java.sql.Blob. Estos tipos pueden ser inconvenientes para algunas aplicaciones, pues el objeto blob o clob no pueden ser reusados fuera de una transacción. Además, el soporte del controlador suele ser malo e inconsistente.

imm_date, imm_time, imm_timestamp, imm_calendar, imm_calendar_date, imm_serializable, imm_binary

Los mapeos de tipo para lo que usualmente se considera tipos Java mutables. Aquí es donde Hibernate realiza ciertas optimizaciones apropiadas sólamente para tipos Java inmutables y la aplicación trata el objeto como inmutable. Por ejemplo, no debe llamar Date.setTime() para una instancia mapeada como imm_timestamp. Para cambiar el valor de la propiedad y hacer que ese cambio sea persistente, la aplicación tiene que asignar un objeto nuevo, no idéntico, a la propiedad.

Los identificadores únicos de entidades y colecciones pueden ser de cualquier tipo básico excepto binary, blob y clob. Los identificadores compuestos también están permitidos, a continuación encontrará mayor información.

Los tipos de valor básicos tienen sus constantes Type correspondientes definidas en org.hibernate.Hibernate. Por ejemplo, Hibernate.STRING representa el tipo string.

Es relativamente fácil para los desarrolladores crear sus propios tipos de valor. Por ejemplo, puede que quiera persistir propiedades del tipo java.lang.BigInteger a columnas VARCHAR. Hibernate no provee un tipo incorporado para esto. Los tipos personalizados no están limitados a mapear una propiedad o elemento de colección a una sola columna de tabla. Así, por ejemplo, podría tener una propiedad Java getName()/setName() de tipo java.lang.String que es persistida a las columnas FIRST_NAME, INITIAL, SURNAME.

Para implementar un tipo personalizado, implemente org.hibernate.UserType o org.hibernate.CompositeUserType y declare las propiedades utilizando el nombre de clase completamente calificado del tipo. Revise org.hibernate.test.DoubleStringType para ver qué clases de cosas son posibles.


<property name="twoStrings" type="org.hibernate.test.DoubleStringType">
    <column name="first_string"/>
    <column name="second_string"/>
</property
>

Observe el uso de etiquetas <column> para mapear una propiedad a múltiples columnas.

Las interfaces CompositeUserType, EnhancedUserType, UserCollectionType, y UserVersionType brindan soporte para usos más especializados.

Incluso usted puede proporcionar parámetros a un UserType en el archivo de mapeo. Para hacer esto, su UserType tiene que implementar la interfaz org.hibernate.usertype.ParameterizedType. Para brindar parámetros a su tipo personalizado, puede utilizar el elemento <type> en sus archivos de mapeo.


<property name="priority">
    <type name="com.mycompany.usertypes.DefaultValueIntegerType">
        <param name="default"
>0</param>
    </type>
</property
>

Ahora el UserType puede recuperar el valor del parámetro denominado default del objeto Properties que se le pasa.

Si utiliza cierto UserType muy frecuentemente, puede ser útil el definir un nombre más corto para este. Puede hacer esto utilizando el elemento <typedef>. Los typedefs asignan un nombre a un tipo personalizado y también pueden contener una lista de valores predeterminados de parámetros si el tipo se encuentra parametrizado.


<typedef class="com.mycompany.usertypes.DefaultValueIntegerType" name="default_zero">
    <param name="default"
>0</param>
</typedef
>

<property name="priority" type="default_zero"/>

También es posible sobrescribir los parámetros provistos en un typedef sobre una base de caso por caso utilizando parámetros de tipo en el mapeo de la propiedad.

Aunque el amplio espectro de tipos incorporados y de soporte para los componentes de Hibernate significa que necesitará usar un tipo personalizado muy raramente, se considera como una buena práctica el utilizar tipos personalizados para clases no-entidades que aparezcan frecuentemente en su aplicación. Por ejemplo, una clase MonetaryAmount es una buena candidata para un CompositeUserType, incluso cuando puede ser fácilmente mapeada como un componente. Un razón para esto es la abstracción. Con un tipo personalizado, sus documentos de mapeo estarán protegidos contra posibles cambios futuros en la forma de representar valores monetarios.

XML no es para todo el mundo, así que hay algunas formas opcionales de definir metadatos de mapeo O/R en Hibernate.

Muchos usuarios de Hibernate prefieren incluir la información de mapeo directamente en el código fuente usando las @hibernate.tags XDoclet. No abordaremos este enfoque en este manual de referencia ya que se considera como parte de XDoclet. Sin embargo, incluímos el siguiente ejemplo de la clase Cat con los mapeos XDoclet:

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

Para obtener más ejemplos de XDoclet e Hibernate consulte el sitio web de Hibernate.

JDK 5.0 introdujo anotaciones del estilo XDoclet a nivel del lenguaje con chequeo seguro de tipos en tiempo de compilación. Este mecanismo es más potente que las anotaciones XDoclet y es mejor soportado por herramientas e IDEs. IntelliJ IDEA, por ejemplo, soporta auto-completación además de resalte de sintaxis de las anotaciones JDK 5.0. La nueva revisión de la especificación de EJB (JSR-220) utiliza anotaciones JDK 5.0 como el mecanismo principal de metadatos para beans de entidad. Hibernate3 implementa el EntityManager del JSR-220 (la API de persistencia). El soporte para metadatos de mapeo está disponible por medio del paquete Anotaciones de Hibernate, como una descarga separada. Tanto los metadatos de EJB3 (JSR-220) como de Hibernate3 se encuentran soportados.

Este es un ejemplo de una clase POJO anotada como un bean de entidad EJB:

@Entity(access = AccessType.FIELD)

public class Customer implements Serializable {
    @Id;
    Long id;
    String firstName;
    String lastName;
    Date birthday;
    @Transient
    Integer age;
    @Embedded
    private Address homeAddress;
    @OneToMany(cascade=CascadeType.ALL)
    @JoinColumn(name="CUSTOMER_ID")
    Set<Order
> orders;
    // Getter/setter and business methods
}

Las propiedades generadas son propiedades cuyos valores son generados por la base de datos. Usualmente, las aplicaciones de Hibernate necesitaban refrescar los objetos que contenian cualquier propiedad para la cual la base de datos generará valores. Sin embargo, el marcar propiedades como generadas deja que la aplicación delegue esta responsabilidad a Hibernate. Cuando Hibernate emite un INSERT or UPDATE SQL para una entidad la cual ha definido propiedades generadas, inmediatamente emite un select para recuperar los valores generados.

Las propiedades marcadas como generadas tienen que ser además no insertables y no actualizables. Sólamente las versiones, sellos de fecha, y propiedades simples se pueden marcar como generadas.

never (por defecto): el valor dado de la propiedad no es generado dentro de la base de datos.

insert: el valor dado de la propiedad es generado en insert, pero no es regenerado en las actualizaciones posteriores. Las propiedades como fecha-creada (created-date) se encuentran dentro de esta categoría. Aunque las propiedades versión y sello de fecha se pueden marcar como generadas, esta opción no se encuentra disponible.

always: el valor de la propiedad es generado tanto en insert como en update.

Hibernate allows you to customize the SQL it uses to read and write the values of columns mapped to simple properties. For example, if your database provides a set of data encryption functions, you can invoke them for individual columns like this:

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">property</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;creditCardNumber&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">column</span><span class="xml_plain">&nbsp;</span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;credit_card_num&quot;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">read</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;decrypt(credit_card_num)&quot;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">write</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;encrypt(?)&quot;</span><span class="xml_tag_symbols">/&gt;</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">property</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />

Hibernate aplica las expresiones personalizadas de manera automática cuando la propiedad se referencia en una petición. Esta funcionalidad es similar a una propiedad derivada formula con dos diferencias:

  • Esta propiedad está respaldada por una o más columnas que se exportan como parte de la generación automática del esquema.

  • La propiedad es de lectura y escritura no de sólo lectura.

Si se especifica la expresión write debe contener exactamente un parémetro de sustitución '?' para el valor.

Los objetos de bases de datos auxiliares permiten la creación - CREATE - y eliminación - DROP - de objetos de bases de datos arbitrarios. Junto con las herramientas de evolución del esquema de Hibernate, tienen la habilidad de definir de manera completa el esquema de un usuario dentro de los archivos de mapeo de Hibernate. Aunque están diseñados específicamente para crear y eliminar cosas como disparadores - triggers- o procedimientos almacenados, realmente cualquier comando SQL se puede ejecutar por medio de un método java.sql.Statement.execute() aquí es válido (por ejemplo, ALTERs, INSERTS, etc). Básicamente, hay dos modos para definir objetos de bases de datos auxiliares:

El primer modo es para numerar explícitamente los comandos CREATE y DROP en el archivo de mapeo:


<hibernate-mapping>
    ...
    <database-object>
        <create
>CREATE TRIGGER my_trigger ...</create>
        <drop
>DROP TRIGGER my_trigger</drop>
    </database-object>
</hibernate-mapping
>

El segundo modo es para proporcionar una clase personalizada que construye los comandos CREATE y DROP. Esta clase personalizada tiene que implementar la interfaz org.hibernate.mapping.AuxiliaryDatabaseObject.


<hibernate-mapping>
    ...
    <database-object>
        <definition class="MyTriggerDefinition"/>
    </database-object>
</hibernate-mapping
>

Adicionalmente, estos objetos de la base de datos se pueden incluir de manera opcional de forma que aplique sólamente cuando se utilicen ciertos dialectos.


<hibernate-mapping>
    ...
    <database-object>
        <definition class="MyTriggerDefinition"/>
        <dialect-scope name="org.hibernate.dialect.Oracle9iDialect"/>
        <dialect-scope name="org.hibernate.dialect.Oracle10gDialect"/>
    </database-object>
</hibernate-mapping
>

Hibernate requiere que los campos valuados en colección persistente se declaren como un tipo de interfaz. Por ejemplo:

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

La interfaz real puede ser java.util.Set, java.util.Collection, java.util.List, java.util.Map, java.util.SortedSet, java.util.SortedMap o lo que usted quiera (donde "lo que usted quiera" significa que tendrá que escribir una implementación de org.hibernate.usertype.UserCollectionType).

Note cómo se inicializó la variable de instancia con una instancia de HashSet. Esta es la mejor forma de inicializar las propiedades valuadas en colección de instancias recién instanciadas (no persistentes). Cuando hace persistente la instancia, llamando a persist(), por ejemplo, Hibernate realmente remplazará el HashSet con una instancia de una implementación de Set propia de Hibernate. Observe los siguientes errores:

Cat cat = new DomesticCat();

Cat kitten = new DomesticCat();
....
Set kittens = new HashSet();
kittens.add(kitten);
cat.setKittens(kittens);
session.persist(cat);
kittens = cat.getKittens(); // Okay, kittens collection is a Set
(HashSet) cat.getKittens(); // Error!

Las colecciones persistentes inyectadas por Hibernate se comportan como HashMap, HashSet, TreeMap, TreeSet o ArrayList, dependiendo del tipo de interfaz.

Las instancias de colecciones tienen el comportamiento usual de los tipos de valor. Son automáticamente persistidas al ser referenciadas por un objeto persistente y se borran automáticamente al desreferenciarse. Si una colección se pasa de un objeto persistente a otro, puede que sus elementos se muevan de una tabla a otra. Dos entidades no pueden compartir una referencia a la misma instancia de colección. Debido al modelo relacional subyacente, las propiedades valuadas en colección no soportan la semántica de valor nulo. Hibernate no distingue entre una referencia de colección nula y una colección vacía.

Utilice las colecciones persistentes de la misma forma en que utiliza colecciones de Java ordinarias. Sin embargo, asegúrese de que entiende la semántica de las asociaciones bidireccionales (se discuten más adelante).

El elemento de mapeo de Hibernate usado para mapear una colección depende del tipo de la interfaz. Por ejemplo, un elemento <set> se utiliza para mapear propiedades de tipo 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
>

Aparte de <set>, existen además los elementos de mapeo <list>, <map>, <bag>, <array> y <primitive-array>. El elemento <map> es representativo:

<map
    name="prop(1)ertyName"
    table="tab(2)le_name"
    schema="sc(3)hema_name"
    lazy="true(4)|extra|false"
    inverse="t(5)rue|false"
    cascade="a(6)ll|none|save-update|delete|all-delete-orphan|delete-orphan"
    sort="unso(7)rted|natural|comparatorClass"
    order-by="(8)column_name asc|desc"
    where="arb(9)itrary sql where condition"
    fetch="joi(10)n|select|subselect"
    batch-size(11)="N"
    access="fi(12)eld|property|ClassName"
    optimistic(13)-lock="true|false"
    mutable="t(14)rue|false"
    node="element-name|."
    embed-xml="true|false"
>

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

1

name: el nombre de la propiedad de colección

2

table (opcional - por defecto es el nombre de la propiedad): el nombre de la tabla de colección. No se utiliza para asociaciones uno-a-muchos.

3

schema (opcional): el nombre de un esquema de tablas para sobrescribir el esquema declarado en el elemento raíz

4

lazy (opcional - por defecto es true): deshabilita la recuperación perezosa y especifica que la asociación siempre es recuperada tempranamente. También se puede utilizar para activar una recuperación "extra-perezoza", en donde la mayoría de las operaciones no inicializan la colección. Esto es apropiado para colecciones grandes.

5

inverse (opcional - por defecto es false): marca esta colección como el extremo "inverso" de una asociación bidireccional.

6

cascade (opcional - por defecto es none): habilita operaciones en cascada para entidades hijas.

7

sort (opcional): especifica una colección con ordenamiento natural, o una clase comparadora dada.

8

order-by (opcional, sólamente en JDK1.4): especifica una columna de tabla o columnas que definen el orden de iteración del Map, Set o bag junto con un asc o desc opcional.

9

where (opcional): especifica una condición WHERE de SQL arbitraria que se utiliza al recuperar o quitar la colección. Esto es útil si la colección debe contener sólamente un subconjunto de los datos disponibles.

10

fetch (opcional, por defecto es select): Elige entre la recuperación por unión externa (outer-join), la recuperación por selección secuencial y la recuperación por subselección secuencial.

11

batch-size (opcional, por defecto es 1): especifica un "tamaño de lote" para recuperar perezosamente instancias de esta colección.

12

access (opcional - por defecto es property): La estrategia que Hibernate utiliza para acceder al valor de la propiedad de colección.

13

optimistic-lock (opcional - por defecto es true): Especifica que los cambios de estado de la colección causan incrementos de la versión de la entidad dueña. Para asociaciones uno a muchos, es posible que quiera deshabilitar esta opción.

14

mutable (opcional - por defectos es true): Un valor false especifica que los elementos de la colección nunca cambian. En algunos casos, esto permite una pequeña optimización de rendimiento.

Todos los mapeos de colección, excepto aquellos con semántica de set o bag, necesitan una columna índice en la tabla de colección. Una columna índice es una columna que mapea a un índice de array o índice de List o llave de Map. El índice de un Map puede ser de cualquier tipo básico, mapeado con <map-key>. Puede ser una referencia de entidad mapeada con <map-key-many-to-many>, o puede ser un tipo compuesto mapeado con <composite-map-key>. El índice de un array o lista es siempre de tipo integer y se mapea utilizando el elemento <list-index>. La columna mapeada contiene enteros secuenciales numerados desde cero, por defecto.

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

1

column_name (required): the name of the column holding the collection index values.

1

base (optional - defaults to 0): the value of the index column that corresponds to the first element of the list or array.

<map-key
        column(1)="column_name"
        formul(2)a="any SQL expression"
        type="(3)type_name"
        node="@attribute-name"
        length="N"/>

1

column (optional): the name of the column holding the collection index values.

2

formula (optional): a SQL formula used to evaluate the key of the map.

3

type (required): the type of the map keys.

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

1

column (optional): the name of the foreign key column for the collection index values.

2

formula (optional): a SQ formula used to evaluate the foreign key of the map key.

3

class (required): the entity class used as the map key.

Si su tabla no tiene una columna índice y todavía desea utilizar List como tipo de propiedad, puede mapear la propiedad como un <bag> de Hibernate. Un bag (bolsa) no retiene su orden al ser recuperado de la base de datos, pero puede ser ordenado o clasificado de manera opcional.

Cualquier colección de valores o asociación muchos-a-muchos requiere una tabla de colección dedicada con una columna o columnas de clave foránea, columna de elemento de colección o columnas y posiblemente una columna o columnas índices.

Para una colección de valores utilice la etiqueta <element>. Por ejemplo:

<element
        column(1)="column_name"
        formul(2)a="any SQL expression"
        type="(3)typename"
        length="L"
        precision="P"
        scale="S"
        not-null="true|false"
        unique="true|false"
        node="element-name"
/>

1

column (optional): the name of the column holding the collection element values.

2

formula (optional): an SQL formula used to evaluate the element.

3

type (required): the type of the collection element.

A many-to-many association is specified using the <many-to-many> element.

<many-to-many
        column(1)="column_name"
        formul(2)a="any SQL expression"
        class=(3)"ClassName"
        fetch=(4)"select|join"
        unique(5)="true|false"
        not-fo(6)und="ignore|exception"
        entity(7)-name="EntityName"
        proper(8)ty-ref="propertyNameFromAssociatedClass"
        node="element-name"
        embed-xml="true|false"
    />

1

column (optional): the name of the element foreign key column.

2

formula (optional): an SQL formula used to evaluate the element foreign key value.

3

class (required): the name of the associated class.

4

fetch (optional - defaults to join): enables outer-join or sequential select fetching for this association. This is a special case; for full eager fetching in a single SELECT of an entity and its many-to-many relationships to other entities, you would enable join fetching,not only of the collection itself, but also with this attribute on the <many-to-many> nested element.

5

unique (optional): enables the DDL generation of a unique constraint for the foreign-key column. This makes the association multiplicity effectively one-to-many.

6

not-found (optional - defaults to exception): specifies how foreign keys that reference missing rows will be handled: ignore will treat a missing row as a null association.

7

entity-name (optional): the entity name of the associated class, as an alternative to class.

8

property-ref (optional): the name of a property of the associated class that is joined to this foreign key. If not specified, the primary key of the associated class is used.

Aquí tiene algunos ejemplos:

Un grupo de cadenas:


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

Un bag que contiene enteros con un orden de iteración determinado por el atributo order-by:


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

Una lista de entidades, en este caso, una asociación muchos-a-muchos:


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

Un mapeo de índices de cadenas a fechas:


<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
>

Una lista de componentes (se discuten en el siguiente capítulo):


<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
>

Una asociación uno-a-muchos enlaza las tablas de dos clases por medio de una clave foránea, sin intervención de tabla de colección alguna. Este mapeo pierde cierta semántica de colecciones Java normales:

Una asociación de Product a Part requiere la existencia de una columna clave foránea y posiblemente una columna índice a la tabla Part. Una etiqueta <one-to-many> indica que ésta es una asociación uno-a-muchos.

<one-to-many
        class=(1)"ClassName"
        not-fo(2)und="ignore|exception"
        entity(3)-name="EntityName"
        node="element-name"
        embed-xml="true|false"
    />

1

class (requerido): El nombre de la clase asociada.

2

not-found (opcional - por defecto es exception): Especifica cómo serán manejados los identificadores en caché que referencien filas perdidas. ignore tratará una fila perdida como una asociación nula.

3

entity-name (opcional): El nombre de entidad de la clase asociada como una alternativa para class.

El elemento <one-to-many> no necesita declarar ninguna columna. Ni es necesario especificar el nombre de table en ningún sitio.

El siguiente ejemplo muestra un mapeo de entidades Part por nombre, en donde partName es una propiedad persistente de Part. Observe el uso de un índice basado en fórmula:


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

Hibernate soporta colecciones implementando java.util.SortedMap y java.util.SortedSet. Tiene que especificar un comparador en el archivo de mapeo:


<set name="aliases"
            table="person_aliases" 
            sort="natural">
    <key column="person"/>
    <element column="name" type="string"/>
</set>

<map name="holidays" sort="my.custom.HolidayComparator">
    <key column="year_id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date" type="date"/>
</map
>

Los valores permitidos del atributo sort son unsorted, natural y el nombre de una clase que implemente java.util.Comparator.

Las colecciones ordenadas realmente se comportan como java.util.TreeSet o java.util.TreeMap.

Si quiere que la misma base de datos ordene los elementos de la colección, utilice el atributo order-by de los mapeos set, bag o map. Esta solución está disponible sólamente bajo el JDK 1.4 o superior y se implementa utilizando LinkedHashSet o LinkedHashMap. Este realiza la ordenación en la consulta SQL y no en memoria.


<set name="aliases" table="person_aliases" order-by="lower(name) asc">
    <key column="person"/>
    <element column="name" type="string"/>
</set>

<map name="holidays" order-by="hol_date, hol_name">
    <key column="year_id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date type="date"/>
</map
>

Las asociaciones pueden incluso ser ordenadas por algún criterio arbitrario en tiempo de ejecución utilizando un filter() de colección:

sortedUsers = s.createFilter( group.getUsers(), "order by this.name" ).list();

Una asociación bidireccional permite la navegación desde ambos "extremos" de la asociación. Se soportan dos tipos de asociación bidireccional:

Puede especificar una asociación bidireccional muchos-a-muchos simplemente mapeando dos asociaciones muchos-a-muchos a la misma tabla de base de datos y declarando un extremo como inverso (cuál de ellos, usted escoge, pero no puede ser una colección indexada).

He aquí un ejemplo de una asociación bidireccional muchos-a-muchos que ilustra la manera en que cada categoría puede tener muchos ítems y cada ítem puede estar en muchas categorías:


<class name="Category">
    <id name="id" column="CATEGORY_ID"/>
    ...
    <bag name="items" table="CATEGORY_ITEM">
        <key column="CATEGORY_ID"/>
        <many-to-many class="Item" column="ITEM_ID"/>
    </bag>
</class>

<class name="Item">
    <id name="id" column="ITEM_ID"/>
    ...

    <!-- inverse end -->
    <bag name="categories" table="CATEGORY_ITEM" inverse="true">
        <key column="ITEM_ID"/>
        <many-to-many class="Category" column="CATEGORY_ID"/>
    </bag>
</class
>

Los cambios realizados sólamente al extremo inverso de la asociación no son persistidos. Esto significa que Hibernate tiene dos representaciones en memoria para cada asociación bidireccional: un enlace de A a B y otro enlace de B a A. Esto es más fácil de entender si piensa en el modelo de objetos de Java y cómo creamos una relación muchos-a-muchos en Java:



category.getItems().add(item);          // The category now "knows" about the relationship
item.getCategories().add(category);     // The item now "knows" about the relationship
session.persist(item);                   // The relationship won't be saved!
session.persist(category);               // The relationship will be saved

El lado no-inverso se utiliza para guardar la representación en memoria a la base de datos.

Puede definir una asociación bidireccional uno-a-muchos mapeando una asociación uno-a-muchos a la misma columna (o columnas) de tabla como una asociación muchos-a-uno y declarando el extremo multivaluado inverse="true".


<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <set name="children" inverse="true">
        <key column="parent_id"/>
        <one-to-many class="Child"/>
    </set>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        not-null="true"/>
</class
>

Mapear un extremo de una asociación con inverse="true" no afecta la operación de cascadas ay que éstos son conceptos ortogonales.

Requiere especial atención una asociación bidireccional en donde un extremo esté representado como una <list> o <map>. Si hay una propiedad de la clase hija que mapee a la columna índice, puede utilizar inverse="true" en el mapeo de la colección:


<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <map name="children" inverse="true">
        <key column="parent_id"/>
        <map-key column="name" 
            type="string"/>
        <one-to-many class="Child"/>
    </map>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <property name="name" 
        not-null="true"/>
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        not-null="true"/>
</class
>

Si no existe tal propiedad en la clase hija, no podemos considerar la asociación como verdaderamente bidireccional. Es decir, hay información en un extremo de la asociación que no está disponible en el otro extremo. En este caso, no puede mapear la colección con inverse="true". En cambio, puede usar el siguiente mapeo:


<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <map name="children">
        <key column="parent_id"
            not-null="true"/>
        <map-key column="name" 
            type="string"/>
        <one-to-many class="Child"/>
    </map>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        insert="false"
        update="false"
        not-null="true"/>
</class
>

Note que en este mapeo, el extremo de la asociación valuado en colección es responsable de las actualizaciones de la clave foránea.

La mayoría de las asociaciones muchos-a-muchos y las colecciones de valores que hemos mostrado hasta ahora mapean a tablas con claves compuestas, aunque se ha sugerido que las entidades deben tener identificadores sintéticos (llaves sustitutas). Una tabla de pura asociación no parece beneficiarse mucho de una llave sustituta, aunque sí podría beneficiarse una colección de valores compuestos. Es por esto que Hibernate brinda una funcionalidad que le permite mapear asociaciones muchos a muchos y colecciones de valores a una tabla con una llave sustituta.

El elemento <idbag> le permite mapear una List (o Collection) con semántica de bag. Por ejemplo:


<idbag name="lovers" table="LOVERS">
    <collection-id column="ID" type="long">
        <generator class="sequence"/>
    </collection-id>
    <key column="PERSON1"/>
    <many-to-many column="PERSON2" class="Person" fetch="join"/>
</idbag
>

Un <idbag> tiene un generador de id sintético, al igual que una clase de entidad. Se asigna una clave delegada diferente a cada fila de la colección. Sin embargo, Hibernate no proporciona ningún mecanismo para descubrir el valor de la clave delegada de una fila en particular.

El rendimiento de actualización de un <idbag> es mucho mejor que el de un <bag> normal. Hibernate puede localizar filas individuales eficientemente y actualizarlas o borrarlas individualmente, al igual que si fuese una lista, mapa o conjunto.

En la implementación actual, la estrategia de generación de identificador native no se encuentra soportada para identificadores de colecciones <idbag>.

Esta sección cubre los ejemplos de colección.

La siguiente clase tiene una colección de instancias Child:

package eg;

import java.util.Set;
public class Parent {
    private long id;
    private Set children;
    public long getId() { return id; }
    private void setId(long id) { this.id=id; }
    private Set getChildren() { return children; }
    private void setChildren(Set children) { this.children=children; }
    ....
    ....
}

Si cada hijo tiene como mucho un padre, el mapeo más natural es una asociación uno-a-muchos:


<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children">
            <key column="parent_id"/>
            <one-to-many class="Child"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
    </class>

</hibernate-mapping
>

Esto mapea a las siguientes definiciones de tabla:


create table parent ( id bigint not null primary key )
create table child ( id bigint not null primary key, name varchar(255), parent_id bigint )
alter table child add constraint childfk0 (parent_id) references parent

Si el padre es requerido, utilice una asociación bidireccional uno-a-muchos:


<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children" inverse="true">
            <key column="parent_id"/>
            <one-to-many class="Child"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
        <many-to-one name="parent" class="Parent" column="parent_id" not-null="true"/>
    </class>

</hibernate-mapping
>

Observe la restricción NOT NULL:


create table parent ( id bigint not null primary key )
create table child ( id bigint not null
                     primary key,
                     name varchar(255),
                     parent_id bigint not null )
alter table child add constraint childfk0 (parent_id) references parent

Opcionalmente, si esta asociación debe ser unidireccional, puede declarar la restricción NOT NULL en el mapeo de <key>:


<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children">
            <key column="parent_id" not-null="true"/>
            <one-to-many class="Child"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
    </class>

</hibernate-mapping
>

Por otro lado, si un hijo tiene múltiples padres, una asociación muchos-a-muchos es apropiada:


<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children" table="childset">
            <key column="parent_id"/>
            <many-to-many class="Child" column="child_id"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
    </class>

</hibernate-mapping
>

Definiciones de tabla:

create table parent ( id bigint not null primary key )
create table child ( id bigint not null primary key, name varchar(255) )
create table childset ( parent_id bigint not null,
                        child_id bigint not null,
                        primary key ( parent_id, child_id ) )
alter table childset add constraint childsetfk0 (parent_id) references parent
alter table childset add constraint childsetfk1 (child_id) references child

For more examples and a complete explanation of a parent/child relationship mapping, see Capítulo 22, Ejemplo: Padre/Hijo for more information.

En el próximo capítulo abordaremos los mapeos de asociaciones más complejas.

Una asociación bidireccional muchos-a-uno es el tipo de asociación más común. El siguiente ejemplo ilustra la relación estándar padre/hijo.


<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <many-to-one name="address" 
        column="addressId"
        not-null="true"/>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
    <set name="people" inverse="true">
        <key column="addressId"/>
        <one-to-many class="Person"/>
    </set>
</class
>
create table Person ( personId bigint not null primary key, addressId bigint not null )
create table Address ( addressId bigint not null primary key )
        

Si utiliza un List, u otra colección con índice, configure la columna key de la clave foránea como not null. Hibernate administrará la asociación del lado de las colecciones para mantener el índice de cada elemento, haciendo del otro lado virtualmente inverso al establecer update="false" y insert="false":


<class name="Person">
   <id name="id"/>
   ...
   <many-to-one name="address"
      column="addressId"
      not-null="true"
      insert="false"
      update="false"/>
</class>

<class name="Address">
   <id name="id"/>
   ...
   <list name="people">
      <key column="addressId" not-null="true"/>
      <list-index column="peopleIdx"/>
      <one-to-many class="Person"/>
   </list>
</class
>

Es importante que defina not-null="true" en el elemento <key> del mapeo de la colección si la columna de la clave foránea es NOT NULL. No declare sólamente not-null="true" en un elemento <column> posiblemente anidado sino en el elemento <key>.

Uniones de asociación más complejas son extremadamente raras. Hibernate maneja situaciones más complejas utilizando fragmentos SQL incluidos en el documento de mapeo. Por ejemplo, si una tabla con datos históricos de información de cuenta define las columnas accountNumber, effectiveEndDate y effectiveStartDate, se mapearían así:


<properties name="currentAccountKey">
    <property name="accountNumber" type="string" not-null="true"/>
    <property name="currentAccount" type="boolean">
        <formula
>case when effectiveEndDate is null then 1 else 0 end</formula>
    </property>
</properties>
<property name="effectiveEndDate" type="date"/>
<property name="effectiveStateDate" type="date" not-null="true"/>

Entonces puede mapear una asociación a la instancia actual, la que tiene effectiveEndDate nulo, utilizando:


<many-to-one name="currentAccountInfo"
        property-ref="currentAccountKey"
        class="AccountInfo">
    <column name="accountNumber"/>
    <formula
>'1'</formula>
</many-to-one
>

En un ejemplo más complejo, imagínese que la asociación entre Employee y Organization se mantienen en una tabla Employment llena de datos históricos de empleo. Entonces se puede mapear una asociación al empleador más reciente del empleado, el que tiene la startDate más reciente, de esta manera:


<join>
    <key column="employeeId"/>
    <subselect>
        select employeeId, orgId 
        from Employments 
        group by orgId 
        having startDate = max(startDate)
    </subselect>
    <many-to-one name="mostRecentEmployer" 
            class="Organization" 
            column="orgId"/>
</join
>

Esta funcionalidad le permite cierto grado de creatividad y flexibilidad, pero usualmente es más práctico manejar esta clase de casos utilizando HQL o una petición de criterio.

La noción de un componente se reutiliza en muchos contextos diferentes, para propósitos diferentes a través de Hibernate.

Un componente es un objeto contenido que es persistido como un tipo de valor, no una referencia de entidad. El término "componente" hace referencia a la noción orientada a objetos de composición y no a componentes a nivel de arquitectura. Por ejemplo, puede modelar una persona así:

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

Ahora Name puede ser persistido como un componente de Person. Name define métodos getter y setter para sus propiedades persistentes, pero no necesita declarar ninguna interfaz ni propiedades identificadoras.

Nuestro mapeo de Hibernate se vería así:


<class name="eg.Person" table="person">
    <id name="Key" column=