Hibernate.org Community Documentation

- Anterior
- Próxima

## Capítulo 22. Guia de Toolset

É possível realizar uma engenharia de roundtrip com o Hibernate, usando um conjunto de plug-ins de Eclipse, ferramentas de linha de comando, assim como tarefas Ant.

As Ferramentas do Hibernate atualmente incluem os plug-ins para o IDE de Eclipse assim como as tarefas para reverter a engenharia dos bancos de dados existentes:

- Editor de Mapeamento: um editor para mapeamento de arquivos XML do Hibernate, suportando a auto complexão e destaque de sintáxe. Ele também suporta a auto complexão da semântica para nomes de classes e nomes de propriedade/campo, fazendo com que ele seja mais versátil do que um editor XML normal.

- Console: o console é uma nova visão em Eclipse. Além disso, para uma visão geral de árvore de suas configurações de console, você também pode obter uma visão interativa de suas classes persistentes e seus relacionamentos. O console permite que você execute as consultas HQL junto ao banco de dados e navegue o resultado diretamente em Eclipse.

- Assistentes de Desenvolvimento: são oferecidos diversos assistentes com as ferramentas de Eclipse do Hibernate. Você pode usar o assistente para gerar rapidamente arquivos de configuração do Hibernate (cfg.xml), ou você pode também reverter completamente o engenheiro, um esquema de banco de dados existente, para arquivos de fonte POJO e arquivos de mapeamento do Hibernate. O assistente de engenharia reversa suporta modelos padronizáveis.

Por favor, consulte o pacote Ferramentas do Hibernate e suas documentações para maiores informações.

No entanto, o pacote principal do Hibernate vem em lote com uma ferramenta integrada: SchemaExport aka `hbm2ddl`. Ele pode também ser usado dentro do Hibernate.

## 22.1. Geração de esquema automático

O DDL pode ser gerado a partir dos arquivos de mapeamento através dos utilitários do Hibernate. O esquema gerado inclui as restrições de integridade referencial, primária e chave estrangeira, para entidade e tabela de coleção. Tabelas e seqüência são também criadas por geradores de identificador mapeado.

Você deve especificar um SQL `Dialect` através da propriedade `hibernate.dialect` ao usar esta ferramenta, uma vez que o DDL é um fabricante bastante específico.

Primeiro, padronize seus arquivos de mapeamento para melhorar o esquema gerado. A próxima seção cobrirá a personalização do esquema.

### 22.1.1. Padronizando o esquema

Muitos elementos de mapeamento do Hibernate definem funções opcionais nomeadas `length`, `precision` e `scale`. Você deve ajustar o length, precision e scale de uma coluna com esta função.

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

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

Algumas tags aceitam uma função `not-null` para gerar uma restrição `NOT NULL`nas colunas de tabela e uma função `unique` para gerar uma restrição `UNIQUE` em colunas de tabela.

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

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

Uma função `unique-key` pode ser usada para agrupar colunas em uma restrição de chave única. Atualmente, o valor específico da função `unique-key` não é usada para nomear a restrição no DDL gerado, somente para agrupar as colunas no arquivo de mapeamento.

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

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

Uma função `index` especifica o nome de um indexe que será criado, usando a coluna ou colunas mapeada(s). As colunas múltiplas podem ser agrupadas no mesmo indexe, simplesmente especificando o mesmo nome de índice.

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

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

Uma função `foreign-key` pode ser usada para sobrescrever o nome de qualquer restrição de chave exterior gerada.

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

Muitos elementos de mapeamento também aceitam um elemento filho `<column>`. Isto é particularmente útil para mapeamento de tipos multi-colunas:

    <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

    >

A função `default` deixa você especificar um valor padrão para uma coluna. Você deve atribuir o mesmo valor à propriedade mapeada antes de salvar uma nova instância da classe 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

    >

A função `sql-type` permite que o usuário sobrescreva o mapeamento padrão de um tipo de Hibernate para um tipo de dados SQL.

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

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

    </property

    >

A função `check` permite que você especifique uma restrição de verificação.

    <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

    >

A seguinte tabela resume estes atributos opcionais.

Tabela 22.1. Sumário

Função | Valores | Interpretação
--- | --- | ---
`length` | número | comprimento da coluna
`precision` | número | precisão da coluna decimal
`scale` | número | escaça de coluna decimal
`not-null` | `true|false` | especifica que a coluna deveria ser não anulável
`unique` | `true|false` | especifica que a coluna deveria ter uma restrição única
`index` | `index_name` | especifica o nome de um índice (multi-coluna)
`unique-key` | `unique_key_name` | especifica o nome de uma restrição única de coluna múltipla
`foreign-key` | `foreign_key_name` | especifica o nome da restrição de chave estrangeira gerada para uma associação, por um elemento de mapeamento `<one-to-one>`, `<many-to-one>`, `<key>`, ou `<many-to-many>`. Note que os lados `inverse="true"` não serão considerados pelo `SchemaExport`.
`sql-type` | `SQL column type` | sobrescreve o tipo de coluna padrão (função do elemento `<column>`somente)
`default` | Expressão SQL | especifica um valor padrão para a coluna
`check` | Expressão SQL | cria uma restrição de verificação de SQL tanto na coluna quanto na tabela

