hibernate-orm/reference/es/modules/toolset_guide.xml

<chapter id="toolsetguide" revision="2">
    <title>Gu&#x00ed;a del Conjunto de Herramientas</title>

    <para>
        La ingenier&#x00ed;a de ida y vuelta con Hibernate es posible usando un conjunto de plugins de Eclipse,
        herramientas de l&#x00ed;nea de comandos, as&#x00ed; como tareas de Ant.
    </para>

    <para>
        Las <emphasis>Herramientas de Hibernate</emphasis> actualmente incluyen plugins para la IDE de
        Eclipse as&#x00ed; como tareas de Ant para la ingenier&#x00ed;a inversa de bases de datos existentes:
    </para>

    <itemizedlist>
        <listitem><para>
            <emphasis>Editor de Mapeo:</emphasis> Un editor de ficheros de mapeo XML, que soporta autocompleci&#x00f3;n
            y resaltado de sint&#x00e1;xis. Soporta tambi&#x00e9;n autocompleci&#x00f3;n sem&#x00e1;ntica de nombres de clases y nombres de
            campos/propiedades, haci&#x00e9;ndolo mucho m&#x00e1;s vers&#x00e1;til que un editor de XML normal.
        </para></listitem>
        <listitem><para>
            <emphasis>Consola:</emphasis> La consola es una nueva vista en Eclipse. Adem&#x00e1;s de la vista de
            &#x00e1;rbol de tus configuraciones de consola, tienes tambi&#x00e9;n una vista interactiva de tus clases
            persistentes y sus relaciones. La console te permite ejecutar consultas HQL contra tu base de datos y
            navegar el resultado directamente en Eclipse.
        </para></listitem>
        <listitem><para>
            <emphasis>Asistentes de Desarrollo:</emphasis> Se proveen muchos asistentes con las herramientas
            de Eclipse. Puedes usar un asistente para generar r&#x00e1;pidamente ficheros de configuraci&#x00f3;n de Hibernate
            (cfg.xml), o incluso puedes haceruna ingenier&#x00ed;a inversa completa de un esquema de base de datos existente
            en ficheros de c&#x00f3;digo de POJO y ficheros de mapeo de Hibernate. El asistente de ingenier&#x00ed;a inversa soporta
            plantillas personalizables.
        </para></listitem>
        <listitem><para>
            <emphasis>Tareas de Ant:</emphasis>
        </para></listitem>

    </itemizedlist>

    <para>
        Por favor refi&#x00e9;rete al paquete <emphasis>Herramientas de Hibernate</emphasis> y su documentaci&#x00f3;n para
        m&#x00e1;s informaci&#x00f3;n.
    </para>

    <para>
        Sin embargo, el paquete principal de Hibernate viene incluyendo una herramienta integrada
        (puede ser usada incluso "dentro" de Hibernate on-the-fly): <emphasis>SchemaExport</emphasis>
        tambi&#x00e9;n conocido como <literal>hbm2ddl</literal>.
    </para>

    <sect1 id="toolsetguide-s1" revision="2">
        <title>Generaci&#x00f3;n autom&#x00e1;tica de esquemas</title>

        <para>
            Una utilidad de Hibernate puede generar DDL desde tus ficheros de mapeo. El esquema generado incluye
            restricciones de integridad referencial (claves primarias y for&#x00e1;neas) para las tablas de entidades y
            colecciones. Las tablas y secuencias tambi&#x00e9;n son creadas para los generadores de identificadores mapeados.
        </para>
        
        <para>
            <emphasis>Debes</emphasis> especificar un <literal>Dialecto</literal> SQL v&#x00ed;a la propiedad
            <literal>hibernate.dialect</literal> al usar esta herramienta, ya que el DDL es altamente espec&#x00ed;fico del
            vendedor.
        </para>

        <para>
            First, customize your mapping files to improve the generated schema.
        </para>

        <sect2 id="toolsetguide-s1-2" revision="1">
            <title>Personalizando el esquema</title>

            <para>
                Muchos elementos de mapeo de Hibernate definen un atributo opcional llamado <literal>length</literal>.
                Con este atributo puedes establecer el tama&#x00f1;o de una columna. (O, para tipos de datos
                num&#x00e9;ricos/decimales, la precisi&#x00f3;n.)
            </para>

            <para>
                Algunas etiquetas tambi&#x00e9;n aceptan un atributo <literal>not-null</literal> (para generar una restricci&#x00f3;n
                <literal>NOT NULL</literal> en columnas de tablas) y y un atributo <literal>unique</literal> (para generar
                restricciones <literal>UNIQUE</literal> en columnas de tablas).
            </para>

            <para>
                Algunas etiquetas aceptan un atributo <literal>index</literal> para especificar el nombre de un &#x00ed;ndice
                para esa columna. Se puede usar un atributo <literal>unique-key</literal> para agrupar columnas en una
                restricci&#x00f3;n de clave de una sola unidad. Actualmente, el valor especificado del atributo
                <literal>unique-key</literal> <emphasis>no</emphasis> es usado para nombrar la restricci&#x00f3;n, s&#x00f3;lo para
                agrupar las columnas en el fichero de mapeo.
            </para>
            
            <para>
                Ejemplos:
            </para>

            <programlisting><![CDATA[<property name="foo" type="string" length="64" not-null="true"/>

<many-to-one name="bar" foreign-key="fk_foo_bar" not-null="true"/>

<element column="serial_number" type="long" not-null="true" unique="true"/>]]></programlisting>

            <para>
                Alternativamente, estos elementos aceptan tamb&#x00ed;en un elemento hijo <literal>&lt;column&gt;</literal>.
                Esto es particularmente &#x00fa;til para tipos multicolumnas:
            </para>

            <programlisting><![CDATA[<property name="foo" type="string">
    <column name="foo" length="64" not-null="true" sql-type="text"/>
</property>]]></programlisting>

            <programlisting><![CDATA[<property name="bar" type="my.customtypes.MultiColumnType"/>
    <column name="fee" not-null="true" index="bar_idx"/>
    <column name="fi" not-null="true" index="bar_idx"/>
    <column name="fo" not-null="true" index="bar_idx"/>
</property>]]></programlisting>

            <para>
                El atributo <literal>sql-type</literal> permite al usuario sobrescribir el mapeo por defecto de
                tipo Hibernate a tipo de datos SQL.
            </para>
            
            <para>
                El atributo <literal>check</literal> te permite especificar una comprobaci&#x00f3;n de restricci&#x00f3;n.
            </para>
            
            <programlisting><![CDATA[<property name="foo" type="integer">
    <column name="foo" check="foo > 10"/>
</property>]]></programlisting>

            <programlisting><![CDATA[<class name="Foo" table="foos" check="bar < 100.0">
    ...
    <property name="bar" type="float"/>
</class>]]></programlisting>
            

            <table frame="topbot" id="schemattributes-summary" revision="2">
                <title>Resumen</title>
                <tgroup cols="3">
                    <colspec colwidth="1*"/>
                    <colspec colwidth="1*"/>
                    <colspec colwidth="2.5*"/>
                    <thead>
                        <row>
                            <entry>Atributo</entry>
                            <entry>Valores</entry>
                            <entry>Interpretaci&#x00f3;n</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry><literal>length</literal></entry>
                            <entry>number</entry>
                            <entry>largo de columna/precisi&#x00f3;n decimal</entry>
                        </row>
                        <row>
                            <entry><literal>not-null</literal></entry>
                            <entry><literal>true|false</literal></entry>
                            <entry>especifica que la columna debe ser no nulable</entry>
                        </row>
                        <row>
                            <entry><literal>unique</literal></entry>
                            <entry><literal>true|false</literal></entry>
                            <entry>especifica que la columna debe tener una restricci&#x00f3;n de unicidad</entry>
                        </row>
                        <row>
                            <entry><literal>index</literal></entry>
                            <entry><literal>index_name</literal></entry>
                            <entry>especifica el nombre de un &#x00ed;ndice (multicolumna)</entry>
                        </row>
                        <row>
                            <entry><literal>unique-key</literal></entry>
                            <entry><literal>unique_key_name</literal></entry>
                            <entry>especifica el nombre de una restricci&#x00f3;n de unicidad multicolumna</entry>
                        </row>
                        <row>
                            <entry><literal>foreign-key</literal></entry>
                            <entry><literal>foreign_key_name</literal></entry>
                            <entry>
                                especifica el nombre de la restricci&#x00f3;n de clave for&#x00e1;nea generada por una
                                asociaci&#x00f3;n, &#x00fa;salo en los elementos de mapeo &lt;one-to-one&gt;, &lt;many-to-one&gt;,
                                &lt;key&gt;, y &lt;many-to-many&gt;. Nota que los lados
                                <literal>inverse="true"</literal> no ser&#x00e1;n considerados por
                                <literal>SchemaExport</literal>.
                            </entry>
                        </row>
                        <row>
                            <entry><literal>sql-type</literal></entry>
                            <entry><literal>column_type</literal></entry>
                            <entry>
                                sobrescribe el tipo de columna por defecto (s&#x00f3;lo atributo del elemento
                                <literal>&lt;column&gt;</literal>)
                            </entry>
                       </row>
                       <row>
                            <entry><literal>check</literal></entry>
                            <entry>expresi&#x00f3;n SQL</entry>
                            <entry>
                                crea una restricci&#x00f3;n de comprobaci&#x00f3;n SQL en columna o  tabla
                            </entry>
                       </row>
                   </tbody>
                </tgroup>
            </table>
            
            <para>
                El elemento <literal>&lt;comment&gt;</literal> te permite especificar un comentario para el esquema
                generado.
            </para>
            
            <programlisting><![CDATA[<class name="Customer" table="CurCust">
    <comment>Current customers only</comment>
    ...
</class>]]></programlisting>

            <programlisting><![CDATA[<property name="balance">
    <column name="bal">
        <comment>Balance in USD</comment>
    </column>
</property>]]></programlisting>
            
            <para>
                Esto resulta en una sentencia <literal>comment on table</literal> o <literal>comment on column</literal>
                en el DDL generado (donde est&#x00e9; soportado).
            </para>

        </sect2>

        <sect2 id="toolsetguide-s1-3">
            <title>Ejecutando la herramienta</title>

            <para>
                La herramienta <literal>SchemaExport</literal> escribe un gui&#x00f3;n DDL a la salida est&#x00e1;ndar y/o
                ejecuta las sentencias DDL.
            </para>

            <para>
                <literal>java -cp </literal><emphasis>classpaths_de_hibernate</emphasis>
                <literal>org.hibernate.tool.hbm2ddl.SchemaExport</literal> <emphasis>opciones ficheros_de_mapeo</emphasis>
            </para>

            <table frame="topbot">
                <title>Opciones de L&#x00ed;nea de Comandos de <literal>SchemaExport</literal></title>
                <tgroup cols="2">
                    <colspec colwidth="1.5*"/>
                    <colspec colwidth="2*"/>
                    <thead>
                        <row>
                            <entry>Opci&#x00f3;n</entry>
                            <entry>Descripci&#x00f3;n</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry><literal>--quiet</literal></entry>
                            <entry>no enviar a salida est&#x00e1;ndar el gui&#x00f3;n</entry>
                        </row>
                        <row>
                            <entry><literal>--drop</literal></entry>
                            <entry>s&#x00f3;lo desechar las tablas</entry>
                        </row>
                        <row>
                            <entry><literal>--text</literal></entry>
                            <entry>no exportar a la base de datos</entry>
                        </row>
                        <row>
                            <entry><literal>--output=my_schema.ddl</literal></entry>
                            <entry>enviar la salida del gui&#x00f3;n ddl a un fichero</entry>
                        </row>
                        <row>
                            <entry><literal>--config=hibernate.cfg.xml</literal></entry>
                            <entry>lee la configuraci&#x00f3;n de Hibernate de un fichero XML</entry>
                        </row>
                        <row>
                            <entry><literal>--properties=hibernate.properties</literal></entry>
                            <entry>lee las propiedades de base de datos de un fichero</entry>
                        </row>
                        <row>
                            <entry><literal>--format</literal></entry>
                            <entry>formatea agradablemente el SQL generado en el gui&#x00f3;n</entry>
                        </row>
                        <row>
                            <entry><literal>--delimiter=x</literal></entry>
                            <entry>establece un delimitador de fin de l&#x00ed;nea para el gui&#x00f3;n</entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

            <para>
                Puedes incluso encajar <literal>SchemaExport</literal> en tu aplicaci&#x00f3;n:
            </para>

            <programlisting><![CDATA[Configuration cfg = ....;
new SchemaExport(cfg).create(false, true);]]></programlisting>

        </sect2>

        <sect2 id="toolsetguide-s1-4">
            <title>Propiedades</title>

            <para>
                Las propiedades de base de datos pueden especificarse
            </para>

            <itemizedlist spacing="compact">
                <listitem>
                    <para>como propiedades de sistema con <literal>-D</literal><emphasis>&lt;property&gt;</emphasis></para>
                </listitem>
                <listitem>
                    <para>en <literal>hibernate.properties</literal></para>
                </listitem>
                <listitem>
                    <para>en un fichero de propiedades mencionado con <literal>--properties</literal></para>
                </listitem>
            </itemizedlist>

            <para>
                Las propiedades necesarias son:
            </para>

            <table frame="topbot">
                <title>Propiedades de Conexi&#x00f3;n de SchemaExport</title>
                <tgroup cols="2">
                    <colspec colwidth="1.5*"/>
                    <colspec colwidth="2*"/>
                    <thead>
                        <row>
                            <entry>Nombre de Propiedad</entry>
                            <entry>Descripci&#x00f3;n</entry>
                        </row>
                    </thead>
                    <tbody>
                    <row>
                        <entry><literal>hibernate.connection.driver_class</literal></entry>
                        <entry>clase del driver jdbc</entry>
                    </row>
                    <row>
                        <entry><literal>hibernate.connection.url</literal></entry>
                        <entry>url de jdbc</entry>
                    </row>
                    <row>
                        <entry><literal>hibernate.connection.username</literal></entry>
                        <entry>usuario de base de datos</entry>
                    </row>
                    <row>
                        <entry><literal>hibernate.connection.password</literal></entry>
                        <entry>contrase&#x00f1;a de usuario</entry>
                    </row>
                    <row>
                        <entry><literal>hibernate.dialect</literal></entry>
                        <entry>dialecto</entry>
                    </row>
                    </tbody>
                </tgroup>
            </table>

        </sect2>

        <sect2 id="toolsetguide-s1-5">
            <title>Usando Ant</title>

            <para>
                Puedes llamar a <literal>SchemaExport</literal> desde tu gui&#x00f3;n de construcci&#x00f3;n de Ant:
            </para>

            <programlisting><![CDATA[<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>]]></programlisting>

        </sect2>

        <sect2 id="toolsetguide-s1-6">
            <title>Actualizaciones incrementales de esquema</title>

            <para>
                La herramienta <literal>SchemaUpdate</literal> actualizar&#x00e1; un esquema existente con cambios
                "incrementales". Nota que <literal>SchemaUpdate</literal> depende fuertemente de la API de metadatos
                de JDBC, de modo que no funcionar&#x00e1; con todos los drivers JDBC.
            </para>

            <para>
                <literal>java -cp </literal><emphasis>classpaths_de_hibernate</emphasis>
                <literal>org.hibernate.tool.hbm2ddl.SchemaUpdate</literal> <emphasis>opciones ficheros_de_mapeo</emphasis>
            </para>

            <table frame="topbot">
                <title>Opciones de L&#x00ed;nea de Comandos de <literal>SchemaUpdate</literal></title>
                <tgroup cols="2">
                    <colspec colwidth="1.5*"/>
                    <colspec colwidth="2*"/>
                    <thead>
                        <row>
                            <entry>Opci&#x00f3;n</entry>
                            <entry>Descripci&#x00f3;n</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry><literal>--quiet</literal></entry>
                            <entry>no enviar a salida est&#x00e1;ndar el gui&#x00f3;n</entry>
                        </row>
                        <row>
                            <entry><literal>--properties=hibernate.properties</literal></entry>
                            <entry>lee las propiedades de base de datos de un fichero</entry>
                        </row>
                     </tbody>
                </tgroup>
            </table>

            <para>
                Puedes encajar <literal>SchemaUpdate</literal> en tu aplicaci&#x00f3;n:
            </para>

            <programlisting><![CDATA[Configuration cfg = ....;
new SchemaUpdate(cfg).execute(false);]]></programlisting>

        </sect2>

        <sect2 id="toolsetguide-s1-7">
            <title>Usando Ant para actualizaciones incrementales de esquema</title>

            <para>
                Puedes llamar a <literal>SchemaUpdate</literal> desde el gui&#x00f3;n de Ant:
            </para>

            <programlisting><![CDATA[<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>]]></programlisting>

        </sect2>

    </sect1>

</chapter>