Hibernate.org Community Documentation

- Anterior
- Siguiente

## Capítulo 22. Manual del conjunto de herramientas

La ingeniería compatible con Hibernate es posible utilizando un conjunto de plugins de Eclipse, herramientas de la línea de comandos así como tareas Ant.

Las herramientas de Hibernate actualmente incluyen plugins la IDE de Eclipse así como tareas Ant para la ingeniería inversa de bases de datos existentes:

- Editor de Mapeo: Un editor de archivos de mapeo XML que soporta autocompleción y resaltado de sintáxis. También soporta la autocompleción semántica de nombres de clases y nombres de campos/propiedades, haciéndolo mucho más versátil que un editor normal de XML.

- Consola: La consola es una nueva vista en Eclipse. Además de la vista de árbol de sus configuraciones de la consola, también tiene una vista interactiva de sus clases persistentes y sus relaciones. La consola le permite ejecutar consultas HQL en su base de datos y navegar el resultado directamente en Eclipse.

- Asistentes de desarrollo: Se proporcionan muchos asistentes junto con las herramientas Eclipse de Hibernate. Puede utilizar un asistente para generar rápidamente los archivos de configuración de Hibernate (cfg.xml), o incluso puede realizar una ingeniería inversa completa de un esquema de la base de datos existente en los archivos de código fuente de POJO y los archivos de mapeo de Hibernate. El asistente de ingeniería inversa soporta plantillas personalizables.

Por favor refiérase al paquete de documentación de las Herramientas de Hibernate para obtener más información.

Sin embargo, el paquete principal de Hibernate viene con una herramienta integrada: SchemaExport también conocida como `hbm2ddl`. Incluso se puede utilizar "dentro" de Hibernate.

## 22.1. Generación automática de esquemas

Una de las funciones de Hibernate puede generar DDL desde sus archivos de mapeo. El esquema generado incluye restricciones de integridad referencial, claves principales y foráneas, para las tablas de entidades y colecciones. También se creen tablas y secuencias para los generadores de identificadores mapeados.

Tiene que especificar un `Dialecto` SQL por medio de la propiedad `hibernate.dialect` al usar esta herramienta, ya que el DDL es altamente específico de acuerdo con el vendedor.

Primero, debe personazar sus archivos de mapeo para mejorar el esquema generado. La siguiente sección aborda la personalización del esquema.

### 22.1.1. Personalización del esquema

Muchos elementos de mapeo de Hibernate definen atributos opcionales denominados `length`, `precision` y `scale`. Con estos atributos puede establecer el tamaño, la precisión y la escala de una columna.

    <property name="zip" length="5"/>

    <property name="balance" precision="12" scale="2"/>

Algunas etiquetas también aceptan un atributo `not-null` para generar una restricción `NOT NULL` en columnas de tablas y un atributo `unique` para generar restricciones `UNIQUE` en columnas de tablas.

    <many-to-one name="bar" column="barId" not-null="true"/>

    <element column="serialNumber" type="long" not-null="true" unique="true"/>

Se puede usar un atributo `unique-key` para agrupar columnas en una restricción de clave única. Actualmente, el valor especificado del atributo `unique-key` no se utiliza para nombrar la restricción en el DDL generado. Sólamente se utiliza para agrupar las columnas en el archivo de mapeo.

    <many-to-one name="org" column="orgId" unique-key="OrgEmployeeId"/>

    <property name="employeeId" unique-key="OrgEmployee"/>

Un atributo `index` especifica el nombre de un índice que se creará utilizando la columa o las columnas mapeadas. Se pueden ser agrupar múltiples columnas bajo el mismo índice, simplemente especificando el mismo nombre de índice.

    <property name="lastName" index="CustName"/>

    <property name="firstName" index="CustName"/>

Un atributo `foreign-key` se puede utilizar para sobreescribir el nombre de cualquier restricción de clave foránea generada.

    <many-to-one name="bar" column="barId" foreign-key="FKFooBar"/>

Muchos elementos de mapeo también aceptan un elemento `<column>` hijo. Esto es particularmente útil para mapear tipos de multi-columna:

    <property name="name" type="my.customtypes.Name"/>

        <column name="last" not-null="true" index="bar_idx" length="30"/>

        <column name="first" not-null="true" index="bar_idx" length="20"/>

        <column name="initial"/>

    </property

    >

