Framework Demoiselle QuickStart Emerson Oliveira Emerson Saito Luciano Borges Marlon Carvalho Rodrigo Hjort Serge Rehem

Transcrição

1 Framework Demoiselle QuickStart Emerson Oliveira Emerson Saito Luciano Borges Marlon Carvalho Rodrigo Hjort Serge Rehem

2

3 Sobre o QuickStart... v 1. Instalação Ambiente recomendado Demoiselle Infra Criação da aplicação Nossa primeira aplicação Construindo o projeto usando um arquétipo Maven Incluindo catálogo remoto Entidade de domínio Camada de persistência Camada de negócio Camada de apresentação Executando no servidor Melhorando a aplicação Exibindo mensagens para o usuário Criando regras de validação nos campos iii

4 iv

5 Sobre o QuickStart Este documento é um tutorial do tipo "passo a passo" que visa ilustrar de forma rápida, clara e prática a criação de uma aplicação simples utilizando o Demoiselle Framework 2.3. Nota Apesar de o Demoiselle Framework 2.3 ser simples de usar, o desenvolvimento de aplicações não triviais requer o conhecimento das diversas tecnologias envolvidas na especificação Java EE, incluindo: Linguagem Java Servlets, JSP e Tag Libraries JavaBeans HTML e XML Contêineres e Servidores Web Nota Esta documentação refere-se à release 2.3 do Demoiselle Framework e pode diferir significativamente das versões anteriores. v

6 vi

