Tutorial do Xdoclet
Resumo
Apresentar a ferramenta XDoclet – uma ferramenta utilizada como
tarefa (task) do Jakarta Ant que permite executar e criar templates para gerar
arquivos, inclusive código Java, reduzindo o tempo de desenvolvimento pois
todos os esforços são direcionados para a regra de negócios, facilitando o
trabalho do desenvolvedor que com um mínimo de esforço adiciona ao código
tags para representar coisas que a linguagem Java não consegue expressar,
como relações entre as várias partes de um Enterprise JavaBeans: as
interfaces, as classes de implementação e os deployment descriptor, arquivos
de mapeamento dos frameworks de persistência objeto-relacional e a
integração com os servidores de aplicações, JBoss, Bea WebLogic , etc.
Introdução
É comum um projeto de software ser composto de diferentes arquivos,
como: arquivos de publicação da aplicação (deployment descriptor), arquivos
de mapeamento objeto-relacional, de componentes (ejb-jar.xml, web.xml,
*.hbm.xml (hibernate)), além de códigos Java que como são baseados em
padrões (design patterns) repetem freqüentemente, o que acaba tornando o
desenvolvimento mais trabalhoso e repetitivo. Nestas circunstâncias o
desenvolvedor recorre ao recurso de copiar (Ctrl+C) e colar (Ctrl + V), que
não é nada muito produtivo, e que propícia uma grande margem de erros. A
idéia é eliminar este trabalho repetitivo e descentralizado através de alguma
ferramenta de geração automática de código, deixando que todo o esforço do
desenvolvimento seja direcionado para a lógica de negócio. Hoje o XDoclet
posiciona como uma ótima ferramenta para a realização deste trabalho
repetitivo.
O XDoclet é uma ferramenta puro Java que habilita a programação
orientada a atributos, que com um mínimo de esforço permite a geração de
código Java ou arquivo texto inclusive XML, com base em @tags
semelhantes às utilizadas pela ferramenta javadoc da Sun. As tags adicionam
metadados ao código, são esses metadados a fonte de informação para a
geração de arquivos e códigos utilizando os templates disponíveis. No entanto
ela só pode ser utilizada como parte do processo de build da ferramenta
Jakarta Ant.
O Xdoclet é uma evolução da ferramenta de criação de EJBs (Entreprise
JavaBeans), ejbdoclet, criada por Richard Öberg, que gerava interfaces de
componentes e seus deployment descriptors. O ejbdoclet ganhou força, e com
a idéia de levar a geração automática de código a outras áreas da programação
surgiu o Xdoclet.
A principal vantagem do desenvolvimento utilizando o XDoclet é a
centralização da informação. Tudo o que é preciso saber sobre um
componente fica em um único local, a classe de implementação do
componente, mudanças no componente acarreta mudanças automáticas em
suas dependências.
Arquitetura do XDoclet
No centro do Xdoclet, está o template engine (mecanismo de templates)
. Os templates são escritos numa sintaxe particular ao Xdoclet
convencionalmente possuem a extensão “*.j” e se assemelham, as estruturas
a de documentos JSP (Java Server Pages). Eles fazem uso do tag handlers
(manipuladores de tags), classes que fornecem os dados necessários para o
templates. Nas tags de templates é permitidos inserir variáveis de
configuração, informações de classes, métodos, tipos, dados de arquivos, tags
do javadoc, etc. Ligado ao tag handlers está o xjavadoc, um analisador de
código Java, responsável por fornecer ao handlers informações sobre as tags
utilizadas na marcação do código fonte
A execução de um template do XDoclet segue o fluxo: o engine carrega
um template, identifica os tags handlers utilizado e executa-os a medida que
prossegue analisando o template. Os handlers fazem uso do xjavadoc para
obter as informações necessárias as @tags e geram no resultado final.
Esta arquitetura torna-o bastante flexível, se necessário for, pode-se
modificar a forma como é gerado algum elemento, para isso basta modificar o
template responsável por gera-lo, ou se algum template para a representação
de algum elemento ainda não existir , basta escrever o template e
opcionalmente alguns tag handlers.
Pré Requisitos
Para executar o Xdoclet é necessário ter o ambiente de desenvolvimento Java configurado corretamente (variáveis JAVA_HOME e CLASSPATH) da versão 1.4 (J2SDK 1.4+) ou superior e utilizar a versão do Jakarta Ant 1.5 ou superior, versões anteriores não são suportadas. No entanto os fontes (sources) compilados poderão ser executadas no J2SDK 1.3 ou superior.
Download
Baixe a versão mais recente do arquivo xdoclet-bin<versão>.zip no endereço
http://sourceforge.net/project/showfiles.php?group_id=31602. Neste pacote encontram-se vários arquivos .jar, que são as bibliotecas necessárias e as classes do XDoclet, documentação, exemplos e uma versão pré-compilada do XDoclet. Descompacte o arquivo zip em algum diretório de sua escolha e for preservada a estrutura de diretório, ela será como mostra a figura abaixo
docs – diretório com toda a documentação que
acompanha a ferramenta. Para visualiza-la aponte o
browser para o arquivo index.html.
lib -bibliotecas necessárias para a execução do Xdoclet.
samples – exemplo que acompanha o Xdoclet para
visualiza-lo é necessário executa-lo através do Ant.
Como o XDoclet é utilizado como uma tarefa do Ant é preciso escrever
um arquivo build.xml (buildfile) que chame as funcionalidades do Xdoclet.
Como usar XDoclet através do Ant
· Primeiro escolha uma das tarefas do Xdoclet para o Ant; · As quatro principais tarefas são
o xdoclet.DocletTask - tarefa genérica; serve de superclasse para as outras o xdoclet.doc.DocumentDocletTask
o xdoclet.ejb.EjbDocletTask o xdoclet.web.WebDocletTask
· Cada tag tem um conjunto de atributos aceitos e um conjunto de tags internos com seus atributos. Para obter mais informações consulte a documentação de referência; · Depois crie uma tag usando a tarefa<taskdef>
<taskdef
name="xdoclet"
classname="xdoclet.DocletTask"> <classpathref ="xdoclet.path" /> </taskdef>
No exemplo acima foi definido uma tarefa com o nome de xdoclet utilizando a
DocletTask, que requer um sub-elemento <template> que descreva a geração do texto
conforme determina em sua construção e a localização do template. Os templates disponíveis estão localizados no diretório lib do xdoclet, são os arquivos JAR (Java Archive). Exemplo: xdoclet-bea-module-1.2b4.jar, xdoclet-orion-module-1.2b4.jar.
Exemplo de implementação
O exemplo que será utilizado para demonstrar a utilização do Xdoclet, será para a partir do código fonte Java gerar os arquivos de mapeamento do Hibernate. Para os que não conhecem o Hibernate é um frameworks de mapeamento objeto-relacional. Ao utiliza-lo você consegue abstrair a camada de persistência, além de acabar com a dependência da linguagem SQL (Structured Query Language) dos bancos de dados relacional. Este tutorial não tem a intenção de estudar o Hibernate. Deixo para uma outra oportunidade, ou obtenha maiores informações no site do projeto. Vide referência.
O exemplo apresentado é bastante simples, basicamente ele é composto de uma tabela chamada contatos, que terá a sua estrutura criada pelo XDoclet na base de sua preferência. Depois de criado ela terá a seguinte estrutura:
Id Nome Telefone
Estrutura da tabela contatos
Vamos primeiro escrever a classe acrescentando a elas as @tags (templates) disponíveis para o Hibernate. Foram omitidos do código os métodos setters, mas poderá s visualizar o código completo no arquivo fonte disponível para download.
package hotwork; /**
* Description of the Class * *@author alessandro.leite *@created 29 de Março de 2004 *@since 1.0 *@hibernate.class table="contatos" */
public class Contatos { private long id; private String nome;
private String fone; /**
* Gets the id attribute of the Contatos object *
*@return The id value
*@hibernate.id generator-class="native" */
public long getId() { return this.id; }
/**
* Gets the nome attribute of the Contatos object *
*@return The nome value *@hibernate.property
*/
public String getNome() { return this.nome; }
/**
* Gets the fone attribute of the Contatos object *
* @return The fone value * @hibernate.property
*/
public String getFone() { return this.fone; }
}
Com a classe pronta, partimos para escrever o arquivo de build (build file) do Ant, será através dele que conseguiremos interagir com o Xdoclet através da @tags inseridas no código. Abaixo segue trecho do arquivo de build, responsável por gerar os arquivos de mapeamento do Hibernate (*.hbm.xml).
<target name="generate-map" description= "Gerando os arquivos de mapeamento do Hibernate">
<taskdef name="hibernatedoclet"
classname="xdoclet.modules.hibernate.HibernateDocletTask"> <classpath>
<fileset dir= "${xdoclet.lib.dir}"> <include name= "*.jar"/>
</fileset> </classpath> </taskdef>
<mkdir dir= "${build.hbm.dir}"/> <hibernatedoclet destdir= "${build.hbm.dir}" excludedtags= "@version,@author,@todo" force= "true" verbose= "true"> <fileset dir= "${src.java.dir}"> <include name= "**/*.java"/>
<exclude name= "**/Hibernate*.java"/> </fileset>
<hibernate/> </hibernatedoclet>
<replace dir= "${build.hbm.dir}">
<include name= "**/hibernate/*.hbm.xml"/>
<replacefilter token = "readonly=" value= "inverse"/> <replacefilter token = "role=" value= "name="/> <replacefilter token = "hibernate-mapping.dtd" value= "hibernate-mapping-2.0.dtd"/>
</replace> </target>
Trecho do arquivo build.xml
Ferramentas
Para ajudar o desenvolvedor a utilizar as muitas @tags disponíveis no
XDoclet para os mais diferentes propósitos é crucial a integração com as
ferramentas de desenvolvimento disponíveis (Eclipse, Jbuilder, Jedit, etc). As
principais opções são:
¨ JBossIde – um plugin para o Eclipse que facilita o deployment de aplicações no
JBoss, e o desenvolvimento, oferecendo o recurso de completar o código automaticamente com as tags disponíveis. O download e maiores informações pode ser obtido no endereço: http://www.jboss.org/developers/projects/jboss/jbosside.jsp
¨
Xdocletgui – uma ferramenta gráfica para o desenvolvimento de
@tags. Ela tem disponível plugins para Eclipse, NetBeans, Intellig
IDEA, JBuilder. O download está disponível através do CVS do
Xdoclet.
¨ Middlegen – é uma ferramenta que possibilita através de uma conexão JDBC gerar
o script baseado na base de dados informado pelo driver JDBC. Com ele é possível gerar:
§ EJB (CMP 2.0) § JDO
§ JSP/Struts
Download e mais informação no http://middlegen.codehaus.org
Se você deseja obter mais informação sobre as ferramentas disponíveis, acesse o endereço: http://xdoclet.sourceforge.net/tools.html
Referência Bibliográfica
[1] Documentação no Xdoclet disponível em: http://xdoclet.sourceforge.net
[2] Walls Craig, Richards Norman, Xdoclet in Action Editora Manning
[3] Tutorial: Use XDoclet to generate Web service support files
http://www-106.ibm.com/developerworks/webservices/edu/ws-dw-ws-xdoc-i.html Último acesso em 31 de março de 2004
[4] Tutorial: Enhance J2EE component reuse with XDoclet
http://www-106.ibm.com/developerworks/webservices/edu/ws-dw-ws-j2x-i.html
[5] Tutorial: Object to Relational Mapping and Relationships with Hibernate http://www.meagle.com:8080/hibernate.jsp - último acesso em 31 de março de 2004
[7] Artigo: Automação com Xdoclet, Marcus Brito publicado na revista Java Magazine Edição n.º 6, Ano I - http://www.javamagazine.com.br
[8] – Página de especificação de Enterprise JavaBeans –
http://java.sun.com/products/ejb
[9] – Hibernate, framework persistência – http://www.hibernate.org
[10] – Jakarta Ant, ferramenta de automação – http://ant.apache.org
Este documento ainda não encontra-se na sua versão final, assim sendo, o autor está aberto a receber qualquer comentário a respeito, através do e-mail: alessandro@dev.java.net
Obrigado,
