 | Gerando Ligação Padrão e Esquema a partir do Código
| Uso de Não-Java 5
O código de exemplo do tutorial usa recursos de coleta e enum por tipo Java 5, mas o próprio JiBX é totalmente compatível com versões mais antigas de Java. O tempo de execução padrão de JiBX funciona com JVMs 1.3 e posteriores e também pode ser construído para compatibilidade com J2ME. A maioria dos outros componentes de JiBX, incluindo BindGen, pode ser executada em JVMs 1.4.1 e posterior. A documentação de BindGen no download de JiBX inclui um exemplo mostrando como as customizações podem fornecer a BindGen o equivalente de coletas por tipo quando você usa código pré-Java 5.
|
|
É fácil gerar uma definição de ligação JiBX e a definição do esquema XML correspondente, a partir do código Java. Você aprenderá como nesta seção.
Introduzindo o Código de Exemplo Java
Como um exemplo, vou iniciar com o código Java para um conjunto de classes estilo bean (campos privados, métodos de acesso público get e set) usadas para representarem um pedido de uma loja on-line.
A Listagem 1 mostra uma versão abreviada do código, com a maioria dos métodos get/set deixados de fora. O código de amostra integral está no diretório src do código de amostra.
Listagem 1. Código Java Base
package org.jibx.starter;
/**
* Informações de pedido.
*/
public class Order
{
private long orderNumber;
private Customer customer;
/** Informações do endereço para cobrança. */
private Address billTo;
private Shipping shipping;
/** Informações do endereço de remessa. Se estiver faltando, o endereço para cobrança também é usado como o endereço de remessa. */
|-------10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- Erro XML: A linha anterior não é maior do que o máximo de 90 caracteres ---------|
private Address shipTo;
private List<Item> items;
/** Data em que o pedido foi colocado no servidor. */
private Date orderDate;
/** Data em que o pedido foi enviado. Será <code>null</code> se o pedido ainda não foi enviado. */
|-------10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- Erro XML: A linha anterior não é maior do que o máximo de 90 caracteres ---------|
private Date shipDate;
private Float total;
public long getOrderNumber() {
return orderNumber;
}
...
}
/**
* Informações do cliente.
*/
public class Customer
{
private long customerNumber;
/** Nome pessoal. */
private String firstName;
/** Nome de família. */
private String lastName;
/** Nome do meio, se houver. */
private List<String> middleNames;
...
}
/**
* Informações de endereço.
*/
public class Address
{
/** Primeira linha de informações de rua (necessário). */
private String street1;
/** Segunda linha de informações de rua (opcional). */
private String street2;
private String city;
/** Abreviação de estado (necessário para os EUA e Canadá, do contrário, opcional). */
private String state;
/** Código de endereçamento postal (necessário para os EUA e Canadá, do contrário, opcional). */
|-------10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- Erro XML: A linha anterior não é maior do que o máximo de 90 caracteres ---------|
private String postCode;
/** Nome do país (opcional, supõe-se EUA se não fornecido). */
private String country;
...
}
/**
* Informações do item de linha do pedido.
*/
public class Item
{
/** Identificador de estoque. Espera-se que tenha 12 caracteres de comprimento, com dois caracteres alfa à esquerda seguidos por dois dígitos decimais.
|-------10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- Erro XML: A linha anterior não é maior do que o máximo de 90 caracteres ---------|
*/
private String id;
/** Descrição de texto do item. */
private String description;
/** Número de unidades pedidas. */
private int quantity;
/** Preço unitário. */
private float price;
...
}
/**
* Métodos suportados de envio. Os métodos de envio "INTERNATIONAL" podem ser usados somente para
|-------10--------20--------30--------40--------50--------60--------70--------80--------9|
|-------- Erro XML: A linha anterior não é maior do que o máximo de 90 caracteres ---------|
* pedidos com endereços de remessa fora dos EUA e um desses métodos é necessário
* nesse caso.
*/
public enum Shipping
{
STANDARD_MAIL, PRIORITY_MAIL, INTERNATIONAL_MAIL, DOMESTIC_EXPRESS,
INTERNATIONAL_EXPRESS
} |
 |
