Demoiselle Framework Reference

Framework Demoiselle 2.3.0

Guia de Referncia

Cleverson Sacramento

Emerson Oliveira

Emerson Saito

Luciano Borges

Marlon Carvalho

Rodrigo HjortSerge Rehem

Thiago Mariano

Wilson Guimares

iii

Sobre o Guia de Referncia ...................................................................................................... v1. Introduo ....................................................................................................................... 1

1.1. O que o Demoiselle? .............................................................................................. 11.2. Sobre a verso 2 ..................................................................................................... 1

2. Arquitetura ....................................................................................................................... 32.1. Estrutura ................................................................................................................ 32.2. Pacote Internal ......................................................................................................... 32.3. Arquitetura das aplicaes .......................................................................................... 4

3. Super POM ....................................................................................................................... 53.1. Demoiselle-Minimal-Parent .......................................................................................... 53.2. Demoiselle-SE-Parent ................................................................................................ 53.3. Demoiselle-Servlet-Parent ........................................................................................... 53.4. Demoiselle-JSF-Parent ............................................................................................... 53.5. Demoiselle-Archetype-Parent ....................................................................................... 5

4. Arqutipos ....................................................................................................................... 74.1. Mnimo .................................................................................................................. 74.2. JSF com JPA .......................................................................................................... 74.3. Vaadin com JPA ...................................................................................................... 7

5. Controlador ...................................................................................................................... 95.1. Como criar seu controlador ......................................................................................... 9

6. Transao ...................................................................................................................... 116.1. Configurando ......................................................................................................... 116.2. Mtodos transacionais .............................................................................................. 116.3. E se acontecer uma Exception? .................................................................................. 126.4. O objeto Transaction ................................................................................................ 126.5. Escolha a estratgia adequada ................................................................................... 126.6. Estratgia JPA ....................................................................................................... 126.7. Estratgia JTA ....................................................................................................... 136.8. Crie a sua estratgia ................................................................................................ 146.9. Escolhendo estratgias manualmente ........................................................................... 14

7. Excees ....................................................................................................................... 177.1. Configurando ......................................................................................................... 177.2. Tratadores de exceo ............................................................................................. 177.3. Mltiplos tratadores ................................................................................................. 177.4. Misturando os dois mundos ....................................................................................... 187.5. Exceo de Aplicao .............................................................................................. 187.6. Tratamento Padro .................................................................................................. 19

8. Configurao .................................................................................................................. 218.1. Configuraes em uma aplicao ................................................................................ 218.2. As classes de configurao ....................................................................................... 218.3. Especificando os parmetros ...................................................................................... 228.4. Usando a configurao na aplicao ............................................................................ 248.5. Lendo arquivos XML ................................................................................................ 248.6. Lendo variveis de ambiente ...................................................................................... 25

9. Inicializao .................................................................................................................... 279.1. Introduo ao mecanismo .......................................................................................... 279.2. Implementao na aplicao ...................................................................................... 279.3. Um exemplo prtico ................................................................................................. 28

10. Tratamento de Mensagens ............................................................................................... 2910.1. Mensagens em uma aplicao .................................................................................. 2910.2. Introduo ao mecanismo ........................................................................................ 2910.3. Parametrizao das mensagens ................................................................................ 3110.4. Internacionalizao das mensagens ............................................................................ 32

Framework Demoiselle 2.3.0

iv

10.5. Exemplos de implementao .................................................................................... 3411. Resource Bundle ............................................................................................................ 37

11.1. Utilizando Resource Bundle no Demoiselle ................................................................... 3712. Parmetro ..................................................................................................................... 39

12.1. Como passar parmetro no Demoiselle 2. .................................................................... 3912.2. As classes de parmetro ......................................................................................... 40

13. Logger ......................................................................................................................... 4114. Templates ..................................................................................................................... 43

14.1. Camada de persistncia .......................................................................................... 4314.2. Camada de negcio ............................................................................................... 4314.3. Camada de apresentao ........................................................................................ 44

15. Segurana ..................................................................................................................... 4515.1. Configurando ........................................................................................................ 4515.2. Autenticao ........................................................................................................ 4515.3. Autorizao .......................................................................................................... 4615.4. Criando sua implementao ..................................................................................... 47

16. Paginao ..................................................................................................................... 5116.1. Introduo ao mecanismo ........................................................................................ 5116.2. Cdigos de suporte ................................................................................................ 5116.3. Implementao na aplicao ..................................................................................... 53

17. Demoiselle Properties ..................................................................................................... 5517.1. Configuraes do Core ........................................................................................... 5517.2. Configuraes da extenso JSF ................................................................................ 5517.3. Configuraes da Extenso JPA ................................................................................ 56

A. Instalao ....................................................................................................................... 57A.1. Pr-requisitos ......................................................................................................... 57A.2. Demoiselle Infra ..................................................................................................... 57

vSobre o Guia de RefernciaEste documento tem como objetivo ser um guia de referncia destinado a todos que desejem conhecer melhor oFramework Demoiselle 2 e suas funcionalidades.

NotaEsta documentao refere-se release 2.3.0 do Demoiselle Framework e pode diferirsignificativamente das verses anteriores.

1

Introduo1.1. O que o Demoiselle?O Demoiselle Framework implementa o conceito de framework integrador. Seu objetivo facilitar a construode aplicaes minimizando tempo dedicado escolha e integrao de frameworks especialistas, o que resulta noaumento da produtividade e garante a manutenibilidade dos sistemas. Disponibiliza mecanismos reusveis voltadosas funcionalidades mais comuns de uma aplicao (arquitetura, segurana, transao, mensagem, configurao,tratamento de excees, etc).

O nome Demoiselle uma homenagem srie de aeroplanos construdos por Santos Dummont entre 1907 e 1909.Tambm conhecido como Libellule, as Demoiselles foram os melhores, menores e mais baratos avies da suapoca. Como sua inteno era popularizar a aviao com fabricao em larga escala, o inventor disponibilizou osplanos em revistas tcnicas para qualquer pessoa que se interessasse.

O Demoiselle Framework usa a mesma filosofia do Pai da Aviao, tendo sido disponibilizado como software livreem abril de 2009, sob a licena livre LGPL version 3. Mais informaes no portal "www.frameworkdemoiselle.gov.br[http://www.frameworkdemoiselle.gov.br]