El atributo `default` le permite especificar un valor por defecto para una columna. Usted le debe asignar el mismo valor a la propiedad mapeada antes de guardar una nueva instancia de la clase mapeada.

    <property name="credits" type="integer" insert="false">

        <column name="credits" default="10"/>

    </property

    >

    <version name="version" type="integer" insert="false">

        <column name="version" default="0"/>

    </property

    >

El atributo `sql-type` permite al usuario sobrescribir el mapeo por defecto de tipo Hibernate a tipo de datos SQL.

    <property name="balance" type="float">

        <column name="balance" sql-type="decimal(13,3)"/>

    </property

    >

El atributo `check` le permite especificar una comprobación de restricción.

    <property name="foo" type="integer">

        <column name="foo" check="foo

    > 10"/>

    </property

    >

    <class name="Foo" table="foos" check="bar < 100.0">

        ...

        <property name="bar" type="float"/>

    </class

    >

La siguiente tabla resume estos atributos opcionales.

Tabla 22.1. Resumen

Atributo | Valores | Interpretación
--- | --- | ---
`length` | número | longitud de columna/precisión decimal
`precision` | número | precisión decimal de columna
`scale` | número | escala decimal de columna
`not-null` | `true|false` | especifica que la columna debe ser sin nulos
`unique` | `true|false` | especifica que la columna debe tener una restricción de unicidad
`index` | `index_name` | especifica el nombre de un índice (multicolumna)
`unique-key` | `unique_key_name` | especifica el nombre de una restricción de unicidad multicolumna
`foreign-key` | `foreign_key_name` | especifica el nombre de la restricción de clave foránea generada por una asociación, para un elemento de mapeo `<one-to-one>`, `<many-to-one>`, `<key>`, o `<many-to-many>`. Observe que `SchemaExport` no considerará los lados `inverse="true"`.
`sql-type` | `SQL column type` | sobrescribe el tipo de columna por defecto (sólamente el atributo del elemento `<column>`)
`default` | expresión SQL | especifica un valor predeterminado para la columna
`check` | expresión SQL | crea una restricción de comprobación SQL en columna o tabla

El elemento `<comment>` le permite especificar un comentario para el esquema generado.

    <class name="Customer" table="CurCust">

        <comment

    >Current customers only</comment>

        ...

    </class

    >

    <property name="balance">

        <column name="bal">

            <comment

    >Balance in USD</comment>

        </column>

    </property

    >

Esto da como resultado una declaración `comment on table` o `comment on column` en el DDL generado, donde se encuentre soportado.

### 22.1.2. Ejecución de la herramienta

La herramienta `SchemaExport` escribe un script DDL a la salida estándar y/o ejecuta las declaraciones DDL.

La siguiente tabla presenta las opciones de la línea de comandos de `SchemaExport`

`java -cp` hibernate_classpaths `org.hibernate.tool.hbm2ddl.SchemaExport` options mapping_files

Tabla 22.2. Opciones de Línea de Comandos de `SchemaExport`

Opción | Descripción
--- | ---
`--quiet` | no envie el script a la salida estándar
`--drop` | sólamente desechar las tablas
`--create` | sólamente crear las tablas
`--text` | no exportar a la base de datos
`--output=my_schema.ddl` | enviar la salida del script ddl a un archivo
`--naming=eg.MyNamingStrategy` | seleccione un `NamingStrategy`
`--config=hibernate.cfg.xml` | lee la configuración de Hibernate de un archivo XML
`--properties=hibernate.properties` | lee las propiedades de base de datos de un archivo
`--format` | formatea muy bien el SQL generado en el script
`--delimiter=;` | establece un delimitador de fin de línea para el script

Inclusive puede incluir `SchemaExport` en su aplicación:

    Configuration cfg = ....;

    new SchemaExport(cfg).create(false, true);

### 22.1.3. Propiedades

Las propiedades de la base de datos se pueden especificar:

- como propiedades del sistema con `-D`<property>

- en `hibernate.properties`

- en un archivo de propiedades nombrado con `--properties`

Las propiedades necesarias son las siguientes:

Tabla 22.3. Propiedades de Conexión del SchemaExport