Gerando a Ligação e o Esquema Padrão
Para gerar uma ligação JiBX e um esquema XML a partir de algumas classes Java, você primeiro precisa compilar as classes, em seguida, executar a ferramenta org.jibx.binding.generator.BindGen incluída no jibx-tools.jar a partir da distribuição JiBX. Você pode executar a ferramenta diretamente a partir da linha de comandos ou indiretamente através de uma ferramenta de construção, como Ant.
O download do tutorial inclui um script Ant build.xml com o destino compile para compilar o código de exemplo e o destino bindgen para executar o programa BindGen no código compilado.
Para testar isso, abra um console no diretório dwcode1 do download instalado e digite ant compile bindgen. Se você tiver Ant instalado em seu sistema e tiver instalado o código de download de acordo com as instruções, você deve ver saída semelhante à mostrada na Figura 1:
Figura 1. Usando a Construção Ant
Você também pode executar BindGen diretamente a partir do console. Para fazer isso, é necessário incluir jibx-tools.jar em seu caminho de classe Java, juntamente com o caminho para os arquivos de classe compilados que você usará como entrada para a geração. Se você quiser duplicar o efeito do destino Ant bindgen fornecido, você também precisa passar o diretório-raiz para os arquivos de origem de suas classe na linha de comando. Por fim, é necessário listar as classes-raiz que deseja usar para a geração. Nos sistemas UNIX® e Linux® , a linha de comando Java (que consiste em uma única linha, mesmo se aparecer quebrada em sua exibição) para duplicar o destino Ant bindgen a partir de um console no diretório dwcode1 (supondo que você tenha seguido as instruções de instalação recomendadas) é:
java -cp ../lib/jibx-tools.jar:bin org.jibx.binding.generator.BindGen
-s src org.jibx.starter.Order |
No Windows, o comando (uma única linha, independentemente de sua aparência aqui) é:
java -cp ..\lib\jibx-tools.jar;bin org.jibx.binding.generator.BindGen
-s src org.jibx.starter.Order |
Muitas outras opções podem ser passadas para BindGen a partir da linha de comando. Você dará uma olhada neles posteriormente no tutorial.
Agora, vamos dar uma olhada no esquema gerado.
Artefatos Gerados
A Listagem 2 mostra a saída do esquema gerada a partir de BindGen (como starter.xsd), ligeiramente reformatada para se ajustar à largura da página e com alguns detalhes removidos. A tag inicial para a definição do esquema que corresponde a cada classe Java é exibida em negrito para enfatizar a estrutura.
Listagem 2. Esquema Gerado
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://jibx.org/starter" elementFormDefault="qualified"
targetNamespace="http://jibx.org/starter">
<xs:complexType name="address">
<xs:annotation>
<xs:documentation>Address information.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element type="xs:string" name="street1" minOccurs="0">
<xs:annotation>
<xs:documentation>First line of street information (required).</xs:documentation>
</xs:annotation>
</xs:element>
...
</xs:sequence>
</xs:complexType>
<xs:element type="tns:order" name="order"/>
<xs:complexType name="order">
<xs:annotation>
<xs:documentation>Order information.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="customer" minOccurs="0">
<xs:complexType>
...
</xs:complexType>
</xs:element>
<xs:element type="tns:address" name="billTo" minOccurs="0">
<xs:annotation>
<xs:documentation>Billing address information.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="shipping" minOccurs="0">
<xs:simpleType>
<xs:annotation>
<xs:documentation>Supported shipment methods. The "INTERNATIONAL" shipment methods
can only be used for orders with shipping addresses outside the U.S., and one of
these methods is required in this case.</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:enumeration value="STANDARD_MAIL"/>
...
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element type="tns:address" name="shipTo" minOccurs="0">
<xs:annotation>
<xs:documentation>Shipping address information. If missing, the billing address is
also used as the shipping address.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="item" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element type="xs:string" name="id" minOccurs="0">
<xs:annotation>
<xs:documentation>Stock identifier. This is expected to be 12 characters in
length, with two leading alpha characters followed by ten decimal
digits.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element type="xs:string" name="description" minOccurs="0">
<xs:annotation>
<xs:documentation>Text description of item.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute type="xs:int" use="required" name="quantity">
<xs:annotation>
<xs:documentation>Number of units ordered.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:float" use="required" name="price">
<xs:annotation>
<xs:documentation>Price per unit.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute type="xs:long" use="required" name="orderNumber"/>
<xs:attribute type="xs:date" name="orderDate">
<xs:annotation>
<xs:documentation>Date order was placed with server.</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute type="xs:date" name="shipDate">
<xs:annotation>
<xs:documentation>
<![CDATA[Date order was shipped. This will be <code>null</code> if the order
has not yet shipped.]]></xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
</xs:schema> |
Por padrão, BindGen gera um esquema com definições complexType e simpleType aninhadas para tipos que são usados somente uma vez e definições separadas para tipos que são usados mais de uma vez. Nesse caso, o estilo aninhado resulta em um esquema com somente três definições globais: os tipos complexos address e order e o elemento order . A classe Address é usada em dois locais na classe Order (para endereços para cobrança e de remessa), por isso essa classe é representada por uma definição global separada no esquema. (O esquema permite reutilizar as definições somente se forem globais.) As outras classes da estrutura de dados Java (Customer, Item e Shipping) são referidas, cada uma, em somente um ponto da classe Order , portanto, as definições de tipo correspondente são integradas diretamente na definição de tipo de esquema order .
Um dos melhores recursos de BindGen é que pode gerar documentação de esquema a partir de Javadocs nas classes de entrada. Você pode ver a documentação do esquema na Listagem 2 para cada campo com um Javadoc na Listagem 1 e para cada tipo global correspondente a uma classe com um Javadoc. Nem todos os formulários de Javadocs podem ser correspondidos com os componentes do esquema através da manipulação padrão de BindGen — e alguns Javadocs, como aqueles nos métodos de acesso "get", podem parecer estranhos quando convertidos para a documentação do esquema — mas a documentação do esquema resultante pode ser extremamente útil para esclarecer o uso apropriado da representação XML. Você pode até mesmo definir sua própria classe do formatador para Javadocs usados como documentação do esquema, se você quiser fazer algumas mudanças no texto no processo de conversão (como remover as sentenças de entrada "Get the ..." dos Javadocs do método "get").
Esse recurso de conversão de Javadoc funciona somente se você tiver o código de origem disponível para as classes e fornecer um argumento para BindGen indicando o caminho 0(ou caminhos) do código de origem. Nas amostras da linha de comando que forneci anteriormente (consulte Gerando a Ligação e o Esquema Padrão), o caminho de origem é fornecido como -s src.
Ligação JiBX Gerada
Além da definição do esquema, BindGen também produz uma definição de ligação JiBX (como o arquivo binding.xml, neste caso) que indica ao compilador de ligação JiBX como fazer a conversão entre as classes Java e XML. Essa definição de ligação é realmente a saída principal de BindGen, com o esquema gerado a partir da ligação. As definições de ligação contêm detalhes integrais das conversões a serem feitas por JiBX, portanto, são necessariamente complexas. Felizmente, não é necessário entender a definição de ligação para trabalhar com JiBX usando geração de ligação e esquema BindGen, de forma que esse tutorial não cubra os detalhes.
| |
