Nomenclatura de artefatos no Maven #

Os projetos englobados pelo Demoiselle são gerenciados através do Apache Maven, uma ferramenta altamente versátil que, entre outras funcionalidades, permite o controle do ciclo de vida dos projetos e resolve automaticamente as dependências a bilbiotecas externas.

A configuração de um projeto no Maven é realizada no arquivo "pom.xml" segundo um Modelo de Objeto de Projeto (POM) e exige a definição de pelo menos três campos:

• grupo (groupId): este elemento indica o identificador único da organização ou grupo que criou o projeto, sendo geralmente baseado no nome de domínio qualificado da empresa (ex: javax.persistence);
• artefato (artifactId): este elemento indica um nome único do artefato primário a ser gerado pelo projeto - tipicamente um arquivo JAR (ex: persistence-api);
• versão (version): este elemento indica a versão do artefato gerado pelo projeto, e caso esta contenha a designação SNAPSHOT temos a indicação de que o projeto está em fase de desenvolvimento (ex: 1.0).

Um artefato típico produzido pelo Maven tem a seguinte nomenclatura: <artefato>-<versão>.<extensão>. Por exemplo: "persistence-api-1.0.jar".

Identificação do grupo #

Para o Core e as Extensões, a identificação do grupo é sempre a mesma:

br.gov.frameworkdemoiselle

Exemplo:

<groupId>br.gov.frameworkdemoiselle</groupId>
<artifactId>demoiselle-framework-parent</artifactId>
<version>2.0.0</version>

Nos outros projetos, os grupos são identificados no Maven seguindo o modelo abaixo, com a substituição do projeto pelo nome do macro-projeto em questão (ex: component, tools ou sample):

br.gov.frameworkdemoiselle.<projeto>

Exemplo:

<groupId>br.gov.frameworkdemoiselle.component</groupId>
<artifactId>demoiselle-junit</artifactId>
<version>2.0.0</version>

Identificação do artefato #

Os componentes contidos nos macro-projetos Demoiselle Framework, Demoiselle Component e Demoiselle Tools precisam obedecer à seguinte nomenclatura para os seus artefatos, com a substituição do componente ou funcionalidade pela respectiva descrição ou (ex: core, jsf, mail, report):

demoiselle-<componente_funcionalidade>

Exemplos:

<groupId>br.gov.frameworkdemoiselle</groupId>
<artifactId>demoiselle-core</artifactId>
<version>2.0.0</version>

<groupId>br.gov.frameworkdemoiselle.component</groupId>
<artifactId>demoiselle-junit</artifactId>
<version>2.0.0</version>

Já os componentes do projeto Demoiselle Sample obedecem a uma nomenclatura mais simplificada (ex: auction5, escola):

<componente>

Exemplos:

<groupId>br.gov.frameworkdemoiselle.sample</groupId>
<artifactId>escola</artifactId>
<version>2.0.0</version>

Módulos #

Podem existir situações em que artefatos sejam configurados de forma a não serem independentes, porém tenham certa relação com algum outro projeto, chamado de projeto raiz. Isso é altamente útil para o gerenciamento múltiplo de projetos associados, os quais geralmente compartilham o ciclo de vida.

No Demoiselle Framework existe o caso de um projeto pai com o grupo "br.gov.frameworkdemoiselle" e nome de artefato "demoiselle-framework-impl-build<" ser referenciado pelos seguintes artefatos do mesmo grupo:

• core
• extension

Todos os artefatos listados acima são construídos no mesmo momento por possuírem um único ciclo de vida, e por essa razão a versão deles deve sempre ser a mesma.

POM Parent ou Super POM #

A partir da versão 2 do Demoiselle, foi introduzido o uso do recurso Maven chamado Parent POM, esse recurso permite que varios itens de configuração contidos no arquivo POM.XML sejam compartilhados. O padrão para nomes é identificado pela funcionalidade no artifactId e usa o prefixo demoiselle e o sufixo parent.