1.2. Sobre a verso 2O principal objetivo da verso 2 do Demoiselle Framework a completa aderncia especificao JSR 316: JavaPlatform, Enterprise Edition 6 [http://jcp.org/en/jsr/detail?id=316], ou simplesmente Java EE 6. Para saber mais,recomendamos os links Introducing the Java EE 6 Platform [http://www.oracle.com/technetwork/articles/javaee/javaee6overview-141808.html] e As novidades da JEE 6 [http://cleversonsacramento.wordpress.com/2010/08/15/as-novidades-da-jee-6/].

Esta documentao referente s especificaes da verso 2 cadastradas no tracker [https://sourceforge.net/apps/mantisbt/demoiselle/changelog_page.php] do Demoiselle, as quais foram publicamente discutidas no frumdemoiselle-proposal [https://sourceforge.net/apps/phpbb/demoiselle/viewtopic.php?f=35&t=63&start=0].

Os captulos a seguir entram em detalhes sobre cada uma das principais funcionalidades do framework. Tenhauma boa leitura!

3

Arquitetura2.1. EstruturaVisando uma melhor modularizao, o Demoiselle est dividido por funcionalidades. Isto significa que o frameworkno monoltico, no qual todas as suas funcionalidades esto contidas em um nico pacote. Alis, esta estratgiano a mais indicada, pois projetos com um propsito especfico, que no necessitam de persistncia ou interfaceWeb, por exemplo, teriam dependncias desnecessrias. Assim, o Demoiselle separado em Core, Extenses eComponentes.

O Core do Demoiselle contm aquelas funcionalidades comuns a todas as extenses e aplicaes. O core simples,leve e formado majoritariamente por interfaces e poucas implementaes. O Core a base do framework, sem ele,as extenses e a prpria aplicao no funcionariam.

As Extenses, como o prprio nome sugere, estendem o Core com funcionalidades extras e bem especficas aum domnio ou tecnologia. Neste contexto, caso sua aplicao necessite de persistncia com JPA, o frameworkfornecer facilidades para voc, contudo, estas funcionalidades no esto no Core. Para este propsito existem asextenses como a demoiselle-jpa, por exemplo. Cabe destacar que as extenses no possuem vida prpria,pois esto diretamente ligadas ao ncleo do framework, inclusive o ciclo de vida das extenses est totalmenteacoplado ao do Core.

J os Componentes so artefatos separados e que, portanto, no so dependentes diretamente do Core. Alis,os Componentes podem at mesmo existir sem referenciar o Core. Desta forma, o seu ciclo de vida totalmenteindependente do Core e Extenses. Um componente no precisa, necessariamente, estender o comportamento doCore, mas permitir disponibilizar novas funcionalidades ao usurio. Outra diferena importante que, diferente deCore e Extenses, os Componentes no necessariamente so aderentes a alguma especificao. Um exemplo o demoiselle-validation.

2.2. Pacote InternalAs boas prticas de programao nos alertam para que nunca sejamos dependentes de implementaes, massempre de interfaces ou, como alguns costumam dizer, depender de contratos. As interfaces existem paraisto: definem um contrato, enquanto as implementaes deste contrato ficam parte, de preferncia, distante doprogramador da aplicao. O mecanismo de injeo de dependncia fortalece ainda mais esta idia. Sua aplicaoprecisar apenas depender das interfaces que o Demoiselle prov. A implementao especfica ser injetadaautomaticamente pelo CDI.

Dica

As classes do pacote internal nunca devem ser referenciadas pela sua aplicao!

Qual o motivo de toda esta explicao? Os programadores mais curiosos iro encontrar classes do framework queesto inseridas no pacote internal. Cabe alertar que as classes a contidas no devem ser usadas diretamentepela aplicao, caso contrrio, voc estar acoplando-a com a implementao interna do framework, que podesofrer mudanas sem aviso prvio. A equipe do Demoiselle possui ateno especial quanto s suas interfaces(contratos) e no ir modific-las sem antes tornar pblicas as mudanas. Contudo, tudo que consta no pacoteinternal pode sofrer mudanas repentinas. Isto significa que sua aplicao pode deixar de funcionar de umaverso para outra caso voc esteja usando diretamente classes internas.

Captulo 2. Arquitetura

4

2.3. Arquitetura das aplicaes importante reforar que o Demoiselle no obriga nenhum tipo de arquitetura para as aplicaes, que podem serconstitudas com quantas camadas forem necessrias. Contudo, prudente no exagerar! Para quem no sabepor onde comear, sugerimos uma arquitetura e padres largamente utilizados pelo mercado, de forma a facilitara manuteno e para melhor modularizao de seu projeto.

Usualmente, as aplicaes so constitudas com pelo menos trs camadas, desta forma comum separaras lgicas de apresentao, regras de negcio e persistncia. O Demoiselle j fornece esteretipos quevisam tornar esta separao mais clara, respectivamente: @ViewController, @BusinessController e@PersistenceController. Maiores detalhes sobre cada anotao desta sero dados no decorrer destadocumentao.

Cabe destacar que estamos falando de uma macro-viso arquitetural. Cada camada desta pode ser organizadainternamente da melhor forma possvel, ou conforme os padres vigentes no mercado. Para uma aplicao Swing,por exemplo, o padro de projeto Presentation Model bastante indicado e pode ser adotado em aplicaes nestaplataforma. Para aplicaes Web, os frameworks especialistas geralmente aplicam o padro MVC (Model/View/Controller).

5

Super POMO Demoiselle faz uso da soluo proposta pelo Apache Maven para diversas fases do desenvolvimento de software.O artefato principal do Maven o POM.XML que o arquivo XML que contm todas as informaes necessriaspara a ferramenta gerenciar o projeto, entre as quais est o gerenciamento de dependncias(bibliotecas), build doprojeto, etc. Mas muito comum que vrios projetos, vinculados ou no, utilizem muitas configuraes em comum.Para o reaproveitamento dessas configuraes, evitando a cpia de texto, o Maven prov dois tipos de estratgia:

-Por herana [http://maven.apache.org/pom.html#Inheritance] ou agregao [http://maven.apache.org/pom.html#Aggregation].

No Demoiselle 2 a estratgia adota foi tambm o da herana. E o termo usado no Demoiselle para identificar essaestratgia que chamamos de Parent POM.

Seguindo esse conceito, foram criados alguns arquivos (pom.xml) e tambm disponibilizados no repositrio Mavendo Demoiselle , que facilitam a configurao dos projetos, e inclusive para o desenvolvimento do prprio Demoiselle.Os arquivos gerados foram divididos em perfis, para que o desenvolvedor possa escolher qual usar de acordo como tipo de aplicao que est desenvolvendo. Assim, a alterao no POM.XML da aplicao ser a minima possvel.Outra vantagem, que as bibliotecas apontadas como dependncias so testadas pela equipe do Demoiselle oque evita eventuais incompatibilidades.

DicaPara excluir uma dependncia vinda do Parent, mas no necessria utilize a tag Exclusions

3.1. Demoiselle-Minimal-ParentConfiguraes teis para todas as aplicaes que utilizam o framework. O ideal que toda aplicao que utiliza oDemoiselle herde deste POM ou de uma de suas especializaes.

3.2. Demoiselle-SE-ParentEspecializao do POM mnimo, contendo configuraes teis para todas as aplicaes Desktop que utilizam oframework, mas sem definio da camada de apresentao que ser utilizada.

3.3. Demoiselle-Servlet-ParentEspecializao do POM mnimo, contendo profiles para Tomcat 6, Tomcat 7, GAE, Glassfish 3, JBoss 6 e JBoss 7,e outras configuraes teis para todas as aplicaes JEE6/Web que utilizam o Demoiselle, mas sem a definiode qual camada de apresentao utilizar. Entre as dependncias refernciadas por este POM est a extensoDemoiselle-Servlet.

3.4. Demoiselle-JSF-ParentEspecializao do POM demoiselle-servlet-parent, contendo configuraes teis e necessrias para todas asaplicaes que utilizaro a tecnologia JSF2 para camada de apresentao. Entre as dependncias refernciadaspor este POM est obviamente a extenso Demoiselle-JSF.

3.5. Demoiselle-Archetype-ParentContm configuraes comuns a todos os projetos geradores de arqutipos.

7

ArqutiposO projeto Demoiselle recomenda e usa a ferramenta Apache-Maven [http://maven.apache.org/] , paragerenciamento do ciclo de vida do desenvolvimento de projeto. Baseada nesta ferramenta, alm do fornecimentodos POMs Parentes, tambm fornece as estruturas chamadas arqutipos [http://maven.apache.org/archetype/maven-archetype-plugin/] para facilitar a criao de aplicaes, garantido a estrutura recomendada pelo frameworke o conceito de gerenciamento do prprio Maven. Atualmente esto disponveis os seguintes artefatos:

4.1. MnimoFornece um conjunto mnimo de artefatos para criar uma aplicao Java, utiliza o Demoiselle-Minimal-Parent sendotil quando os outros arqutipos disponveis no se enquadram nas caractersticas do projeto a ser criado.

4.2. JSF com JPAtil para os projetos que precisam de uma arquitetura que utilize as tecnologias JSF e JPA, baseado noDemoiselle-JSF-Parent, e que j traz uma estrutura padro de pacotes e todas as dependncias necessrias pararodar a aplicao. Ao usar este arqutipo, voc ter uma pequena aplicao de Bookmarks j pronta para rodar. Paraisto, basta instal-la em um servidor da sua preferncia! Para mais detalhes sobre esta aplicao de exemplo e emcomo usar o arqutipo, acesse a sesso de documentao chamada Quickstart [http://demoiselle.sourceforge.net/docs/quickstart/].

4.3. Vaadin com JPAUma das principais novidades com relao esta nova verso do Demoiselle Framework sua integraomais completa outras tecnologias de apresentao. Na verso anterior apesar de ser possvel a utilizaode outra solues, no havia ainda facilitadores realmente integrados ao Demoiselle. Seguindo este princpio,um dos arqutipos disponibilizados pelo Framework gera uma aplicao de exemplo, nos mesmo moldes que disponibilizado para a tecnologia JSF, mas com a tecnologia de apresentao chamada VAADIN [http://vaadin.com].

9

ControladorNo Demoiselle Framework os controladores ou controllers servem para identificar as camadas da arquitetura desua aplicao. comum que as aplicaes utilizem apenas trs camadas: viso, negcio e persistncia. Existemaplicaes que utilizam fachadas. Por esse motivo, foram implementados nessa verso do framework quatrocontrollers:

ViewController

FacadeController

BusinessController

PersistenceController

Alm de identificar as camadas, os controllers so pr-requisitos para utilizao da funcionalidade de tratamentode excees, atravs do uso da anotao @ExceptionHandler. Isso quer dizer que para utilizar essafuncionalidade, a classe precisa usar um dos controllers citados acima ou a prpria anotao @Controller ouainda um controller criado exclusivamente para sua aplicao. Todos os controllers criados no framework soesteretipos e podem ser usados tambm para definio de caractersticas como, por exemplo, o escopo. Isso querdizer que se um controller tem um determinado escopo, todas as classes desse controller, tambm tero o mesmoescopo. Foi falado que possvel criar um controller para uso exclusivo em sua aplicao, mas como fazer isso?Veja na seo abaixo.

5.1. Como criar seu controlador comum nos depararmos com situaes onde precisamos criar controllers exclusivos com determinadascaractersticas ou que sirvam apenas para determinar algum tipo de funcionalidade. Para criar um novo controllerno Demoiselle, basta que ele esteja anotado com @Controller, como no exemplo abaixo.

@Controller@Stereotype@ViewScopedpublic @interface SeuController {}

Neste exemplo foi criado um controlador chamado SeuController que tem a caracterstica de ter um escopode View. Isto quer dizer que toda classe que seja desse tipo de controlador, tambm ter o escopo de View.

11

TransaoEsta funcionalidade utiliza os recursos do CDI para interceptar e delegar adequadamente o tratamento dastransaes. Em outras palavras, no reinventamos a roda. Criamos algumas estratgias de delegao e controlede transao com base no que est sendo mais utilizado no mercado, algumas mais simples de configurar, outrasmais completas para utilizar.

Alm de plugar e usar as estratgias prontas que fizemos para voc, possvel tambm criar a sua. Vai que vocprecise de algo que no pensamos ainda. O importante que voc tenha opes, e uma das opes tambm noutilizar a nossa soluo. Caso voc esteja utilizando o Demoiselle Framework em conjunto com outro framework(tais como o JBoss Seam, Spring ou Google Guice) que oferea o controle de transao, voc pode us-lo tambm.Viva a liberdade de escolha!

Neste captulo apresentaremos para voc como usar a nossa soluo de controle de transao, as estratgiasprontas que oferecemos e a criao de sua prpria estratgia.

6.1. ConfigurandoPara um correto funcionamento do Demoiselle necessrio inserir o interceptador de transao no arquivo src/main/WEB-INF/beans.xml.

br.gov.frameworkdemoiselle.internal.interceptor.TransactionalInterceptor

6.2. Mtodos transacionaisVamos comear pelo mais importante: como declarar os mtodos como transacionais? Como informar aoDemoiselle Framework que o mtodo deve participar da sesso transacional? A resposta muito simples, anoteseu mtodo com @Transactional.

@Transactionalpublic void inserir() { }

Se voc desejar que todos os mtodos de sua classe sejam transacionais, anote diretamente a classe:

@Transactionalpublic class Simples { public void inserir() { } public void alterar() { } public void excluir() { }

Captulo 6. Transao

12

}

Neste exemplo, os mtodos inserir(), alterar() e excluir() da classe Simples participaro docontexto transacional.

6.3. E se acontecer uma Exception?Caso ocorra uma exceo na execuo de um mtodo transacional o mecanismo far rollback na transaoautomaticamente. possvel mudar este comportamento utilizando excees de aplicao (para maiores detalhesver Exceo).

@ApplicationException(rollback = false)public class AbacaxiException {}

6.4. O objeto TransactionPara ter acesso instncia da transao corrente, basta injet-la em sua classe.

public class Simples { @Inject private Transaction transaction;}

6.5. Escolha a estratgia adequadaPara o controle transacional funcionar corretamente preciso escolher a estratgia mais adequada para o seu caso.No existe a bala de prata, voc tem que avaliar a melhor estratgia para o seu projeto.

Voc pode optar tambm por no utilizar controle de transao. Neste caso, basta no utilizar a anotao@Transactional. Contudo, caso voc a utilize, voc poder escolher entre as estratgias JPA, JTA (ambasfornecidas pelo Framework) e uma estratgia que voc pode criar ou importar para seu projeto.

A forma de selecionar cada uma dessas estratgias descrita abaixo. Caso tente utilizar o controle de transaoe no selecione nenhuma estratgia, o framework lanar uma exceo lhe avisando sobre isto!

6.6. Estratgia JPAEsta estratgia, que est disponvel na extenso demoiselle-jpa, delega o controle de transaes para ojavax.persistence.EntityManager da especificao JPA. Voc deve escolher esta estratgia quandovoc estiver fazendo a persistncia com JPA e utilizando apenas uma base de dados em sua aplicao. Comoum EntityManager acessa apenas uma unidade de persistncia, no h como fazer o controle transacional deunidades distintas.

A transao JPA simples de configurar e no exige nenhum recurso externo sua aplicao. Para utiliz-la bastaque seu projeto adicione no arquivo POM.XML dependncia extenso demoiselle-jpa, que o Demoisellefar a seleo por essa estratgia de forma automtica.

Estratgia JTA

13

Dica

Caso no esteja utilizando o arqutipo JSF-JPA fornecidos pelo Demoiselle, confira se adependncia para a extenso est indicada corretamente no arquivo POM.XML.

br.gov.frameworkdemoiselle demoiselle-jpa compile

6.7. Estratgia JTAEsta estratgia, tambm est disponvel atravs de uma extenso (demoiselle-jta), e responsvel pordelegar o controle de transao para um container JEE. Com a JTATransaction possvel incluir vriasunidades de persistncia de uma mesma aplicao no mesmo contexto transacional. Isso mesmo, o famoso Two-Phase Commit (2PC).

A estratgia JTA no serve apenas para persistncia em banco de dados, serve tambm para integrar comtecnologias que faam acesso ao contexto JTA, como o caso do EJB. Para ativar esta estratgia basta que seuprojeto adicione no arquivo POM.XML a dependncia extenso demoiselle-jta, que o Demoiselle far aseleo por essa estratgia de forma automtica, pois essa estratgia tem prioridade em relao a estratgia JPA.

Feito isto, o controle transacional ser delegado para a transao acessvel via JNDIcom o nome UserTransaction. A estratgia acessa o objeto da seguinte maneira:Beans.getReference(UserTransaction.class). Portanto, para voc utilizar esta estratgia, vocprecisa de um container JEE ou de um servidor JTA qualquer.

preciso tambm informar no arquivo persistence.xml o endereo da conexo JTA gerenciada. Veja umexemplo utilizando o servidor de aplicaes JBoss-AS6 e com o provider Hibernate (embutido no JBoss-AS) comoimplementao JPA:

java:jboss/datasources/ExampleDS

Captulo 6. Transao

14

Dica

Caso no esteja utilizando o arqutipo JSF-JPA fornecidos pelo Demoiselle, confira se adependncia para a extenso est indicada corretamente, no arquivo POM.XML.

br.gov.frameworkdemoiselle demoiselle-jta compile

6.8. Crie a sua estratgiaCaso nenhuma das estratgias oferecidas sirva para voc, crie a sua. Basta escrever uma classe no-finalque implemente a interface Transaction do pacote br.gov.frameworkdemoiselle.transaction. preciso que sua classe no possua construtores explcitos ou que possua um construtor pblico sem parmetros. possvel fazer injees nesta classe.

package projeto;

import br.gov.frameworkdemoiselle.transaction.Transaction;

public class MegaTransaction implements Transaction { public void begin() { } public void commit() { } public void rollback() { } public void setRollbackOnly() { } public int getStatus() { } public void setTransactionTimeout(int seconds) { } public boolean isActive() { } public boolean isMarkedRollback() { }}

Pronto, s isso! Agora, os mtodos anotados com @Transactional iro utilizar a estratgia criada emseu projeto de forma automtica, mesmo que as extenses demoiselle-jpa e demoiselle-jta sejamadicionadas ao projeto, pois o framework da prioridade mxima estratgia criada no projeto.

6.9. Escolhendo estratgias manualmenteExistem alguns casos nos quais voc vai ter que definir a estratgia manualmente. Um exemplo quando seu projetoimplementa mais do que uma estratgia de transao. Outra situao pode acontecer em casos de teste, nos quaisvoc queira utilizar estratgia diferente. Nesses casos voc deve definir no arquivo demoiselle.propertiesqual estratgia ser utilizada. Veja alguns exemplos de definio de estratgias prpria, JTATransaction eJPATransaction (importante notar que apenas uma estratgia pode estar ativa por vez):

frameworkdemoiselle.transaction.class=projeto.MyTransaction

Escolhendo estratgias manualmente

15

frameworkdemoiselle.transaction.class=br.gov.frameworkdemoiselle.transaction.JTATransaction

frameworkdemoiselle.transaction.class=br.gov.frameworkdemoiselle.transaction.JPATransaction

17

ExceesEsta funcionalidade foi feita para voc que acha muito verboso encher o cdigo de try/catch. E o que dizerde repetir o tratamento de excees em vrios mtodos da mesma classe na base do copiar/colar? Oferecemos voc uma alternativa para resolver estes problemas, mas voc estar livre para us-la: isoladamente, misturandocom a forma verbosa ou at mesmo no us-la.

7.1. ConfigurandoPara um correto funcionamento do Demoiselle necessrio inserir o interceptador de exceo no arquivo src/main/WEB-INF/beans.xml.

br.gov.frameworkdemoiselle.internal.interceptor.ExceptionHandlerInterceptor

7.2. Tratadores de exceoPara definir um tratador de exceo, basta anotar o mtodo com @ExceptionHandler. O tratamento deexcees s possvel em classes anotadas com @Controller ou os derivados desta anotao. Para ver maisdetalhes sobre controladores no Demoiselle, leia o captulo Controladores.

@Controllerpublic class Simples {

@ExceptionHandler public void tratador(NullPointerException cause) { } public void inserir() { } public void alterar() { } public void excluir() { }}

Neste exemplo, qualquer exceo do tipo NullPointerException que ocorrer nos mtodos da classeSimples ter o tratamento delegado para o mtodo tratador(). Para as excees no tratadas, ocomportamento seguir o padro da linguagem.

7.3. Mltiplos tratadoresNo se limite a apenas um tratador por classe, voc pode ter vrios.

@Controller

Captulo 7. Excees

18

public class Simples {

@ExceptionHandler public void tratador(NullPointerException cause) { } @ExceptionHandler public void tratador(AbacaxiException cause) { } public void inserir() { } public void alterar() { } public void excluir() { } }

Caso as excees NullPointerException ou AbacaxiException ocorram nos mtodos da classeSimples, o tratamento ser delegado para o seu tratador.

7.4. Misturando os dois mundos possvel que, em determindas situaes no seu projeto, voc precise misturar o tratamento sofisticado com atradicional forma verbosa. Como fazer isso?

Suponha que no mtodo inserir() voc precise dar um tratamento exclusivo para uma exceo. Para isso,misture as duas abordagens para atingir o seu objetivo.

@Controllerpublic class Simples {

@ExceptionHandler public void tratador(NullPointerException cause) { } public void inserir() { try { // tenta algo } catch (AbacaxiException cause ) { // trata o problema } } public void alterar() { } public void excluir() { }}

Neste caso a exceo AbacaxiException s ser tratada no mtodo inserir().

7.5. Exceo de AplicaoImagine que voc precise informar que caso um determinado tipo de exceo seja lanado atravs do seu mtodo, atransao atual sofrer um rollback. Ou, ento, que haja necessidade de informar o grau de severidade da exceo,de forma que uma camada de apresentao especfica a trate de forma diferenciada. Estas duas opes sopossveis atravs do uso da anotao @ApplicationException. Utilize-a em suas excees e informe osatributos rollback e severity para alcanar os objetivos acima.

@ApplicationException(rollback=true, severity=SeverityType.INFO)public class MinhaException extends Exception {}

Tratamento Padro

19

No exemplo citado acima, estamos informando que caso esta exceo seja lanada por um mtodo anotado com@Transactional, este mtodo sofrer um rollback. Ao mesmo tempo, sua camada de exibio apresentar umamensagem automtica para o usurio, conforme o nvel de severidade. O comportamento padro para o rollback realizar o rollback sempre que a exceo for lanada. O grau de severidade padro informativo (INFO).

7.6. Tratamento PadroAs excees lanadas a partir da camada de negcio, ou de persistncia, no causam a interrupo de suaaplicao. Muito menos, apresentam a tela padro de erro do JSF ou de outra tecnologia de viso. Qualquerexceo lanada, e que chega at a camada de apresentao, recebe um tratamento especial. Inicialmente, ela encapsulada de forma que possa ser exibida de forma elegante para o usurio. No caso do JSF, utilizado omecanismo de Messages prprio desta tecnologia.

No caso do Vaadin, o tratamento bem semelhante, contudo, a exceo tratada de forma que possa serexibida adotando os mecanismos prprios da tecnologia. No caso de excees que no usam a anotao@ApplicationException, um rollback realizado de forma automtica. Por ltimo, sem o uso desta anotao,toda exceo vista como tendo nvel de gravidade igual a ERROR.

21

Configurao8.1. Configuraes em uma aplicaoEm aplicaes no modelo Java EE, as quais so executadas hospedadas em um servidor de aplicaes oucontiner Web, existem diversos papis alm do desenvolvedor, tais como assembler e deployer. comum nestasaplicaes que informaes de configurao de ambiente, especialmente por questes de segurana, sejam deconhecimento restrito. Por exemplo, o usurio e senha de um banco de dados ou o nome de uma fila de mensagensso informaes que o desenvolvedor no deve possuir, pelo menos para o ambiente de produo. Alm disso, oprofissional responsvel pelo deploy (i.e., a implantao) da aplicao geralmente no pode ser encarregado derecompilar os cdigos fontes para efetivar a alterao desses dados.

Para resolver essas questes, faz-se necessrio um mecanismo de configurao para as aplicaes. Odesenvolvedor e o assembler constroem inteiramente uma aplicao e entregam o respectivo arquivo para odeployer coloc-la em produo. Paralelamente a isso, o deployer configura arquivos externos e variveis desistema com as informaes sigilosas e protegidas que sero posteriormente lidas pela aplicao. A aplicao noprecisar ser reconstruda caso um dado de configurao precise ser modificado.

Frequentemente em Java utilizamos as seguintes abordagens para armazenar as configuraes:

arquivo de propriedades: tratam-se de simples arquivos de texto nomeados com a extenso .properties eque internamente so escritos com a sintaxe chave = valor, armazenando uma nica chave por linha;

arquivo XML: so arquivos de texto altamente estruturados com a sintaxe de tags e que permitem uma maiorvalidao de seus valores, sendo geralmente nomeados com a extenso .xml;

variveis de ambiente: valores definidos a nvel de sistema operacional, independente de plataforma (Windows,Linux, etc) e que podem ser recuperados durante a execuo da aplicao.

Na seo a seguir veremos como o Demoiselle Framework apoia o desenvolvimento de aplicaes nas tarefas decarregamento de configuraes. Tal mecanismo comumente utilizado internamente em diversos componentesdo framework.

8.2. As classes de configuraoA primeira etapa para a utilizao do mecanismo de configurao em uma aplicao consiste em criar uma classeespecfica para armazenar os parmetros desejados e anot-la com @Configuration. Eis um exemplo:

@Configuration(resource = "bookmark")public class BookmarkConfig {

private String applicationTitle; private boolean loadInitialData; public String getApplicationTitle() { return applicationTitle; } public boolean isLoadInitialData() { return loadInitialData; }}

Captulo 8. Configurao

22

Na classe os atributos devem ser tratados como sendo somente de leitura, possuindo apenas seus respectivosmtodos getter. Valores default podem ser especificados com literais na prpria declarao do atributo (ex:boolean loadInitialData = true).

Nota

As classes anotadas com @Configuration so tratadas de forma diferenciada pelo continer.Elas so instanciadas uma nica vez (seguindo o padro de projeto singleton) e podem serutilizadas em qualquer ponto da aplicao. Seu ciclo de vida gerenciado automaticamentepela implementao CDI. O arquivo de recursos especificado lido apenas na inicializao daaplicao e os atributos da classe so preenchidos automaticamente nessa etapa.

No exemplo em questo, ser buscado um arquivo de propriedades com o nome bookmark.propertiescontendo as seguintes chaves:

application.title = Ttulo da Aplicaoload.initial.data = true

Nota

Recomenda-se usar o sufixo Config em uma classe de configurao para indic-la como tal.

O nome do recurso (resource) e o tipo de configurao (type) so argumentos opcionais na anotao@Configuration. Caso no sejam especificados, ser considerado o arquivo de propriedades padro doDemoiselle Framework, o demoiselle.properties.

8.3. Especificando os parmetrosPor padro todos os atributos existentes em uma classe anotada com @Configuration so tratados comoparmetros de configurao e sero automaticamente preenchidos durante a leitura do arquivo de recursos.

Dica

Para indicar que um determinado atributo da classe no corresponde a um parmetro, utilizea anotao @Ignore nele. Desta forma ele ser desconsiderado no momento de leitura daconfigurao.

Dica

Para forar a existncia de um parmetro de configurao, utilize a anotao @NotNull norespectivo atributo. Caso ele no seja encontrado no recurso, uma exceo ser lanada nainicializao da aplicao.

Especificando os parmetros

23

No arquivo de recursos ser buscada a chave correspondente ao atributo seguindo convenes pr-determinadas.Por exemplo, no caso do atributo loadInitialData, sero buscadas as seguintes verses de chaves no arquivode recursos:

loadInitialData

load.initial.data

load_initial_data

loadinitialdata

DicaA fim de utilizar uma nomenclatura de chave diferente dos formatos convencionados, utilize aanotao @Name no atributo.

Em determinadas situaes utilizado um prefixo de chave comum a todos os parmetros de uma classe deconfigurao. Neste caso, possvel especificar tal prefixo na anotao @Configuration. Isso permite, porexemplo, que um mesmo arquivo de recursos (ex: demoiselle.properties) seja compartilhado por diversasclasses de configurao.

Veja na listagem abaixo um cdigo fonte que ilustra a utilizao das anotaes descritas nesta seo:

@Configuration(resource = "bookmark", prefix = "general") public class BookmarkConfig {

@Name("app.title") private String applicationTitle;

@NotNull private boolean loadInitialData;

@Ignore private int dummy;

public String getApplicationTitle() { return applicationTitle; }

public boolean isLoadInitialData() { return loadInitialData; }}

Na anotao @Configuration so especificados o arquivo de recursos bookmark.properties e oprefixo general a ser considerado em cada uma das chaves.Ao invs de adotar o padro convencionado, com a anotao @Name ser considerada a chave app.titleaps o prefixo.Como o atributo anotado com @NotNull, presume-se que ele sempre estar presente no arquivo derecursos. Caso contrrio, uma exceo ocorrer na inicializao da aplicao.Este atributo, por estar anotado com @Ignore, no ser considerado pelo mecanismo de configuraes.

Captulo 8. Configurao

24

Neste caso, ser buscado um arquivo de propriedades com o nome bookmark.properties contendo asseguintes chaves:

general.app.title = Ttulo da Aplicaogeneral.load.initial.data = true

Dica

Alm de String e boolean, existe a possibilidade de se recuperar valores de qualquer tipoprimitivo do Java (i.e., int, byte, short, char, long, float, double e boolean)e tambm arrays desses tipos e de alguns tipos complexos (i.e., Integer, BigDecimal,BigInteger, Calendar, Date, Color, Locale, URL e String).

8.4. Usando a configurao na aplicaoA fim de utilizar o objeto de configurao previamente instanciado e preenchido pelo continer, basta criar umavarivel numa classe qualquer da aplicao e anot-la com @Inject. Tal varivel ser injetada automaticamentee pode ser usada dentro de um mtodo. Veja na listagem a seguir um exemplo de injeo e uso de uma classede configurao:

public class BookmarkBC {

@Inject private BookmarkConfig config;

public void startup() { if (config.isLoadInitialData()) { ...

} }}

Nota

O Demoiselle Framework utiliza internamente o mecanismo de configuraes na leitura do arquivodemoiselle.properties para outras funcionalidades, tais como transao, persistncia epaginao.

8.5. Lendo arquivos XMLAgora veja como ficaria a abordagem de configurao usando arquivos XML. Eis um arquivo de exemplo, oescola.xml, possuindo um valor numrico e um conjunto de strings:

125

Lendo variveis de ambiente

25

Aluno Professor Administrador

Neste caso, na classe de configurao EscolaConfig a anotao @Configuration precisa apontar parao tipo de recursos XML e usar o respectivo arquivo escola.xml. Eis a implementao necessria para que oreferido arquivo XML seja lido e os seus valores carregados automaticamente:

@Configuration(resource = "escola", type = ConfigType.XML)public class EscolaConfig {

private Integer qtdeInicial = 50;

@Name("papeis.papel") private List papeis;

private Integer getQtdeInicial() { return qtdeInicial; }

public List getPapeis() { return papeis; }}

8.6. Lendo variveis de ambienteA terceira abordagem na configurao consiste em utilizar as variveis de ambiente do sistema operacional. Estasvariveis geralmente so carregadas na inicializao do sistema ou aps a criao da sesso do usurio (i.e., apso login), mas tambm podem ser modificadas manualmente atravs de comandos como set ou export.

O mecanismo de configuraes no Demoiselle Framework faz uso da classe java.lang.System [http://download.oracle.com/javase/6/docs/api/java/lang/System.html] fornecida pela API do Java para carregar os valoresnas propriedades a partir de variveis de ambiente independente do sistema operacional.

Veja na listagem abaixo o cdigo necessrio para a leitura de uma varivel de ambiente:

@Configuration(type = ConfigType.SYSTEM)public class EscolaConfig {

@Name("java.home") private String javaDirectory;

public String getJavaDirectory() { return javaDirectory; }}

27

Inicializao9.1. Introduo ao mecanismoUma aplicao qualquer, seja do tipo Web ou desktop, geralmente necessita efetuar determinadas tarefas durantea sua inicializao e ou finalizao. Eis alguns exemplos: abertura de conexo a um servidor de banco de dados,carregamento de parmetros de configurao a partir de arquivos externos e execuo de scripts especficos. Ouseja, normalmente essas aes so definidas como funes estruturais da aplicao.

Para que a execuo dessas aes ocorra de forma concisa, faz-se necessrio o uso de um mecanismo padronizadopara inicializao do ambiente. O Demoiselle Framework fornece esse mecanismo atravs da especificao CDIintroduzindo duas anotaes: @Startup e @Shutdown.

9.2. Implementao na aplicaoA fim de utilizar o mecanismo inerente do Demoiselle Framework, preciso simplesmente anotar os mtodoscontendo as instrues desejadas com @Startup, para a inicializao, ou @Shutdown, para a finalizao.

Dica

O mecanismo de inicializao do Demoiselle Framework independente da natureza da aplicaoJava, isto , visa tanto aplicaes do tipo Web quanto do tipo desktop (ex: Swing).

As instrues contidas em um mtodo anotado com @Startup sero executadas automaticamente quando aaplicao Java for inicializada, seja ela hospedada em um continer Web ou executada atravs de um mtodomain(). Nenhum outro arquivo ou classe precisa ser definido. A anotao @Startup pode ser utilizada emconjunto com a anotao @Priority, que recebe como parametro um nmero inteiro que serve para definir aprioridade de execuo do respectivo mtodo, na existncia de mais de um inicializador para a aplicao.

De maneira anloga, um mtodo anotado com @Shutdown ser executado no momento de finalizao de umaaplicao, obedecendo tambm ordem de prioridade definida com a anotao @Priority.

Eis um exemplo de implementao de inicializador em uma aplicao:

public class BookmarkInitializer {

@Startup @Priority(1) public void initialize() { ...

}

@Shutdown @Priority(5) public void finalize() { ...

}}

Captulo 9. Inicializao

28

DicaPara a definio de prioridade de execuo de um mtodo na inicializao ou finalizao,podem ser utilizadas as constantes MIN_PRIORITY ou MAX_PRIORITY presentes embr.gov.frameworkdemoiselle.annotation.Priority.

9.3. Um exemplo prticoEis um interessante caso de uso de inicializao e finalizao: rodar um servidor de modo standalone em paralelo execuo da aplicao principal. Eis o cdigo referente essa implementao:

import br.gov.frameworkdemoiselle.lifecycle.Shutdown;import br.gov.frameworkdemoiselle.lifecycle.Startup;

import static br.gov.frameworkdemoiselle.annotation.Priority.MAX_PRIORITY;import static br.gov.frameworkdemoiselle.annotation.Priority.MIN_PRIORITY;

public class DatabaseServer {

private final org.hsqldb.Server server;

public DatabaseServer() { server = new Server(); server.setDatabaseName(0, "db"); server.setDatabasePath(0, "database/db"); server.setPort(9001); server.setSilent(true); }

@Startup @Priority(MAX_PRIORITY) public void startup() { server.start(); }

@Shutdown @Priority (MIN_PRIORITY) public void shutdown() { server.stop(); }}

29

Tratamento de Mensagens10.1. Mensagens em uma aplicaoUma aplicao bem estruturada, seja na plataforma Web ou Desktop, deve exibir mensagens informativas, de aviso,ou de erro para o usurio aps efetuar determinadas tarefas. Por exemplo, aps gravar um registro no banco dedados, aconselhvel que a aplicao exiba uma mensagem informativa. Se alguma exceo ocorreu, precisoexibir uma mensagem de erro. Ou seja, a severidade da mensagem deve ser escolhida de acordo com o resultadoda execuo.

Veja na tabela a seguir a definio de cada um dos nveis de severidade da mensagem em uma aplicao e umexemplo de texto associado:

Tabela 10.1. Nveis de severidade em mensagens

Severidade Utilizao Exemplo de texto

Informao Usada quando da ocorrncia normal ou esperadano fluxo, com o objetivo de confirmar ao usuriouma situao de sucesso.

Aluno includo com sucesso.

Aviso Usada quando uma regra de negcio ouvalidao qualquer da aplicao tenha desviadoo fluxo normal de execuo.

A turma selecionada j est lotada.Matrcula do aluno no efetuada.

Erro Reservado para o caso de uma situao anormal,tal como excees provenientes de ambiente(falha de conexo na rede, queda de um servidorde banco de dados, etc) tenha impedido aexecuo.

No foi possvel efetuar a modificao doaluno.

Em uma aplicao construda usando-se arquitetura em camadas, as mensagens geralmente so originadas emuma determinada camada e precisam ser transmitidas s demais at chegar ao usurio. Por exemplo, se ocorreum erro de gravao no banco de dados, isto , na camada de persistncia, tal informao precisa ser repassadas camadas subsequentes, ou seja, as camadas de negcio e posteriormente de controle e viso. Este conceito justamente chamado de tratamento de mensagens, o qual, ao lado do tratamento de excees, auxilia o fluxo deexecues em uma aplicao bem arquiteturada. Em resumo, preciso programar a troca de mensagens entre asdiversas camadas de uma aplicao orientada a objetos.

Veremos na seo a seguir como o Demoiselle Framework pode ajudar o desenvolvedor na tarefa de troca demensagens em uma aplicao.

10.2. Introduo ao mecanismoOrtogonalmente s camadas verticais da aplicao (i.e., apresentao, negcio e persistncia), a arquiteturaproposta pelo Demoiselle Framework fornece os contextos de transao, segurana e mensagem. Este ltimo justamente responsvel pela troca de mensagens entre as camadas.

Tecnicamente falando, o contexto de mensagens no Demoiselle Framework representado pela interfaceMessageContext. Esta interface contm mtodos destinados a incluso, recuperao e limpeza de mensagensno contexto.

Para obter uma instncia do contexto de mensagens, basta injet-lo na classe:

Captulo 10. Tratamento de Me...

30

@Injectprivate MessageContext messageContext;

A maneira mais simples de se inserir uma mensagem no contexto invocando o mtodo add() deMessageContext passando como argumento o texto literal da mensagem:

messageContext.add("Aluno inserido com sucesso.");

Opcionalmente, pode-se indicar a severidade da mensagem:

messageContext.add("Deseja realmente excluir o aluno?", SeverityType.WARN);

Dica

Quando a severidade no informada (argumento de tipo SeverityType), ser consideradoo nvel informativo, isto , INFO.

Para a transmisso das mensagens no contexto tambm fornecida a interface Message, a qual permite com queos textos sejam obtidos de catlogos especializados, tais como arquivos de propriedades ou banco de dados. Essainterface precisa ser implementada em uma classe customizada pelo desenvolvedor. Sua estrutura bem simples:

public interface Message {

String getText(); SeverityType getSeverity();}

A classe DefaultMessage fornecida pelo Demoiselle Framework uma implementao da interface Messageque faz uso dos arquivos de recurso da aplicao para obteno das descries das mensagens. Especificamenteutiliza o arquivo messages.properties.

Nota

A unidade bsica de manipulao de mensagens no Demoiselle Framework a interfaceMessage. Basta que ela seja implementada na aplicao para que o contexto de mensagenspossa manipul-la. A classe DefaultMessage oferecida como implementao padro dessainterface.

Para incluir uma mensagem no contexto usando o tipo Message preciso invocar o mtodo add()de MessageContext passando o objeto como argumento. Eis um exemplo disso utilizando a classeDefaultMessage:

Parametrizao das mensagens

31

Message message = new DefaultMessage("Ocorreu um erro ao excluir o aluno!", SeverityType.ERROR);messageContext.add(message);

Uma vez inseridas no contexto em determinada camada da aplicao, as mensagens podem ser posteriormenterecuperadas. Para tal, preciso invocar o mtodo getMessages() da interface MessageContext, o qualretornar uma coleo de objetos do tipo Message.

NotaA extenso para JavaServer Faces no Demoiselle Framework transfere automaticamente asmensagens includas no MessageContext para a apresentao durante a renderizao dapgina pelo JSF.

Para remover todas as mensagens existentes no contexto, basta invocar o mtodo clear() da interfaceMessageContext.

NotaEspecificamente para aplicaes Java Web, o contexto de mensagens automaticamentereinicializado a cada requisio HTTP. Ou seja, as mensagens includas no contexto por umadeterminada sesso de usurio no interferem nas demais sesses existentes no servidor deaplicaes. Alm disso, ao final da requisio as mensagens existentes so automaticamenteexcludas do contexto.

O contexto de mensagens MessageContext tem o seu ciclo de vida gerenciado pelo CDI e pertence ao escopode sesso (i.e., @SessionScoped). Ou seja, mensagens includas na requisio de um determinado usurio nosero exibidas para um outro usurio, pois cada um possuir a sua sesso.

NotaO contexto de mensagens, representado pela interface MessageContext, capaz dearmazenar diversas mensagens em uma mesma requisio. Ele no restrito aplicaes dotipo Web, isto , pode ser usado tambm para aplicaes do tipo desktop (i.e., Swing).

10.3. Parametrizao das mensagensUm recurso importante no tratamento de mensagens de uma aplicao consiste na parametrizao dos textos queelas carregam. Isso extremamente til para indicar com detalhes uma situao especfica, com o objetivo demelhor informar o usurio. Por exemplo, ao invs de simplesmente exibir Excluso de disciplina no permitida prefervel mostrar o seguinte texto mais explicativo Excluso no permitida: disciplina est sendo usada pelaturma 301. Para efetuar essa parametrizao, preciso usar a formatao de textos padronizada pela classejava.text.MessageFormat [http://download.oracle.com/javase/6/docs/api/java/text/MessageFormat.html] daAPI do Java, que basicamente considera a notao de chaves para os argumentos.

O Demoiselle Framework usa a MessageFormat para efetuar a parametrizao e formatao dos valores. Parausar essa funcionalidade, basta incluir as chaves na string da mensagem e ao inseri-la no contexto especificar osparmetros:


32

Message message = new DefaultMessage("Aluno {0} inserido com sucesso");messageContext.add(message, aluno.getNome());

Eis um exemplo mais avanado do uso de parametrizaes em mensagens:

Message message = new DefaultMessage("As {1,time} do dia {1,date,short} houve {2} na turma {0}");messageContext.add(message, new Integer(502), new Date(), "falta de professor");

O resultado da execuo deste cdigo seria um texto como: s 13:45:05 do dia 03/01/11 houve falta do professorna turma 502. Ou seja, os argumentos {0}, {1} e {2} so substitudos por seus respectivos elementos na ordemem que so passados no mtodo add(), sendo que ainda podemos formatar esses valores.

Dica

possvel passar mais de um parmetro nas mensagens adicionadas no contexto, usandopara isso a sintaxe de formatao da classe java.text.MessageFormat. A ordem dosargumentos passados no mtodo add() reflete nos elementos substitudos na string.

10.4. Internacionalizao das mensagensA DefaultMessage oferece a funcionalidade de internacionalizao da aplicao, ou seja, a disponibilizaodos textos em diversos idiomas. Numa aplicao do tipo Web, o mecanismo de internacionalizao faz com queas mensagens e textos sejam exibidos de acordo com o idioma selecionado pelo usurio na configurao donavegador.

Como j foi citado anteriormente, a implementao DefaultMessage busca os textos das mensagens no arquivode recursos messages.properties, o qual possui entradas no conhecido formato chave = valor. Todavia,para fazer uso desses textos, preciso passar a chave da mensagem desejada como argumento na invocao doconstrutor da classe. Este identificador precisa estar entre sinais de chaves, tal como no exemplo a seguir:

Message message = new DefaultMessage("{ALUNO_INSERIR_OK}");messageContext.add(message, aluno.getNome());

Ou seja, ao invs de usar a string literal, passamos o identificador da chave presente no arquivo de propriedades.

Nota

O smbolo de chaves {} na string do construtor da classe DefaultMessage indica se o textoda mensagem ser recuperado de um arquivo de recursos ou considerado o texto literal.

Eis um exemplo de contedo do arquivo messages.properties destinado a manter por padro os textos noidioma portugus brasileiro (i.e., pt-BR). Veja que ele contm a chave ALUNO_INSERIR_OK usada no exemploanterior:

Internacionalizao das mensagens

33

ALUNO_INSERIR_OK = Aluno {0} inserido com sucessoALUNO_ALTERAR_OK = Aluno {0} alterado com sucessoALUNO_EXCLUIR_OK = Aluno {0} excludo com sucesso

A fim de prover internacionalizao para o idioma ingls americano (i.e., en-US) no exemplo em questo, eis ocontedo do arquivo messages_en_US.properties:

ALUNO_INSERIR_OK = Student {0} was successfully addedALUNO_ALTERAR_OK = Student {0} was successfully modifiedALUNO_EXCLUIR_OK = Student {0} was successfully removed

Similarmente, o arquivo messages_fr.properties se destina a prover as mensagens no idioma francs(independente do pas), contendo as linhas a seguir:

ALUNO_INSERIR_OK = L'tudiant {0} a t ajout avec succsALUNO_ALTERAR_OK = L'tudiant {0} a t modifi avec succsALUNO_EXCLUIR_OK = L'tudiant {0} a t supprim avec succs

Nota

As chaves das mensagens (ex: ALUNO_INSERIR_OK) devem ser as mesmas em todos osarquivos de propriedades. So elas que identificam unicamente uma mensagem, que ao final doprocesso tem o seu texto automaticamente traduzido para o idioma preferido do usurio.

Dica

possvel ainda configurar de modo genrico o idioma, especificando apenas a lngua.Por exemplo, ao invs de ingls britnico (en_GB) e ingls americano (en_US),podemos simplesmente definir o idioma ingls (en). Neste caso, o arquivo dever ser omessages_en.properties.

Nota

Internamente o Demoiselle Framework usa a classe java.util.Locale [http://download.oracle.com/javase/6/docs/api/java/util/Locale.html] presente na API do Java para manipular os textos dasmensages durante a internacionalizao.

Nota

A seleo de idioma na internacionalizao de uma aplicao consiste na definio de:


34

lngua: cdigos formados por duas letras em minsculo listados na ISO-639 (ISO LanguageCode) - exemplos: pt, en, fr, es, de;

pas: cdigos formados por duas letras em maisculo listados na ISO-3166 (ISO Country Code)- exemplos: BR, PT, US, GB.

10.5. Exemplos de implementaoA fim de auxiliar a manuteno das descries das mensagens em uma aplicao diversas solues podem serescolhidas pelos arquitetos e empregadas pelos desenvolvedores. Nesta seo sero mostradas duas sugestespara essa questo, usando interfaces e enumeradores.

A vantagem em se utilizar ambas as solues que diversas mensagens relacionadas podem ser agrupadas,reduzindo assim a quantidade de arquivos a serem mantidos e centralizando a configurao das mensagens.

Sendo assim, uma possvel soluo criar uma interface destinada a armazenar todos os modelos de mensagensde uma determinada severidade a ser usada na aplicao. Nesta interface so declarados campos do tipo Messagecom o modificador final (implicitamente tambm ser public e static). Veja o exemplo de cdigo para ainterface InfoMessages:

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}");}

No exemplo em questo, o texto das mensagens ser recuperado do arquivo de recursosmessages.properties presente no diretrio /src/main/resources/. Eis o contedo desse arquivo:

BOOKMARK_DELETE_OK = Bookmark exclu\u00EDdo\: {0}BOOKMARK_INSERT_OK = Bookmark inserido: {0}BOOKMARK_UPDATE_OK = Bookmark atualizado: {0}

DicaRecomenda-se criar uma interface para cada tipo de severidade (ex: InfoMessages,WarningMessages, ErrorMessages e FatalMessages), agrupando nestas asmensagens usadas exclusivamente para o mesmo fim.

J a segunda abordagem consiste no uso de enumeraes para centralizar os modelos de mensagem. utilizado omesmo arquivo de recursos messages.properties ilustrado na abordagem anterior. Porm, neste caso cadaenumerador da enumerao corresponder a uma chave no arquivo de propriedades.

public enum InfoMessages implements Message {

BOOKMARK_DELETE_OK,

Exemplos de implementao

35

BOOKMARK_INSERT_OK,

BOOKMARK_UPDATE_OK;

private final DefaultMessage msg;

private InfoMessages() { msg = new DefaultMessage("{" + this.name() + "}"); }

@Override public String getText() { return msg.getText(); }

@Override public SeverityType getSeverity() { return msg.getSeverity(); }}

A fim de adicionar mensagens ao contexto, eis um exemplo de cdigo que faz uso do artefato InfoMessages,que funciona no importa qual abordagem escolhida (interface ou enumerao):

@BusinessControllerpublic class BookmarkBC {

@Inject

private MessageContext messageContext;

public void insert(Bookmark bookmark) { ...

messageContext.add(InfoMessages.BOOKMARK_INSERT_OK, bookmark.getDescription()); }

public void update(Bookmark bookmark) { ...

messageContext.add(InfoMessages.BOOKMARK_UPDATE_OK, bookmark.getDescription()); }

public void delete(Bookmark bookmark) { ...

messageContext.add(InfoMessages.BOOKMARK_DELETE_OK, bookmark.getDescription()); }}

No ponto contendo @Inject ser injetado via CDI o contexto de mensagens presente na aplicao, ou seja,uma instncia da interface MessageContext que poder ser utilizada em qualquer mtodo nessa classe.Aqui os mtodos insert(), update() e delete() na classe BookmarkBC manipulam o contexto demensagens em cada invocao destes. O mtodo add() de MessageContext faz com que a mensagem


36

passada como parmetro seja adicionada ao contexto, que ao final exibida para o usurio na camada deapresentao.

37

Resource BundleUm dos requisitos para se construir uma aplicao nos dias de hoje, o de que seja utilizada por pessoasem vrios lugares no mundo e em diferentes lnguas. Portanto, preciso que as aplicaes sejam facilmenteinternacionalizveis. Para isso, existe um recurso no java chamado de Resource Bundle, que nada mais do queum esquema de arquivos properties, onde cada arquivo representa uma lngua e cada um desses arquivospossui um conjunto de chaves e valores, sendo que os valores so os textos que sero exibidos na aplicao eesto na lngua correspondente lngua que o arquivo representa.

O arquivo properties que ser utilizado para montar a aplicao escolhido pelo prprio usurio, seja atravsda lngua definida no browser ou no prprio sistema operacional. Caso o usurio escolha uma lngua que no estdisponvel na aplicao, uma lngua default ser utilizada. Por exemplo: vamos imaginar que em uma aplicaoexistem dois arquivos properties, um em portugus e outro em ingls, e que o arquivo default o ingls. Vamosimaginar tambm que a aplicao Web, portanto a lngua escolhida est definida no prprio browser. Caso estejaconfigurado no browser do usurio a lngua alem e como no existe nenhum arquivo de properties para alemo,a aplicao ser exibida na lngua inglesa, que a lngua configurada como default.

Todos os arquivos so criados praticamente com o mesmo nome. O que diferencia um arquivo do outro oacrscimo da sigla que representa a lngua daquele arquivo. O arquivo que representa a lngua default no temessa sigla ao fim do nome. Seguindo o exemplo citado acima e imaginando que o nome dos nossos arquivos messages, ficaria da seguinte forma: messages.properties seria o arquivo default que representaria a lnguainglesa e messages_pt.properties seria o arquivo da lngua portuguesa. Veja abaixo um exemplo com essesdois arquivos.

messages.properties:

button.edit=Editbutton.new=Newbutton.save=Save

messages_pt.properties:

button.edit=Editarbutton.new=Novobutton.save=Salvar

11.1. Utilizando Resource Bundle no DemoiselleNa verso 2.X do Demoiselle Framework, existe uma fbrica de Resource Bundle que fica no Core e permite seuuso atravs da injeo ou atravs de uma instanciao normal. O grande detalhe que nessa fbrica injetado umobjeto do tipo Locale, isso quer dizer que necessrio criar tambm uma fabrica de Locale. Como a definiode Locale varia de acordo com a camada de apresentao, essas fbricas foram criadas nas extenses deapresentao: demoiselle-jsf, demoiselle-se e demoiselle-vaadin. Na extenso demoiselle-se a definio do Locale dada atravs do Locale definido na mquina do usurio, enquanto que nas extensesdemoiselle-jsf e demoiselle-vaadin essa definio acontece atravs do Locale do browser do usurio,por se tratarem de extenses para camada de apresentao Web. Por default, a fbrica de Resource Bundle vaiinjetar um bundle apontando para o arquivo messages, mas isso pode ser facilmente alterado atravs da anotao@Name. Veja abaixo como utilizar o Resource Bundle no Demoiselle.Utilizando Resource Bundle atravs da injeo:

Captulo 11. Resource Bundle

38

@Inject@Name("messages-core")private ResourceBundle bundle;

public String metodoQueRetornaOValorDaChavebuttonedit() { return bundle.getString("button.edit");}

Utilizando Resource Bundle sem uso de injeo:

private ResourceBundleFactory bundleFactory = new ResourceBundleFactory(Locale.getDefault());private ResourceBundle bundle;

public String metodoQueRetornaOValorDaChavebuttonedit() { bundle = bundleFactory.create("messages-core"); return bundle.getString("button.edit");}

39

Parmetro muito comum em uma aplicao web haver a necessidade de passar parmetros atravs da URL. A passagemde parmetros at que algo fcil e tranquilo de fazer. O chato a captura do parmetro dentro do PageBean, pois toda vez que quisermos faz-lo, temos que acessar o FacesContext, para a partir da pegar oHttpServletRequest e depois recuperar o valor passado. Veja abaixo como ficaria o cdigo.

Passagem do parmetro:

http://localhost:8080/aplicacao/pagina.jsf?parametro=valorParametro

Captura do parmetro pelo Page Bean

public class Classe {

public void metodo() { FacesContext context = FacesContext.getCurrentInstance(); HttpServletRequest req = (HttpServletRequest) context.getExternalContext().getRequest(); String param = req.getParameter("parametro"); }}

12.1. Como passar parmetro no Demoiselle 2.Visando facilitar essa recuperao do parmetro passado atravs da URL, foi disponibilizada na verso 2.Xdo Demoiselle Framework uma funcionalidade atravs da interface Parameter e de sua implementaoParameterImpl, que permite capturar esse valor atravs do uso de injeo. Para isso, basta criar no seu PageBean um objeto do tipo br.gov.frameworkdemoiselle.util.Parameter e anot-lo com @Inject. Onome desse objeto o nome que ser usado para buscar o valor do parmetro. Caso o usurio queira dar umnome diferente ao objeto, ele pode anot-lo com @Name e no valor dessa anotao, colocar o nome do parmetro.Por default o objeto criado tem o escopo de request, mas possvel usar o escopo de sesso ou de viso,bastando anotar o objeto com @SessionScoped ou @ViewScoped, respectivamente. Veja abaixo como ficariaessa passagem de parmetros na verso 2.X do Demoiselle.

Passagem do parmetro

http://localhost:8080/aplicacao/pagina.jsf?parametro=1http://localhost:8080/aplicacao/pagina.jsf?parametroString=valorParametroString

Captura do parmetro pelo Page Bean


@ViewScoped @Inject private Parameter parametro;

Captulo 12. Parmetro

40

@Name("parametroString") @SessionScoped @Inject private Parameter objetoComNomeDiferenteDoParametro;}

12.2. As classes de parmetroA interface Parameter e sua implementao ParameterImpl disponibilizam alguns mtodos, comosetValue(T value), getKey(), getValue() e getConverter(), que servem respectivamente paraatribuir o valor do objeto, capturar o nome do parmetro passado na URL, recuperar o valor passado para aqueleparmetro e capturar o conversor de tipo utilizado. Logo, para usar o valor daquele objeto, basta utilizar o mtodogetValue(), tal como mostrado a seguir:


@ViewScoped @Inject private Parameter parametro;

public void metodo() { System.out.println("Valor do par#metro: " + parametro.getValue()); }}

41

LoggerUma API de logging um recurso interessante para informar o usurio e o desenvolvedor sobre os erros, alertas,resultados de operaes, os recursos acessados e outras informaes a respeito do sistema. Por esse motivo foiimplementada na verso 2.X do Demoiselle Framework uma fbrica de logger que fica no core e visa permitir ainjeo desse recurso baseado na classe org.slf4j.Logger. Veja abaixo como usar o logger no Demoiselle:

public class MinhaClasse {

@Inject private Logger logger;

public void meuMetodo() { logger.debug("logando meu metodo"); logger.warn("mensagem de alerta do meu metodo"); }}

43

TemplatesO Demoiselle Framework prov abstraes de classes para as camadas de apresentao, negcio e persistncia.Tais classes podem ser encontradas no pacote br.gov.frameworkdemoiselle.template e auxiliam odesenvolvedor ao disponibilizar mtodos comuns maioria das aplicaes. seguir iremos exemplificar o uso decada uma delas.

14.1. Camada de persistnciaA classe abstrata JPACrud implementa as operaes bsicas de incluso, remoo, atualizao e recuperaode registros no banco de dados. Sendo assim, possibilita que o desenvolvedor concentre-se na criao de mtodosespecficos para atender as regras de negcio da sua aplicao. Esta classe recebe dois parmetros em notaode genricos:

T representa a entidade que ser tratada

I representa o tipo do identificador da entidade

No exemplo abaixo demonstra-se a utilizao da JPACrud, onde o desenvolvedor precisou implementar apenasum mtodo especfico.

@PersistenceControllerpublic class SuaEntidadeDAO extends JPACrud {

public List findByAlgumCriterioEspecifico(final String criterio) { Query query = getEntityManager().createQuery("select se from SuaEntidade se where se.criterio = :criterio "); query.setParameter("criterio", criterio); return query.getResultList(); }}

14.2. Camada de negcioDe forma semelhante classe JPACrud, a classe DelegateCrud foi criada com o intuito de dispensar odesenvolvedor de implementar mtodos que sero comuns maioria das entidades. Alm disso, esta classeimplementa a injeo de dependncia entre as camadas de negcio e persistncia. Para utiliz-la, trs parmetrosdevem ser passados em notao de genricos:

T representa a entidade


C representa uma classe que implemente a interface CRUD

Segue abaixo um exemplo da utilizao do DelegateCrud. Neste caso, foi implementado um mtodo para validara entidade antes de proceder com a incluso no banco de dados. Para isso, o mtodo insert() fornecido pelaclasse foi sobreescrito.

@BusinessController

Captulo 14. Templates

44

public class SuaEntidadeBC extends DelegateCrud {

private void validateInsert(SuaEntidade se) { // valida os atributos da entidade }

@Override @Transactional public void insert(SuaEntidade se) { validateInsert(se); super.insert(se); }}

14.3. Camada de apresentaoPara a camada de apresentao, existem duas classes que implementam os comportamentos bsicosde navegao para pginas de listagem e edio. Estas classes so AbstractListPageBean eAbstractEditPageBean, respectivamente. De forma semelhante DelegateCrud, estas classes realizama injeo de dependncia da camada de negcio dentro do artefato da camada de apresentao. Ambas recebemdois parmetros em notao de genricos:

T representa a entidade que ser tratada


Estendendo o AbstractListPageBean:

@ViewControllerpublic class SuaEntidadeListMB extends AbstractListPageBean {}

Estendendo o AbstractEditPageBean:

@ViewControllerpublic class SuaEntidadeEditMB extends AbstractEditPageBean {}

45

SeguranaNeste captulo ser tratada uma questo de grande importncia para a maioria das aplicaes e motivo deinfindveis discusses nas equipes de desenvolvimento: controle de acesso. Assim como tudo relacionado aoframework, a implementao de segurana foi projetada de forma simples e flexvel, independente de camada deapresentao ou tecnologia, te deixando livre para implementar sua prpria soluo ou utilizar as extenses prontas,como a que atualmente provemos baseada no Apache Shiro (http://shiro.apache.org).

Para utilizar o modelo de segurana proposto basta utilizar o Demoiselle, pois no ncleo do Framework esto asinterfaces e anotaes que definem o comportamento bsico da implementao.

15.1. ConfigurandoPara um correto funcionamento do Demoiselle necessrio inserir os interceptadores de segurana no arquivosrc/main/WEB-INF/beans.xml.

br.gov.frameworkdemoiselle.internal.interceptor.RequiredPermissionInterceptor br.gov.frameworkdemoiselle.internal.interceptor.RequiredRoleInterceptor

15.2. AutenticaoO mecanismo de autenticao busca verificar a identidade do usurio de um sistema. A forma mais conhecida, ecomum, para executar essa verificao se d por meio de um formulrio de login, geralmente solicitando um nomede usurio e sua respectiva senha. No entanto, outras formas como reconhecimento biomtrico e autenticao portoken, para citar apenas duas, tm ganhado um grande nmero de adeptos.

O Demoiselle deixa o desenvolvedor livre para definir qual forma usar, de acordo com a sua convenincia enecessidade. A pea chave para tornar isso possvel o contexto de segurana, representado pela interfaceSecurityContext. Nessa esto definidos os mtodos responsveis por gerenciar os mecanismos de autenticaocomo, por exemplo, executar login/logout de usurios e verificar se os mesmos esto ou no autenticados.

O contexto de segurana ir direcionar as requisies para a implementao definida pela aplicao. A autenticaoser efetuada por uma classe que implemente a interface Authenticator, cujo mtodo authenticate() responsvelpor executar os passos necessrios para validar a identidade de um usurio. Nesta mesma interface seroencontrados, ainda, os mtodos unAuthenticate() e getUser(), responsveis por, respectivamente, desautenticar eretornar o usurio autenticado.

Para exemplificar, consideremos a autenticao baseada em nome de usurio e senha. O primeiro passo criarum bean para armazenar essas informaes:

@SessionScopedpublic class Credential {

Captulo 15. Segurana

46

private String login; private String senha; // ...}

Feito isso, podemos implementar a classe na qual se deseja adicionar o mecanismo de segurana:

public class ClasseExemplo {

@Inject private Credential credential;

@Inject private SecurityContext context;

public void metodo1() { credential.setLogin(#usuario1#); credential.setSenha(#123#); context.login(); // codigo do metodo context.logout(); } }

Neste caso, a interface SecurityContext e o bean Credential esto sendo injetados na classe utilizando o CDI. Dentrodo mtodo, ao definir o usurio e a senha e invocar context.login(), a implementao de segurana definida irtratar essa requisio de acordo com os critrios estabelecidos.

15.3. AutorizaoO mecanismo de autorizao responsvel por garantir que apenas usurios autorizados tenham o acessoconcedido a determinados recursos de um sistema. No modelo de segurana do Demoiselle 2, a autorizao podeacontecer de duas formas:

Permisso por usurio, atravs da anotao @RequiredPermission

Permisso por papel, atravs da anotao @RequiredRole

Novamente a interface SecurityContext a responsvel pela interao entre as funcionalidades da aplicao e aimplementao de segurana. Nela esto definidos os mtodos que verificam se o usurio possui permisso paraacessar um recurso ou se o usurio est associado a um papel.

A anotao @RequiredPermission pode ser utilizada tanto em classes como em mtodos e possui dois parmetrosopcionais: operation e resource. O primeiro define a operao para a qual se deseja permisso e o segundodefine em qual recurso essa operao ser realizada. Abaixo sero exemplificadas algumas formas de utilizao:

class ClasseExemplo {

@RequiredPermission public void requiredPermissionWithoutDeclaredResourceAndOperation() { }

@RequiredPermission(resource = "contact", operation = "insert")

Criando sua implementao

47

public void requiredPermissionWithDeclaredResourceAndOperation() { }}

Observe o mtodo cuja anotao no possui parmetros. Nesse caso sero considerados como recurso e operaoo nome da classe e do mtodo, respectivamente. Uma outra possibilidade seria utilizar a anotao @Name, tantona classe como no mtodo, de forma a possibilitar uma descrio mais amigvel para o usurio.

Assim como na autenticao, o contexto de segurana possui mtodos destinados a delegar as requisiesde autorizao para a implementao de segurana. No caso da anotao @RequiredPermission , o mtodohasPermission(String resource, String operation) executa esta tarefa. Para tanto, deve existir uma classe queimplemente a interface Authorizer, cujo mtodo hasPermission(Object resource, String operation) verifica se ousurio logado possui permisso para executar uma determinada operao em um recurso especfico.

Ainda na interface Authorizer, pode-se notar a existncia do mtodo hasRole(String role), responsvel por verificarse o usurio logado possui um papel especfico. Este mtodo chamado pelo contexto de segurana, por meiodo seu mtodo hasRole(String role), para tratar as requisies que possuam a anotao @RequiredRole. Essaanotao possui um parmetro obrigatrio, no qual podem ser definidos uma simples role ou um array delas.

class ClasseExemplo {

@RequiredRole("simpleRoleName") public void requiredRoleWithSingleRole() { }

@RequiredRole({ "firstRole", "secondRole", "thirdRole", "fourthRole", "fifthRole" }) public void requiredRoleWithArrayOfRoles() { } }

As restries de segurana pode ser utilizadas, ainda, em pginas web, com o auxlio de Expression Language,como no exemplo abaixo:

Nesse caso, a habilitao de um boto est condicionada existncia de permisso para o usurio autenticado nomomento executar a operao insert no recurso contact.

15.4. Criando sua implementaoAps toda essa explicao, fica a dvida: como implementar um esquema de segurana sem utilizar a extensoexistente?

O primeiro passo criar classes para implementar as interfaces Authenticator e Authorizer. O Demoiselle detectaautomaticamente a implementao, e torna essa classe a implementao padro dessas interfaces:

public class MeuAuthenticator implements Authenticator {

Captulo 15. Segurana

48

@Override public boolean authenticate() { // Escreva aqui seu codigo de autenticacao return true;

}

@Override public User getUser() { // Escreva aqui seu codigo para retornar o usuario logado return null; }

@Override public void unAuthenticate() { // Escreva aqui seu codigo de desautenticacao } }

public class MeuAuthorizer implements Authorizer {

@Override public boolean hasRole(String role) { // Escreva aqui seu codigo de verificacao do papel return false; }

@Override public boolean hasPermission(Object resource, String operation) { // Escreva aqui seu codigo de verifica##o de permissao return false; } }

Pronto! Sua aplicao j possui uma implementao de segurana definida. Caso sua ela no implemente essasinterfaces, no momento em que forem chamadas, o framework lanar uma exceo informando que a aplicaoprecisa implement-las.

Se voc tem mais de uma implementao de Authenticator e/ou Authorizer (o que pode acontecer, porexemplo, quando se necessite de uma implementao na aplicao principal, e outra para os testes), dever definirno arquivo demoiselle.properties qual classe ser a padro:

frameworkdemoiselle.security.authenticator.class=projeto.MeuAuthenticatorPadrao frameworkdemoiselle.security.authorizer.class=projeto.MeuAuthorizerPadrao

Cuidado

O Demoiselle tambm oferece o componente Authorization [http://demoiselle.sourceforge.net/docs/demoiselle-guide-components/1.2.0/html/authorization-master.html] que facilita o uso desegurana com JAAS. Obviamente, no possvel utiliz-los ao mesmo tempo. H arqutipos

Criando sua implementao

49

Maven que j trazem esse componente como dependncia, por isso sempre confira o arquivoPOM.XML e se for o caso retire essa dependncia.

51

PaginaoNeste captulo sero considerados os seguintes assuntos:

Motivao para o uso de um mecanismo padronizado para paginao;

Funcionamento e uso da estrutura Pagination e do contexto de paginao (PaginationContext).

16.1. Introduo ao mecanismoA apresentao de conjuntos de registros de mdio a grande porte em formato de tabelas em aplicaes Webgeralmente requer um mecanismo de paginao, o qual permite ao cliente ver apenas um pedao do resultadofinal, podendo este navegar para frente e para trs atravs dos registros. A menos que o conjunto de registros sejagarantidamente pequeno, qualquer aplicao do tipo Web com funcionalidades de busca e/ou listagem de registros,precisa ser dotada de paginao.

O mecanismo de paginao para as aplicaes fornecido pelo Demoiselle Framework consiste em um algoritmodirecionado ao banco de dados (i.e., Database-Driven Pagination). Essa abordagem, apesar de requerer instruesSQL especficas para obter pores determinadas de registros, a mais utilizada por ser mais eficiente e produzirmenos redundncia de dados, diminuindo assim trfego de rede, consumo de memria e reduzindo o tempo deresposta.

fornecido em tempo de execuo um contexto de paginao, o qual tem escopo de sesso e armazenaa informao de paginao de cada entidade (i.e., bean) que necessite de tal mecanismo. Esse contexto compartilhado entre as diversas camadas da aplicao, especificamente entre as camadas de viso e persistncia.Dessa maneira, a paginao dos dados transparente para a camada intermediria (i.e., negcio) e no interferena modelagem das classes de um projeto.

16.2. Cdigos de suporteO mecanismo de paginao do Demoiselle Framework permite que os parmetros para a consulta no banco sejamconfigurados de forma bastante prtica. Por outro lado, a consulta paginada ao banco j feita pela extensodemoiselle-jpa. Dessa forma, basta ajustar os parametros da paginao, e pedir as consultas normalmente.O resultado da consulta ento passado para algum componente de iterao de dados com suporte ao mecanismoconhecido como Lazy Load (ou Lazy Loading).Faro parte do cdigo de suporte para paginao:

A classe Pagination: usada para manipular a paginao dos dados resultantes, contendo os camposcurrentPage (pgina atual, selecionada na camada de viso), pageSize (tamanho da pgina, a quantidadede registros que ela comportar) e totalResults (a quantidade de resultados existentes na base de dados);

A classe PaginationContext: contexto usado para armazenar e fornecer estruturas do tipo Pagination;

A classe PaginationConfig: armazenador de configuraes referentes paginao.

Cdigos internos de suporte no Core:

public class Pagination {

private int currentPage; private int pageSize; private Long totalResults; private Integer totalPages; // ...

Captulo 16. Paginao

52

}

@SessionScopedpublic class PaginationContext {

private final Map

Implementao na aplicao

53

// ...

public Pagination getPagination() { return paginationContext.getPagination(getBeanClass(), true); }

public int getPageSize() { return paginationConfig.getDefaultPageSize(); }

public int getMaxPageLinks() { return paginationConfig.getMaxPageLinks(); }}

16.3. Implementao na aplicaoVeremos nessa seo como implementar a paginao em uma aplicao Java. Para esse exemplo tomamos comobase a aplicao de Bookmarks fornecida pelo arqutipo JSF com JPA do Demoiselle Framework (para maioresdetalhes ver Arqutipos). Iremos utilizar o componente DataTable do PrimeFaces, que oferece o mecanismo deLazy Loading conhecido como LazyDataModel, muito til para paginao e classificao de dados.

Primeiro preciso configurar um objeto LazyDataModel no construtor do Managed Bean (BookmarkList nesseexemplo): instanci-lo e sobrescrever o mtodo abstrado load, que recebe vrios argumentos. Esses argumentosso recuperados na pgina jsf que carrega a instncia do objeto LazyDataModel.

Dentro do mtodo load iremos pegar do contexto de paginao uma instncia da implementao da interfacePagination e ajustar alguns dos seus parmetros para: indicar a partir de qual item a paginao deve iniciar,e o tamanho (quantidade de itens) de cada pgina. Esses dados so usados no mtodo findAll(), da classeJPACrud (extenso JPA), que utiliza o contexto de paginao para pegar os parametros e fazer a consulta nobanco buscando apenas os itens que esto dentro da pagina que o parametro first indicar. O resultado passadopara a instncia do LazyDataModel, que responsvel por exibir os dados de forma apropriada.

classe BookmarkList devem ser adicionados os seguintes trechos de cdigo:

// ...import java.util.Map;import br.gov.frameworkdemoiselle.pagination.Pagination;// ...

public BookmarkListMB() {

private LazyDataModel lazyModel; lazyModel = new LazyDataModel() {

@Override public List load (int first, int pageSize, String sortField, SortOrder sortOrder, Map filters){

Pagination pagination = getPagination(); pagination.setPageSize(pageSize); pagination.setFirstResult(first);

List itemsList = bc.findAll();

Captulo 16. Paginao

54

lazyModel.setRowCount(pagination.getTotalResults());

return itemsList; } }; // ... public LazyDataModel getLazyModel() { return lazyModel; } // ...}

No arquivo messages.properties adicione as linhas:

page.first=0page.rows=4page.max.links=3

Na pgina JSF bookmark_list.xhtml, substitua a linha:

por:

Com essas alteraes simples, a aplicao Bookmarks passa a utilizar o mecanismo de paginao oferec

Documents

Demoiselle Framework Reference