7 Instalação 1.1. Ambiente recomendado Software Versão Site (Download) Java Development Kit (JDK) 6.0 openjdk.org [ Apache Maven 2.2 maven.apache.org [ maven.apache.org/docs/2.2.1/releasenotes.html] Eclipse IDE [ downloads/packages/release/indigo/r] m2eclipse plugin 0.12 m2eclipse.sonatype.org [ m2eclipse.sonatype.org/installingm2eclipse.html] JBoss Application Server [ jbossas/7.1/jboss-as final/jbossas final.zip] 1.2. Demoiselle Infra Para auxiliar no preparo do ambiente integrado de desenvolvimento utilizado na presente documentação, recomenda-se a utilização dos pacotes de software fornecidos pelo projeto Demoiselle Infra [ demoiselle.sourceforge.net/infra/]. Neste link você encontrará as orientações necessárias para a sua configuração. Nota Atualmente são disponibilizados pacotes exclusivamente para a plataforma GNU/Linux e distribuições baseadas no Debian, tal como Ubuntu. Se você não utiliza nenhum dos sistemas operacionais citados, terá que baixar e instalar todos os softwares listados acima. Para auxiliar um pouco o processo, disponibilizamos alguns vídeos aqui [ de demonstração de algumas fases. 1

8 2

9 Criação da aplicação 2.1. Nossa primeira aplicação Para iniciar o uso do Demoiselle Framework, criaremos uma aplicação Java do tipo Web utilizando o Apache Maven [ através do plugin para IDE Eclipse (M2Eclipse) para gerenciar todo o clico de vida do Projeto, desde a criação até o deploy. Essa aplicação consistirá em um cadastro simples de bookmarks (links Favoritos ) e será gerada com o auxílio de um arquétipo do Maven disponibilizado pelo projeto Demoiselle. Ela será preparada para utilizar as tecnologias de persistência JPA e de apresentação JSF nas versões mais recentes conforme a especificação Java EE Construindo o projeto usando um arquétipo Maven Para criar esse projeto utilizando a IDE Eclipse, acesse o menu File, New, Other... digite e selecione Maven Project: conforme mostrado na figura abaixo: Na tela seguinte, recomenda-se manter os valores padrões: 3

10 Capítulo 2. Criação da aplicação Na tela abaixo, no combo-box chamado Catalog, selecione o item com o nome Demoiselle e no campo Filter digite JSF e em seguida selecione o item demoiselle-jsf-jpa : 4

11 Incluindo catálogo remoto Cuidado Se as opções anteriores não aparecem, é porque será necessário incluir o catálogo remoto de arquétipos Maven do Demoiselle. Caso contrário pule o subitem Incluindo catálogo remoto e siga as demais instruções. Cuidado A versão do arquétipo irá variar conforme surjam novas versões do Demoiselle. A imagem deste guia apresenta a versão 2.3.0, contudo, fique sempre atento para as novas versões do Demoiselle em nosso site e sempre utilize a versão do arquétipo mais recente Incluindo catálogo remoto Ainda na tela criação do novo projeto, clique no botão Configure à direita do combo-box Catalog, para que apareça a tela de configuração de arquétipos Maven no Eclipse. Clique no botão Add Remote Catalog...: 5

12 Capítulo 2. Criação da aplicação Na campo Catalog File coloque este conteúdo: repositories/releases. No campo Description informe: Nexus. Em seguida, clique no botão Verify... para certificar-se que o conteúdo está correto. Retorne então ao item anterior e siga as instruções. Na próxima tela preencha os campos conforme ilustrado a seguir e clique em Finish: Ao término do processo será criado o projeto bookmark gerenciado pelo Maven e com a seguinte estrutura de diretórios: bookmark/ -- pom.xml -- src -- main -- java -- br -- gov -- frameworkdemoiselle -- sample -- bookmark -- business -- BookmarkBC.java 6

13 Incluindo catálogo remoto -- constant -- readme.txt -- domain -- Bookmark.java -- exception -- readme.txt -- message -- readme.txt -- persistence -- BookmarkDAO.java -- util -- readme.txt -- view -- BookmarkEditMB.java -- BookmarkListMB.java -- resources -- demoiselle.properties -- log4j.properties -- messages.properties -- META-INF -- beans.xml -- persistence.xml -- ValidationMessages.properties -- webapp -- bookmark_edit.xhtml -- bookmark_list.xhtml -- images -- logo.png -- index.html -- index.xhtml -- menu.xhtml -- template -- main.xhtml -- WEB-INF -- beans.xml -- faces-config.xml -- lib -- web.xml -- test -- java -- br -- gov -- frameworkdemoiselle -- sample -- bookmark -- business -- BookmarkBCTest.java -- resources -- demoiselle.properties -- META-INF -- beans.xml -- persistence.xml 7

14 Capítulo 2. Criação da aplicação 2.3. Entidade de domínio Dentro do pacote br.gov.frameworkdemoiselle.sample.bookmark.domain foi criada a classe Bookmark, a qual será responsável por representar um objeto de bookmark a ser persistido no banco de dados usando public class Bookmark implements Serializable { private static final long serialversionuid = 1L; /* If you are using Glassfish then remove the strategy = SEQUENCE) private Long private String private String link; public Bookmark() { super(); public Bookmark(String description, String link) { this.description = description; this.link = link; public Long getid() { return id; public void setid(long id) { this.id = id; public String getdescription() { return description; public void setdescription(string description) { this.description = description; public String getlink() { return link; public void setlink(string link) { this.link = link; 8

15 Camada de persistência Os dois construtores da classe Bookmark serão utilizados posteriormente na aplicação. @GeneratedValue são fornecidas pela especificação JPA Camada de persistência Dentro do pacote br.gov.frameworkdemoiselle.sample.bookmark.persistence foi criada a classe BookmarkDAO, a qual será responsável por manipular os public class BookmarkDAO extends JPACrud<Bookmark, Long> { private static final long serialversionuid = 1L; Nota A trata-se de um estereótipo fornecido pelo Demoiselle Framework para indicar que uma classe será tratada como controlador da camada de persistência na aplicação. A classe abstrata JPACrud faz parte do código de suporte fornecido pelo Demoiselle Framework (especificamente na extensão JPA). Ao utilizá-la, o desenvolvedor não precisará implementar métodos de manipulação de uma entidade, tais como busca, listagem, inclusão, alteração e exclusão de registros. Dessa forma, apenas métodos específicos do caso de uso necessitam ser criados manualmente. Dica Recomenda-se usar o sufixo DAO nessa classe para indicar que se trata de um objeto de acesso a dados (i.e., um DAO - Data Access Object). No diretório /src/main/resources/meta-inf/ foi criado o arquivo persistence.xml utilizado para armazenar as configurações de acesso ao banco de dados via JPA (conexões controladas por um JPA Provider, ex: Hibernate) ou JTA (conexões controladas pelo Application Server, ex: JBossAS) e, como pode ser observado, o Demoiselle Framework já traz neste arquivo vários exemplos de configurações para os mais distintos Application Servers, como: JBoss AS7, JBoss AS6, GlassFish 3, Tomcat 6 e Tomcat7. O projeto criado pelo arquétipo demoiselle-jsf-jpa já vem configurado para usar conexão JPA com o HSQLDB, conforme código abaixo: <persistence version="2.0" xmlns=" xmlns:xsi=" 9

16 Capítulo 2. Criação da aplicação xsi:schemalocation=" <persistence-unit name="bookmark-ds" transaction-type="resource_local"> <non-jta-data-source>java:jboss/datasources/exampleds</non-jta-data-source> <class>br.gov.frameworkdemoiselle.sample.bookmark.domain.bookmark</class> <properties> <property name="hibernate.show_sql" value="true" /> <property name="hibernate.format_sql" value="false" /> <property name="hibernate.hbm2ddl.auto" value="create-drop" /> </properties> </persistence-unit> </persistence> 2.5. Camada de negócio Dentro do pacote br.gov.frameworkdemoiselle.sample.bookmark.business foi criada a classe BookmarkBC, a qual será responsável por gerenciar as regras de negócio referentes aos public class BookmarkBC extends DelegateCrud<Bookmark, Long, BookmarkDAO> { private static final long serialversionuid public void load() { if (findall().isempty()) { insert(new Bookmark("Demoiselle Portal", " insert(new Bookmark("Demoiselle SourceForge", " insert(new Bookmark("Twitter", " insert(new Bookmark("Blog", " insert(new Bookmark("Wiki", " insert(new Bookmark("Bug Tracking", " insert(new Bookmark("Forum", " insert(new Bookmark("Github", " insert(new Bookmark("SVN", " insert(new Bookmark("Maven", " insert(new Bookmark("Downloads", " O método com a nessa classe será invocado automaticamente durante a inicialização da aplicação e fará com que a tabela seja populada com dados iniciais de bookmarks. 10

17 Camada de apresentação Nota A trata-se de um estereótipo fornecido pelo Demoiselle Framework para indicar que uma classe será tratada como controlador da camada de negócio na aplicação. A classe DelegateCrud faz parte do código de suporte fornecido pelo Demoiselle Framework. Ao utilizá-la, o desenvolvedor não precisará implementar métodos de negócio triviais de uma entidade e tampouco programar a injeção de dependência entre as camadas de negócio e persistência. Tal injeção será realizada de forma implícita. Dica Recomenda-se usar o sufixo BC nessa classe para indicar que se trata de um controlador de negócio (i.e., um BC - Business Controller) Camada de apresentação Dentro do pacote package br.gov.frameworkdemoiselle.sample.bookmark.view foram criadas as classes BookmarkEditMB e BookmarkListMB, onde a primeira é responsável por controlar as modificações sobre os bookmarks efetuadas pelo usuário e a segunda é responsável por exibir as informações sobre public class BookmarkEditMB extends AbstractEditPageBean<Bookmark, Long> { private static final long serialversionuid = private public String delete() { this.bookmarkbc.delete(getid()); public String insert() { this.bookmarkbc.insert(getbean()); public String update() { this.bookmarkbc.update(getbean()); return getpreviousview(); 11

18 Capítulo 2. Criação da protected void handleload() @PreviousView("/bookmark_list.xhtml") public class BookmarkListMB extends AbstractListPageBean<Bookmark, Long> { private static final long serialversionuid = private BookmarkBC protected List<Bookmark> handleresultlist() { return public String deleteselection() { boolean delete; for (Iterator<Long> iter = getselection().keyset().iterator(); iter.hasnext();) { Long id = iter.next(); delete = getselection().get(id); if (delete) { bc.delete(id); iter.remove(); return getpreviousview(); A trata-se de um estereótipo fornecido pelo Demoiselle Framework para indicar que uma classe será tratada como controlador da camada de apresentação (i.e., visão) na aplicação. A serve para definir a próxima visão a ser direcionado o fluxo de navegação JSF. De forma semelhante, a define a visão anterior de um fluxo. A é fornecida pela especificação CDI. Ela realiza a injeção de dependência da camada de negócio dentro do artefato da camada de apresentação. A trata-se de uma anotação fornecida pelo Demoiselle Framework para indicar que o método em questão será incluído na sessão transacional. Caso essa anotação esteja vinculada na classe, todos os seus métodos serão considerados transacionais. 12

19 Executando no servidor As classes AbstractEditPageBean e AbstractListPageBean fazem parte do código de suporte fornecido pelo Demoiselle Framework (especificamente na extensão JSF). Ao utilizá-las, o desenvolvedor não precisará implementar métodos específicos de navegação para uma tela de cadastro (i.e., do tipo CRUD). Dica Recomenda-se usar o sufixo MB nessa classe para indicar que se trata de um bean gerenciado do JSF (i.e., um MB - Managed Bean). No diretório /src/main/webapp/ foram criados os arquivos: bookmark_edit.xhtml - página JSF de cadastro e edição de bookmark; bookmark_list.xhtml - página JSF de cadastro e edição de bookmark; index.html - página HTML que redireciona para a página jsf; index.xhtml - página JSF inicial do sistema; menu.xhtml - página JSF que monta o menu de navegação. No diretório /src/main/webapp/template foi criado o arquivo: main.xhtml - página JSF que serve de template referenciada na demais páginas JSF. Nota Nos arquivos XHTML listados neste exemplo foi empregado o framework PrimeFaces [ o qual foi um dos primeiros a oferecer suporte completo à especificação JSF 2.0. No diretório /src/main/resources/ podemos observar que foi criado o arquivo de recursos messages.properties. Ao invés de manter fixas as descrições em rótulos, links, botões e mensagens em uma aplicação, recomenda-se parametrizar esses textos em arquivos de recursos. Além de ser considerada boa prática, essa medida facilita uma posterior internacionalização da aplicação para diversos idiomas. Nota O arquivo de recursos messages.properties armazenará textos no idioma default da aplicação (neste caso, em Português do Brasil) Executando no servidor A última etapa consiste em fazer o deploy da Java Web em um servidor de aplicações. Utilizando a IDE Eclipse, basta clicar com o botão direito no projeto bookmark e acessar o menu Run As, Run on Server. Em seguida, escolha um servidor compatível com Java EE 6 (ex: JBoss AS 7) e aguarde a inicialização deste. 13

20 Capítulo 2. Criação da aplicação Na visão Console você verá as mensagens decorrentes do servidor de aplicações e da inicialização da aplicação bookmark agora hospedada nele. Dica Para executar em modo de depuração, na visão Servers, clique com o botão direito no servidor desejado e selecione a opção Debug. Em seguida, abra o navegador Web de sua preferência e acesse o endereço Esta é a página que deverá ser exibida com a aplicação bookmark em funcionamento: 14

21 Executando no servidor Figura 2.1. Página principal da aplicação Bookmark Para cadastrar um novo bookmark basta ir no menu principal: Bookmarks, Novo. Executando-a, será exibida a página a seguir: 15

22 Capítulo 2. Criação da aplicação Figura 2.2. Tela de cadastro e edição dos dados na aplicação Bookmark 16

23 Melhorando a aplicação 3.1. Exibindo mensagens para o usuário Uma vez que o objetivo principal da aplicação foi concluído (i.e., listagem e edição de bookmarks), veremos algumas funcionalidades adicionais fornecidas pelo Demoiselle Framework, iniciando pelo tratamento de mensagens. Dentro do pacote br.gov.frameworkdemoiselle.sample.bookmark.message crie a interface InfoMessages, a qual servirá para armazenar mensagens informativas a serem exibidas ao usuário: public interface InfoMessages { final Message BOOKMARK_DELETE_OK = new DefaultMessage("{bookmark-delete-ok"); final Message BOOKMARK_INSERT_OK = new DefaultMessage("{bookmark-insert-ok"); final Message BOOKMARK_UPDATE_OK = new DefaultMessage("{bookmark-update-ok"); Nota A unidade básica de manipulação de mensagens no Demoiselle Framework é a interface Message. Ou seja, basta que esta última seja implementada na aplicação para que o contexto de mensagens possa manipulá-la. A classe DefaultMessage é oferecida como implementação padrão dessa interface. No exemplo em questão, o texto das mensagens será recuperado do arquivo de recursos messages.properties previamente criado no diretório /src/main/resources/. Para isso, adicione as seguintes linhas nesse arquivo: bookmark-delete-ok=bookmark exclu\u00eddo\: {0 bookmark-insert-ok=bookmark inserido: {0 bookmark-update-ok=bookmark atualizado: {0 Dentro do pacote br.gov.frameworkdemoiselle.sample.bookmark.business altere a classe BookmarkBC incluindo os trechos de código indicados a public class BookmarkBC extends DelegateCrud<Bookmark, Long, BookmarkDAO> private MessageContext messagecontext;... 17

24 Capítulo 3. Melhorando a public void insert(bookmark bookmark) { super.insert(bookmark); messagecontext.add(infomessages.bookmark_insert_ok, public void update(bookmark bookmark) { super.update(bookmark); messagecontext.add(infomessages.bookmark_update_ok, public void delete(long id) { super.delete(id); messagecontext.add(infomessages.bookmark_delete_ok, id); No ponto será injetado via CDI o contexto de mensagens presente na aplicação, ou seja, uma instância da interface MessageContext que poderá ser utilizada em qualquer método nessa classe. Aqui os métodos insert(), update() e delete() da classe DelegateCrud são sobrescritos para permitir com que o contexto de mensagens seja manipulado em cada invocação destes. O método add() de MessageContext faz com que a mensagem passada como parâmetro seja adicionada ao contexto, que ao final será exibida para o usuário na camada de apresentação. Nota O contexto de mensagens, representado pela interface MessageContext, é capaz de armazenar diversas mensagens em uma mesma requisição. Ele não é restrito à aplicações do tipo Web, isto é, pode ser usado também para aplicações do tipo desktop (i.e., Swing). Ao término das modificações propostas até aqui, reconstrua o projeto Java e faça novo deploy no servidor de aplicações. Acesse a aplicação bookmark e efetue inclusões, modificações e exclusões de bookmarks. As mensagens informativas devem aparecer em caixas de mensagens na tela, tal como ilustrado a seguir: 18

25 Criando regras de validação nos campos Figura 3.1. Exibição de mensagens na aplicação Bookmark 3.2. Criando regras de validação nos campos Sendo aderente à especificação Java EE 6, o Demoiselle Framework recomenda e faz uso do mecanismo de validação provido pela especificação JSR-303 (Bean Validation) [ A fim de testarmos mais essa funcionalidade, utilizaremos a implementação de validação Hibernate Validator. Para tal, abra o arquivo pom.xml do projeto bookmark e inclua nele a seguinte dependência: <dependencies>... <dependency> <groupid>org.hibernate</groupid> <artifactid>hibernate-validator</artifactid> <version>4.3.0.final</version> </dependency> </dependencies> 19

26 Capítulo 3. Melhorando a apli... Nota O objetivo dessa abordagem de validação é auxiliar na criação de restrições diretamente nas entidades de domínio. Tais restrições serão utilizadas de forma conjunta nas camadas de persistência e apresentação da aplicação. A vantagem é que elas são facilmente configuráveis, bastando apenas incluir certas nos campos da classe a ser validada. No pacote br.gov.frameworkdemoiselle.sample.bookmark.domain altere a entidade de domínio Bookmark incluindo as anotações de validação nos campos description e link conforme ilustrado a public class private @Size(min = 1, max = 30) private = private String link;... No campo description, a serve para impedir que o valor nulo seja atribuído a ele. Já a restringe a quantidade mínima e máxima de caracteres no campo. No campo link mais restrições são aplicadas. Além de não permitir o valor nulo e estipular o comprimento máximo de 255 caracteres o campo não pode ficar vazio e seu conteúdo deve ser um endereço de Internet válido Dica Validações de campos específicos para a comunidade brasileira são oferecidos pelo componente Demoiselle Validation. Com ele, as seguintes anotações podem ser aplicadas nas classes Assim que você efetuar as modificações, reconstrua o projeto Java e faça novo deploy no servidor de aplicações. Acesse a aplicação bookmark e, na tela de edição de bookmarks, deixe vazios os campos no formulário e clique 20

27 Criando regras de validação nos campos em Salvar. Tente também preencher um endereço de Internet inválido no campo Link. Caixas de erro com as mensagens referentes as validações devem aparecer ao lado de cada campo, tal como ilustrado: Figura 3.2. Validação de campos na aplicação Bookmark Dica As mensagens exibidas na tela durante a validação estão contidas no arquivo de recursos ValidationMessages.properties presente no diretório /src/main/resources/. 21

28 22