demoiselle-<funcionalidade>-parent

Exemplos:

<groupId>br.gov.frameworkdemoiselle</groupId>
<artifactId>demoiselle-framework-parent</artifactId>
<version>2.0.0</version>

<groupId>br.gov.frameworkdemoiselle</groupId>
<artifactId>demoiselle-jsf-parent</artifactId>
<version>2.0.0</version>

Estruturação de arquivos e diretórios #

Estrutura de projetos Demoiselle #

Define o padrão de diretórios para os projetos Demoiselle armazenados no repositório de códigos.

Estrutura básica #

A estrutura utilizada no Demoiselle para organizar os diretórios segue a convenção sugerida pelo Maven, onde qualquer projeto criado deve seguir uma estrutura básica conforme o exemplo a seguir.

+- nome_projeto

 +- impl/
 | +- src/
 | | +- main/
 | | |  +- java/
 | | |  +- resources/
 | | |  +- assembly/
 | | +- test/
 | | |  +- java/
 | | |  +- resources/
 +- documentation/

Estrutura Complexa #

Caso o projeto necessite de composição de módulos e outras estruturas, definimos um padrão que deve ser seguido.

+- nome_projeto

 +- archetype/
 +- assembly/
 +- impl/
 | +- nome_modulo/
 | | +- src/
 | | |  +- main/
 | | |  |  +- java/
 | | |  |  +- resources/
 | | |  |  +- assembly/
 | | |  +- test/
 | | |  |  +- java/
 | | |  |  +- resources/
 +- parent/
 +- site/
 +- documentation/

A adição de novos diretórios, é permitida desde que não tenham nenhum padrão que já atenda.

Estrutura padrão para projetos desenvolvidos com Demoiselle #

Estrutura mínima #

A estrutura utilizada pelos projetos que usam o Demoiselle para organizar os diretórios segue a convenção sugerida pelo Maven, onde qualquer projeto criado deve seguir uma estrutura mínima conforme o exemplo a seguir.

+- project
  +- src/
  |  +- main/
  |  |  +- java/
  |  |  +- resources/
  |  |  +- webapp/
  |  |  +- assembly/
  |  |
  |  +- test/
  |  |  +- java/
  |  |  +- resources/
  |  |
  +- target/

O arquétipo demoiselle-minimal faz a geração desta estrutura.

Estrutura composta #

Caso o projeto necessite utilizar vários módulos aninhados utilizamos uma estrutura básica contendo apenas os artefatos comuns entre os módulos, sendo que cada módulo possui a mesma estrutura de um projeto simples.

+- project
   +- src/
   |  +- main/
   |  |  +- assembly/
   |  |
   |
   +- project-1
   |  +- src/
   |  |  +- main/
   |  |  |  +- java/
   |  |  |  +- webapp/
   |  |  |  +- resources/
   |  |  |  +- assembly/
   |  |  |
   |  |  +- test/
   |  |  |  +- java/
   |  |  |  +- resources/
   |  |  |
   |  |
   |  +- target/
   |   
   +- project-n
   |  +- src/
   |  |  +- main/
   |  |  |  +- java/
   |  |  |  +- webapp/
   |  |  |  +- resources/
   |  |  |  +- assembly/
   |  |  |
   |  |  +- test/
   |  |  |  +- java/
   |  |  |  +- resources/
   |  |  |
   |  |
   |  +- target/
   |   
   +- target/

O arquétipo demoiselle-jsf-jpa faz a geração deste tipo de estrutura.

Função de cada diretório na estrutura #

Informações de pacotes Java #

Qualquer diretório que representar um subpacote no Java deve obrigatoriamente conter um arquivo com a nomenclatura package-info.java. Este arquivo deve conter o cabeçalho comum em qualquer arquivo de código Java e uma breve descrição, no formato de comentário Javadoc, sobre a função dos artefatos contidos nessa classe.