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 1
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. Download e Instalação 2
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> Exemplo: 3
<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; 4
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> 5
<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: 6
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, Alessandro Ferreira Leite 7