Nombre de la Propiedad | Descripción
--- | ---
`hibernate.connection.driver_class` | clase del controlador jdbc
`hibernate.connection.url` | url de jdbc
`hibernate.connection.username` | usuario de la base de datos
`hibernate.connection.password` | contraseña del usuario
`hibernate.dialect` | dialecto

### 22.1.4. Utilización de Ant

Puede llamar a `SchemaExport` desde su script de construcción de Ant:

    <target name="schemaexport">

        <taskdef name="schemaexport"

            classname="org.hibernate.tool.hbm2ddl.SchemaExportTask"

            classpathref="class.path"/>

        <schemaexport

            properties="hibernate.properties"

            quiet="no"

            text="no"

            drop="no"

            delimiter=";"

            output="schema-export.sql">

            <fileset dir="src">

                <include name="**/*.hbm.xml"/>

            </fileset>

        </schemaexport>

    </target

    >

### 22.1.5. Actualizaciones incrementales de esquema

La herramienta `SchemaUpdate` actualizará un esquema existente con cambios "incrementales". El `SchemaUpdate` depende de la API de metadatos de JDBC, de modo que no funcionará con todos los controladores JDBC.

`java -cp` hibernate_classpaths `org.hibernate.tool.hbm2ddl.SchemaUpdate` options mapping_files

Tabla 22.4. Opciones de Línea de Comandos de `SchemaUpdate`

Opción | Descripción
--- | ---
`--quiet` | no envie el script a la salida estándar
`--text` | no exporte el script a la base de datos
`--naming=eg.MyNamingStrategy` | seleccione un `NamingStrategy`
`--properties=hibernate.properties` | lee las propiedades de base de datos de un archivo
`--config=hibernate.cfg.xml` | specifique un archivo `.cfg.xml`

Puede incluir `SchemaUpdate` en su aplicación:

    Configuration cfg = ....;

    new SchemaUpdate(cfg).execute(false);

### 22.1.6. Utilización de Ant para actualizaciones incrementales de esquema

Puede llamar a `SchemaUpdate` desde el script de Ant:

    <target name="schemaupdate">

        <taskdef name="schemaupdate"

            classname="org.hibernate.tool.hbm2ddl.SchemaUpdateTask"

            classpathref="class.path"/>

        <schemaupdate

            properties="hibernate.properties"

            quiet="no">

            <fileset dir="src">

                <include name="**/*.hbm.xml"/>

            </fileset>

        </schemaupdate>

    </target

    >

### 22.1.7. Validación de Esquema

La herramienta `SchemaValidator` validará que el esquema de la base de datos existente "coincide" con sus documentos de mapeo. El `SchemaValidator` depene bastante de la API de metadatos JDBC así que no funcionará con todos los controladores JDBC. Esta herramienta es extremadamente útil para comprobar.

`java -cp` hibernate_classpaths `org.hibernate.tool.hbm2ddl.SchemaValidator` options mapping_files

La siguiente tabla presenta las opciones de la línea de comandos para `SchemaValidator`

Tabla 22.5. Opciones de la Línea de Comandos `SchemaValidator`

Opción | Descripción
--- | ---
`--naming=eg.MyNamingStrategy` | seleccione un `NamingStrategy`
`--properties=hibernate.properties` | lee las propiedades de base de datos de un archivo
`--config=hibernate.cfg.xml` | specifique un archivo `.cfg.xml`

Puede incluir `SchemaValidator` en su aplicación:

    Configuration cfg = ....;

    new SchemaValidator(cfg).validate();

### 22.1.8. Utilización de Ant para la validación de esquema

Puede llamar `SchemaValidator` desde el scrip de Ant:

    <target name="schemavalidate">

        <taskdef name="schemavalidator"

            classname="org.hibernate.tool.hbm2ddl.SchemaValidatorTask"

            classpathref="class.path"/>

        <schemavalidator

            properties="hibernate.properties">

            <fileset dir="src">

                <include name="**/*.hbm.xml"/>

            </fileset>

        </schemavalidator>

    </target

    >

Copyright © 2004 Red Hat, Inc.

- AnteriorCapítulo 21. Mejoramiento del rendimiento
- Subir
- Inicio
- SiguienteCapítulo 23. Additional modules