O elemento `<comment>` permite que você especifique comentários para esquema gerado.

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

        <comment

    >Current customers only</comment>

        ...

    </class

    >

    <property name="balance">

        <column name="bal">

            <comment

    >Balance in USD</comment>

        </column>

    </property

    >

Isto resulta em uma instrução `comment on table` ou `comment on column` no DDL gerado, onde é suportado.

### 22.1.2. Executando a ferramenta

A ferramenta `SchemaExport` escreve um script DDL para padronizar e/ou para executar as instruções DDL.

A seguinte tabela exibe as opções de linha de comando do `SchemaExport`

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

Tabela 22.2. `SchemaExport` Opções de Linha de Comando

Opção | Descrição
--- | ---
`--quiet` | não saia do script para stdout
`--drop` | somente suspenda as tabelas
`--create` | somente crie tabelas
`--text` | não exporte para o banco de dados
`--output=my_schema.ddl` | saia do script ddl para um arquivo
`--naming=eg.MyNamingStrategy` | seleciona um `NamingStrategy`
`--config=hibernate.cfg.xml` | leia a configuração do Hibernate a partir do arquivo XML
`--properties=hibernate.properties` | leia propriedades de banco de dados a partir dos arquivos
`--format` | formatar bem o SQL gerado no script
`--delimiter=;` | ajustar e finalizar o delimitador de linha para o script

Você pode até mesmo incorporar o `SchemaExport` em sua aplicação:

    Configuration cfg = ....;

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

### 22.1.3. Propriedades

As Propriedades do Banco de Daods podem ser especificadas:

- Como Propriedades de sistema com `-D`<property>

- em `hibernate.properties`

- em um arquivo de propriedades nomeadas com `--properties`

As propriedades necessárias são:

Tabela 22.3. SchemaExport Connection Properties

Nome de Propriedade | Descrição
--- | ---
`hibernate.connection.driver_class` | classe de driver jdbc
`hibernate.connection.url` | jdbc url
`hibernate.connection.username` | usuário de banco de dados
`hibernate.connection.password` | senha do usuário
`hibernate.dialect` | dialeto

### 22.1.4. Usando o Ant

Você pode chamar o `SchemaExport` a partir de seu script de construção do 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. Atualizações de esquema incremental

A ferramenta `SchemaUpdate` irá atualizar um esquema existente com mudanças "incrementais". Observe que `SchemaUpdate` depende totalmente da API de metadados JDBC, portanto não irá funcionar com todos os driver JDBC.

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

Tabela 22.4. `SchemaUpdate`Opções de Linha de Comando

Opção | Descrição
--- | ---
`--quiet` | não saia do script para stdout
`--text` | não exporte o script ao banco de dados
`--naming=eg.MyNamingStrategy` | seleciona um `NamingStrategy`
`--properties=hibernate.properties` | leia propriedades de banco de dados a partir dos arquivos
`--config=hibernate.cfg.xml` | especifique um arquivo `.cfg.xml`

Você pode incorporar o `SchemaUpdate` em sua aplicação:

    Configuration cfg = ....;

    new SchemaUpdate(cfg).execute(false);

### 22.1.6. Utilizando Ant para atualizações de esquema incremental

Você pode chamar `SchemaUpdate` a partir do script 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. Validação de esquema

A ferramenta `SchemaValidator` irá confirmar que o esquema de banco de dados existente "combina" com seus documentos de mapeamento. Observe que o `SchemaValidator` depende totalmente da API de metadados JDBC, portanto ele não funcionará com todos os drivers JDBC. Esta ferramenta é extremamente útil para teste.

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

A seguinte tabela exibe as opções de linha de comando do `SchemaValidator`:

Tabela 22.5. `SchemaValidator` Opções de Linha de Comando

Opção | Descrição
--- | ---
`--naming=eg.MyNamingStrategy` | seleciona um `NamingStrategy`
`--properties=hibernate.properties` | leia propriedades de banco de dados a partir dos arquivos
`--config=hibernate.cfg.xml` | especifique um arquivo `.cfg.xml`

Você pode incorporar o `SchemaValidator` em sua aplicação:

    Configuration cfg = ....;

    new SchemaValidator(cfg).validate();

### 22.1.8. Utilizando Ant para validação de esquema

Você pode chamar o `SchemaValidator` a partir do script 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. Aumentando o desempenho
- Acima
- Principal
- PróximaCapítulo 23. Additional modules