Desenvolvimento de Aplicações com Entities Versão 3.1

Desenvolvimento de Aplicações com Entities Versão 3.1 Marcius Gomes Brandão - marciusbrandao@gmail.com Antônio Gomes Ferreira - antogofe@yahoo.com.br Hélio Augusto Sabóia Moura - helioasmoura@gmail.com

VIII.1 - Coringas...18 Entities 3.1 I - Introdução...3 I.1 - Origem...3 I.2 - Propriedade Intelectual...3 IX - Ação...19 IX.1 - Ações no Entities...20 IX.2 - Ação com Argumentos...20 IX.3 - Métodos Escondidos...20 IX.4 - Transação...20 I.3 - Garantia...3 X - Distribuição...21 II - Conceitos Básicos...4 XI - Configuração de SGBD...21 XI.1 - Múltiplas Bases de Dados...21 II.1 - Domínio...4 II.2 - JavaBeans...4 XII - Casos de Sucesso...22 II.3 - JPA...4 XII.1 - DER...22 II.4 - Repositório...4 XII.1.a - Controle de Ponto...22 XII.1.b - Avaliação de Temporários...22 II.5 - Interface Gráfica de Usuário...4 XII.1.c - Pró-Estradas...22 II.5.a - CRUD...5 XII.1.d - Sistema Corporativo SIGDER...23 II.5.b - Visões...5 II.5.c - Ações...5 XII.2 - ETICE...24 XII.2.a - Cinturão Digital...24 II.6 - Máquina de Estado...5 III - Preparação...5 XIII - Evolução do Entities... III.1 - Pré-Requisitos...5 XIV - Relatórios... III.2 - Distribuição do Entities...5 XV - Segurança... III.3 - Configuração...5 XVI - Uma Aplicação Completa... IV - Primeira Aplicação...6 XVII - Referências do Entities... IV.1 - Rodando os Exemplos...6 XVII.1 - Anotações... IV.1.a - Base de Dados...6 XVII.1.a - @ActionDescriptor... IV.2 - QuickStart...6 XVII.1.b - @Editor... IV.3 - Rodando a Aplicação...7 XVII.1.c - @EntityDescriptor...26 IV.3.a - Incluindo...7 XVII.1.d - @Param...26 IV.3.b - Excluindo...7 XVII.1.e - @ParameterDescritor...26 IV.3.c - Alterando...7 XVII.1.f - @PropertyDescriptor...26 IV.4 - Entendendo a Aplicação...8 XVII.1.g - @Transaction...26 IV.4.a - Propriedade tipo String...8 XVII.1.h - @View...26 IV.4.b - Propriedade tipo Data...8 XVII.1.i - @Views...27 IV.4.c - Propriedade tipo Enumeração...8 XVII.2 - Implementação de Repositórios...27 IV.4.d - Propriedade tipo Booleano...8 XVII.3 - LLE Linguagem de Layout do Entities...28 IV.4.e - Propriedade tipo Numérico...8 XVII.3.a - Resumo da Extended Backus-Naur Form...29 IV.4.f - Validação...9 IV.4.g - Campos Largos...9 IV.5 - Customizando...9 IV.6 - Adicionando Novas Entidades...10 IV.6.a - Menu da Aplicação...10 IV.7 - Mudando a Pele Skins...11 IV.8 - Internacionalização...11 IV.9 - Distribuição da Aplicação...11 IV.10 - Passos Para Montar uma Aplicação...11 V - Tela Formulário Padrão...12 V.1 - Só para Leitura...12 V.2 - Visões Padrões...12 V.2.a - TABLE...12 V.2.b - TABLE_CRUD...12 V.2.c - FORM...12 V.2.d - FORM_CRUD...12 VI - Relacionamentos...13 VII - Indo Além do CRUD...14 VII.1 - Primeira Visão...15 VII.2 - Segunda Visão...15 VII.3 - Terceira Visão...16 VII.4 - Quarta Visão...16 VII.5 - Quinta Visão...17 VIII - Adicionando Filtros...18 Segunda-feira, 3 de Maio de 2010-1

Segunda-feira, 3 de Maio de 2010-2

Célula de Tecnologia da Informação e Comunicação do Departamento de Edificações e Rodovias do Estado do Ceará I - Introdução CETIC/DER. Deste então vem sendo estudado por outros setores do O Entities é um framework Java com a finalidade de simplificar o governo do Ceará para possível uso. Principalmente nos órgãos que desenvolvimento de aplicações gerando automaticamente a interface estão migrando para a plataforma Java. gráfica de usuário a partir do modelo de negócio. A CETIC/DER vem utilizando o Entities desde janeiro de 2009 em Em outras palavras, o Entities gera a interface gráfica de usuário a partir de anotações Java inseridas nas classes de entidades JPA (Java Persistence API). Assim sendo o desenvolvedor foca sua atenção nas classes de negócio da aplicação o que resulta em um desenvolvimento mais eficiente, em tempo e qualidade. seu desenvolvimento e em muito tem colaborado com críticas e sugestões que vêm moldando o produto final. O analista de sistemas Antônio Ferreira, da CETIC/DER, se envolveu no projeto Entities como usuário projetista e desenvolvedor de aplicações fornecendo importante realimentação dos resultados O Entities foi todo desenvolvido visando atender a metodologia de obtidos e necessidades a serem cobertas pelo Entities. Objetos Expostos (Objetos Nús) Naked Objects que por sua vez Recentemente na CETIC/DER o analista de sistemas Hélio Moura leva à metodologia de Projeto Dirigido para o Domínio - DDD - Domain se juntou ao analista Marcius Brandão no desenvolvimento e Driven Design - onde o desenvolvedor representa o domínio de uma documentação do Entities. forma que seu conteúdo fique bem claro para ele e para o cliente. A representação do domínio se torna uma linguagem comum entre o I.2 - Propriedade Intelectual desenvolvedor e o cliente. Busca-se assim chegar a uma estrutura de entidades e seus relacionamentos que represente claramente os O Entities é um software livre e, assim sendo, pode ser usado dados e necessidades do cliente. para quaisquer finalidades sem incidir quaisquer ônus sobre seu uso. Partindo-se deste conceito, pode-se pensar em uma geração O Entities é mantido por seus autores. Críticas e sugestões devem automática de telas a partir do domínio uma vez que o domínio ser endereçadas a: representa claramente as necessidades do cliente. Marcius Gomes Brandão marciusbrandao@gmail.com O sítio Domain-Driven Design Community - contém boas Antônio Gomes Ferreira antogofe@yahoo.com.br referências sobre DDD - http://domaindrivendesign.org. Hélio Augusto Sabóia Moura helioasmoura@gmail.com Em resumo, com o Entities é possível se obter a interface gráfica de usuário a partir de anotações específicas nos códigos das I.3 - Garantia entidades do domínio. O Entities se apresenta exatamente como está, isto é, não é fornecida por parte de seus autores nenhum tipo de garantia quanto a suas funcionalidades e resultados de seu uso. Qualquer pessoa ou O Entities está baseado nas pesquisas sobre Naked Objects e entidade que venha utilizá-lo, o fará por sua própria conta e risco. DDD; em ideias e códigos de projetos de software livres baseados 0 nesta metodologia e na experiência em desenvolvimento de seus criadores. I.1 - Origem A pesquisa teórica sobre Naked Objects e DDD pode ser referenciada pelos sítios Naked Objects - http://www.nakedobjects.org DDD Community - http://www.domaindrivendesign.org que são boas raízes para pesquisas sobre o assunto. Uma boa introdução ao DDD é dada no artigo: Almeida, R. - Java & DDD, Revista Java Magazine, edição 72, setembro/2009. Entre os projetos pesquisados estão: Naked Objects - http://www.nakedobjects.org OpenXava - http://www.openxava.org Trails - http://www.trailsframework.org Crank http://code.google.com/p/krank O motivo básico de se criar um novo projeto é o de tornar mais simples de se usar as ideias do Naked Objects e do DDD por parte dos desenvolvedores, além de dar mais flexibilidade no desenvolvimento e facilidade de uso. O desenvolvimento é feito com total aderência ao JPA independente de outras classes e com vasto uso de JavaBeans. e Além disto o Entities visa poder especificar interfaces gráficas mais customizáveis, dando ao desenvolvedor não só a possibilidade de criar páginas padrões CRUD e Lista-Detalhe simples mas também páginas com layouts mais sofisticados sem perder a simplicidade na definição destes layouts e manter sintonia com os preceitos do Naked Objects. O Entities foi criado pelo analista de sistemas Marcius Brandão. O Entities tomou um grande impulso quando foi adotado pela Segunda-feira, 3 de Maio de 2010-3

que podem ser manipulados visualmente com a ajuda de uma ferramenta de desenvolvimento. II - Conceitos Básicos O Entities é baseado nos conceitos de Naked Objects, onde a premissa é a de que os objetos devem ser expostos ao usuários para que este possa manipulá-los. Em resumo, um JavaBean possui as seguintes características: implementa a interface java.io.serializable (possibilita a persistência e restauração do objeto) O objetivo é concentrar o esforço de desenvolvimento na definição das entidades e deixar que o framework gere a visualização destas entidades expondo-as ao usuário. possui um construtor sem argumentos possui métodos get e set para permitir o acesso a suas propriedades. Porque implementar N camadas se você precisa implementar apenas uma! Pode conter métodos de tratamento de eventos. O padrão JavaBean permite que as propriedades de um objeto sejam conhecidas programaticamente por meio da reflexão. (www.nakedobject.com) O framework também ajuda na construção de serviços básicos como o CRUD, por exemplo. Muitos dos serviços exigidos pelas aplicações de negócios podem ser implementados genericamente (www.nakedobject.com) O Entities faz alto uso de reflexão para montar a interface gráfica de usuário automaticamente. II.3 - JPA JPA Java Persistence API é a base da definição de domínio no Entities. IGU Validação ETL Domínio Segurança Relatório BI Repositótio IGU Interface Gráfica de Usuário ETL Exportar, Transformar e Carregar (Load) BI Business Inteligency II.1 - Domínio O domínio é o conjunto de entidades da aplicação. O Entities consulta as anotações do JPA para saber as características de apresentação das propriedades de uma entidade. A JPA usa os conceitos de JavaBeans na sua definição o que torna as propriedades de uma entidade acessíveis ao Entities por meio da reflexão. A JPA é utilizada para a construção de objetos completos no que tange seus comportamentos. Nota: Um objeto completo é aquele possui suas propriedades e todos os métodos que o manipulam. Objetos completos são imprescindíveis na metodologia Naked Objects pois o usuário deve ter em mãos os objetos e poder executar suas ações. II.4 - Repositório O Entities utiliza o conceito de repositório do DDD. Um repositório encapsula toda a lógica necessária para obter referências a objetos. Lembrando que no conceito de Naked Objects uma entidade possui Os objetos do domínio não precisam lidar com infra-estruturas todos os métodos que regem seu comportamento. Estes método são específicas para acessar outros objetos do domínio. as ações do Entities. O repositório abstrai toda a complexidade de acesso a outros O domínio deve ser projetado de maneira a deixar claro ao usuário objetos. quais são os objetos que deve manipular. Os objetos são mostrados ao usuário que pode criar novos objetos, No Entities pode-se criar novos repositórios para se dar acesso a alterar objetos, excluir objetos e disparar ações dos objetos com o fim novas estruturas. de cumprir sua meta. II.5 - Interface Gráfica de Usuário Nota: Usando uma aplicação baseada no Naked Objects, o usuário deixa de ser um seguidor do processo comandado pela aplicação para ser o condutor do processo por meio da manipulação dos objetos do domínio. Enfim, o usuário deixa de ser um operador leigo para ser um conhecedor do processo no qual atua. O Entities automatiza a geração da interface gráfica do usuário criando visões padrões para as entidades. Por meio de anotações Java o desenvolvedor pode influir na maneira que cada propriedade da entidade vai ser apresentada. Com isto, pode-se customizar validadores e outros artefatos que facilitem a representação e edição de uma propriedade de entidade. É essencial que o domínio seja construído junto com o cliente para Para todo tipo de propriedade o Entities possui uma forma padrão que este possa ter total conhecimento das entidades envolvidas e de de apresentação de edição e de apresentação somente para leitura. suas funcionalidades. Em geral estas formas são as mais comumente utilizadas e são Na realidade o domínio deve expressar ao máximo o problema do providas de recursos de edição ricos em funcionalidades. cliente utilizando-se de termos comuns no dia dia do cliente. II.2 - JavaBeans O conceito de JavaBeans leva a componentização ao mundo Java. Enfim, com anotações do Entities é possível definir não só as formas nas quais as propriedades são apresentadas e editadas, como também definir a ordem de apresentação destas propriedades. Nota: JavaBeans são componentes reutilizáveis de software Segunda-feira, 3 de Maio de 2010-4

II.5.a - CRUD O Entities provê telas CRUD básicas baseadas em tabelas ou em formulários. Desta forma tratar de operações relacionadas a CRUD não demanda nenhum esforço do desenvolvedor. III - Preparação III.1 - Pré-Requisitos II.5.b - Visões Para se desenvolver aplicações utilizando O Entities permite que se crie visões especiais para a apresentação necessários os seguintes conhecimentos: de resultados de consultas JPQL (Java Persistence Query Language) JavaBeans de modo a se obter visões diferentes em momentos diferentes para a Estrutura de aplicações Web em Java mesma consulta. JPA - Java Persistence API Para a definição de uma visão o Entities utiliza um texto simples Os softwares necessários são: (String) como propriedade de uma anotação própria para entidades. JDK 6 - Java Development Kit 6 Como a premissa de manter o foco na programação de entidades, a Netbeans 6.8 definição de visões resultantes de consulta é feita em uma anotação aplicada à entidade que mais se adeque à visão criada. O objetivo é evitar de se criar outras estruturas de dados, como arquivos XML, que foram feitas para serem manipuladas por IDEs mas que se tornou comum passar esta tarefa para o desenvolvedor. o Entities, são III.2 - Distribuição do Entities O Entities é distribuído como uma aplicação vazia de nome Entities-Blank. Para não desviar a atenção do desenvolvedor sobre a definição de A aplicação vazia Entities-Blank é uma aplicação Web préentidades, foi criada uma linguagem simples para descrever o layout configurada com todos os recursos necessários ao Entities. da apresentação do resultado da consulta. A Entities-Blank pode ser baixada a partir do endereço: A Linguagem de Layout do Entities LLE provê a capacidade de se definir layouts de maneira muito simples por meio de um único texto http://redefoks.googlecode.com/files/entities-blank-3.1.zip (String). Este arquivo ZIP deve ser descompactado em qualquer pasta. A LLE apenas define a disposição dos campos da visão, a forma na O Entities-Blank é uma aplicação preparada para a IDE Netbeans qual cada campo vai ser apresentado é definida na propriedade da entidade dona do campo ou, na ausência de uma especificação 6.8. explícita, na forma padrão do Entities para aquele tipo de propriedade. III.3 - Configuração Sempre visando a simplicidade, o Entities segue a convenção de configuração mínima, isto é, ele já vem totalmente pré-configurado e pronto para funcionar. II.5.c - Ações Assim como as propriedades da entidades, o métodos da entidade Dentre os conceitos de Naked Objects, está o da criação da que não sejam do grupo 'get/set' são expostos ao usuário como aplicação incrementalmente, partindo-se de protótipos chegando, após comandos ou ações (em geral na forma de um botão). sucessivos refinamentos, à aplicação final. Portanto, as telas geradas pelo Entities dão ao operador acesso às A configuração inicial do Entities permite a elaboração rápida de propriedades e ao métodos das entidades. Tornando assim o objeto exposto ao operador como na premissa maior da metodologia Naked protótipos. Objects. Após todo o refinamento do protótipo, o desenvolvedor fica a cargo de configurar somente os itens que desejar diferenciar em sua aplicação, como a definição da base de dados por exemplo. II.6 - Máquina de Estado Quando o desenvolvimento é voltado a objetos, como em Naked Objects, não existe a figura de casos de uso e sim objetos a serem manipulados via seus métodos (ações). 0 A melhor maneira de se implementar casos de uso no Entities é por meio de máquinas de estados. No Naked Objects tudo é manipulado via instâncias de entidades, desta forma um estado da máquina de estados precisa ser uma entidade a ser instanciada. O estado da máquina de estado se relaciona com as entidades envolvidas no procedimento como qualquer outra entidade e possui métodos que permitem ou não a mudança para um outro estado. Desta forma a máquina de estado é persistida indicando o estado de um procedimento envolvendo certas entidades. 0 - Segunda-feira, 3 de Maio de 2010-5

IV - Primeira Aplicação IV.2 - QuickStart O projeto Entities-Blank gera uma aplicação Web, cuja interface Nota: Fontes em 'exemplos/quickstart' gráfica gerada é baseada no JSF - JavaServer Faces usando o Facelets para componentização e disposição (layout). A biblioteca de Como primeira aplicação será criada uma entidade de nome componentes RichFaces (componentes JSF) é usada para a maioria Pessoa, no pacote model, e a partir dela serão geradas as telas de dos componentes utilizados pelo Entities. edição no padrão CRUD (Create, Read, Update, Delete). Nota: Outras bibliotecas de componentes e outros frameworks são usados no intuito de resolver as necessidades de visualização da aplicação gerada, mas o uso destes outros artefatos são totalmente abstraídos do desenvolvedor pelo Entities. As telas são geradas em tempo de execução, sendo assim, não existem arquivos de telas a serem editados posteriormente pelo desenvolvedor. Todo desenvolvimento é feito sobre o domínio! O fato das telas da interface gráfica serem geradas automaticamente, não impede que se produzam telas da forma normal. Assim sendo, nos casos onde o Entities não gera telas adequadas, estas podem ser escritas na forma tradicional, editando-se seus arquivos xhtml. IV.1 - Rodando os Exemplos Todos os exemplos contidos neste manual encontram-se na pasta exemplo dentro da pasta raiz do projeto Entities-Blank. Cada pasta de exemplo contém uma pasta src e uma pasta web. A pasta src contém as fontes de código Java e a configuração do Hibernate; esta pasta deve ser substituir a pasta de mesmo nome do projeto Entities-Blank. A pasta web contém o arquivo main.xhtml este arquivo deve substituir o arquivo de mesmo nome e local no projeto Entities-Blank. IV.1.a - Base de Dados A aplicação Entities-Blank vem configurada para utilizar uma base de dados Java DB embutida. Desta forma para rodar os exemplos é necessário apenas iniciar o servido Java DB. Clicar com o botão direito do ratinho em 'Serviços / Banco de Dados / Java DB' e escolher a opção Inicializar servidor. 0 - Na aplicação vazia, o Entities-Blank, deve-se criar a entidade Pessoa no pacote model. 14 @Entity 15 public class Pessoa implements Serializable { 16 17 public enum Sexo { MASCULINO, FEMININO } 18 19 @Id 20 @GeneratedValue 21 private long id; 22 23 private Sexo sexo; 24 @Column(length=40) 26 @Pattern(regex = "^[A-Z,0-9\\s]{0,40}$") 27 @NotEmpty(message = "Informe o nome da pessoa") 28 private String nome; 29 30 @Temporal(javax.persistence.TemporalType.DATE) 31 private Date datadenascimento; 32 33 @Column(scale = 1, precision = 2) 34 private float altura; 35 36 private boolean deficientefisico; 37 38 @Lob 39 @Column(length=10240) // 10kb 40 private byte[] foto; 41 42 // implementação dos GETTERS & SETTERS 100 // implementação do equals e hashcode 123 } Na pasta 'Páginas Web' o arquivo main.xhtml é a página principal da aplicação e deverá conter o código necessário para apresentar as páginas CRUD da aplicação. O arquivo main.xhtml contém: 1 <?xml version='1.0' encoding='utf-8'?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 > 3 <html xmlns="http://www.w3.org/1999/xhtml" 4 xmlns:ui="http://java.sun.com/jsf/facelets" 5 xmlns:h="http://java.sun.com/jsf/html" 6 xmlns:e="http://entities.br"> 7 <body> 8 <ui:composition template="./template.xhtml"> 9 <ui:define name="body"> <h:messages/> <e:view name="model.pessoa@table_crud"/> 13 </ui:define> 14 </ui:composition> 15 </body> 16 </html> As linhas em negrito foram adicionadas. Por fim, deve-se incluir a referência à entidade Pessoa no arquivo hibernate.cfg.xml para que esta entidade possa ser persistida. 13... 14 <mapping class= "model.pessoa" /> 15 </session-factory> 16 </hibernate-configuration> Pronto! Uma vez criada a entidade só com anotações JPA e sendo esta referenciada na página principal da aplicação, pode-se compilar e executar a aplicação CRUD. Segunda-feira, 3 de Maio de 2010-6

Salvar IV.3 - Rodando a Aplicação No Netbeans para limpar e compilar a aplicação tecla-se Shift+F11 e para executar tecla-se F6. Nota: Devido ao uso da base de dados embutida nas aplicações exemplo, antes de cada execução deve-se parar o servidor Web Tomcat. No Netbeans basta abrir a aba de projetos, expandir o item servidores, clicar com o botão direito do ratinho sobre o servidor Tomcat e escolher a opção Parar. Note-se que o campo 'Foto' é apresentado com um botão para escolher um arquivo para subir (upload) pois está no modo de edição. Clicando-se sobre o comando Salvar, a tabela é relistada com a entidade incluída mostrada só para leitura. Uma mensagem indicando que a inclusão foi feita também é apresentada. Mensagem A tela a seguir é apresentada no navegador (browser): Note-se que o campo 'Foto' é apresentado com um botão para baixar (download) pois está no modo de apresentação. Na tela inicial identificamos os seguintes campos: Após a inclusão de mais duas pessoas temos: Nome da Aplicação Nome da Entidade Barra de Ferramentas Barra de navegação Incluir Alterar Excluir Nesta figura são apresentados os diversos componentes da tela IV.3.b - Excluindo com suas identificações funcionais. Nota-se claramente o nome da aplicação, o nome da entidade na qual se deseja realizar operações Agora a segunda entidade é marcada para ser excluída: de CRUD, a barra de ferramentas com os comandos para incluir, alterar e excluir instâncias da entidade e a barra de navegação. Excluir A barra de navegação é usada para a paginação da apresentação do conjunto de entidades buscadas. O Entities automaticamente pagina a apresentação em lista em páginas de 10 entidades por vez. Entidade marcada para ser excluída Como se pode ver na figura 1, apenas o comando de inclusão está habilitado, pois ainda não existe nehuma entidade pessoa criada. IV.3.a - Incluindo Ao se clicar no comando incluir, uma nova entidade Pessoa é criada e a tela é atualizada para mostrá-la. Salvar Ao se clicar sobre o comando excluir, a seguinte mensagem é mostrada pedindo a confirmação da operação: Cancelar Após se confirmar a exclusão, a lista de entidades vola junto com a Deve-se preencher os campos da nova entidade criada e clicar mensagem confirmando a exclusão. sobre o comando salvar. IV.3.c - Alterando Lista de opções Aproveitando-se da mesma figura, um outro exemplo é mostrado: a primeira entidade é marcada para ser alterada e clica-se no comando Alterar. Note que o campo Sexo ficou com a lista de opções da enumeração Sexo definida na entidade Pessoa. Segunda-feira, 3 de Maio de 2010-7

Mensagem Alterar Entidade marcada para ser alterada IV.4.b - Propriedade tipo Data Propriedades data (sql.date, util.date ou, Calendar) são caixas de texto formatadas no padrão brasileiro (dd/mm/aaaa ) seguidas de um botão que apresenta um calendário. Neste caso a anotação @Temporal(javax.persistence.TemporalType.DATE) é utilizada para apresentar apenas data e as anotações A lista é reapresentada com linha da entidade escolhida preparada para ser editada. @Temporal(javax.persistence.TemporalType.TIME) e @Temporal(javax.persistence.TemporalType.TIMESTAMP) indicam um campo de hora e data-hora respectivamente. Mostrar calendário IV.4 - Entendendo a Aplicação Calendário Base de Dados: O Entities-Blank vem configurado para usar uma base de dados embutida utilizando o Java DB. Desta forma nenhuma configuração de base de dados é necessária no momento. Para se utilizar outro gerenciador de base de dados ou até mesmo múltiplas bases de dados, veja a seção Configuração de SGBD. 34 @Temporal(javax.persistence.TemporalType.DATE) 22 23 24 public enum Sexo { } 29 private Sexo sexo; Nas telas da aplicação nota-se que as colunas da tabela com os 35 private Date datadenascimento; dados da entidade foram nomeadas com o nome do campo na entidade. IV.4.c - Propriedade tipo Enumeração O Entities espera que os nomes dos campos da entidade Propriedades enumeradas são apresentados como lista de valores obedeçam a convenção JavaBean de nomeação de campos onde o nome do campo começa sempre com letras minúsculas e cada (comobox). palavra interna no nome comece com letra maiúscula (também conhecido como notação CamelCase). Por exemplo: o campo datadenascimento (notar a notação CamelCase) foi convertido para Data De Nascimento O Entities utiliza a reflexão para obter os nomes dos campos da entidade. O campos são adicionados à tabela em ordem alfabética. Pois a especificação Java não garante que a ordem dos campos obtidos pela reflexão estejam na mesma ordem em que foram criados na codificação. MASCULINO, FEMININO IV.4.d - Propriedade tipo Booleano Outro detalhe com relação a nomes, está no fato do rótulo usado na identificação da entidade. No lugar de se usar Pessoa foi utilizado As propriedades booleanas (boolean, Boolean) são apresentadas Pessoas no título da tela. O Entities se preocupa com o uso do plural como caixas de seleção (checkbox). adequado quando necessário. O Entities monta o componente de edição de acordo com o tipo do campo e suas anotações. IV.4.a - Propriedade tipo String 38 private boolean deficientefisico; Propriedades String são representados em caixas de texto, IV.4.e - Propriedade tipo Numérico obedecendo o tamanho especificado no JPA além de permitir sua validação por meio de expressões regulares. As propriedades numéricas (int, Integer, float, Float,, double, Double, long, Long, byte, Byte) são apresentadas como caixas de texto formatadas de acordo com a anotação @Column da JPA, obedecendo suas propriedades Scale e Precision. 30 31 32 33 @Column(length=40) @Pattern(regex = "^[A-Z,0-9\\s]{0,40}$") @NotEmpty(message = "Informe o nome da pessoa") private String nome; 36 37 @Column(scale = 1, precision = 2) private float altura; Segunda-feira, 3 de Maio de 2010-8

IV.4.f - Validação Todas as validações disponíveis no Hibernate-Validator são reconhecidas pelo Entities. Como exemplo na aplicação temos o caso em que se deixa o campo Nome em branco: Mensagem Campo vazio IV.4.g - Campos Largos O campo 'Foto é um campo largo. Em resumo, campos largos (@LOB - large object) são mostrados como comandos para baixar (download) se estiver em apresentação e como comandos para subir (upload) se estiver em edição. Na apresentação: 24 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 113 136 } public enum Sexo { MASCULINO, FEMININO } @Id @GeneratedValue @PropertyDescriptor(index = 1) private long id; @PropertyDescriptor(index = 2) private Sexo sexo; @Column(length = 40) @PropertyDescriptor(index = 3) @Pattern(regex = "^[A-Z,0-9\\s]{0,40}$") @NotEmpty(message = "Informe o nome da pessoa") private String nome; @PropertyDescriptor(index = 4) @Temporal(javax.persistence.TemporalType.DATE) private Date datadenascimento; @PropertyDescriptor(index = 5) @Column(scale = 1, precision = 2) private float altura; @PropertyDescriptor(index = 6, displayname = "Def. Físico") private boolean deficientefisico; @Lob @Column(length=10240) // 10kb @PropertyDescriptor(index = 7) private byte[] foto; // implementação dos GETTERS & SETTERS // implementação do equals e hashcode A tela resultante destas modificações fica assim: Na edição: IV.5 - Customizando Nota-se a nova ordem das colunas, que foi ditada pelo campo index da anotação @PropertyDescriptor. Como no caso: Nota: Fontes em 'exemplos/quickstart-customizado' A aplicação Entities-Blank pode ser renomeada para o nome desejado para a aplicação em desenvolvimento. No Netbeans, devese clicar com o botão direito do ratinho sobre o projeto EntitiesBlank e escolher a opção Renomear... : 32 33 @PropertyDescriptor(index = 2) private Sexo sexo; onde a propriedade Sexo ficou na segunda coluna. Outra customização interessante seria a da apresentação da foto no lugar do comando de baixar (download). Para isto basta acrescentar a anotação @Editor no campo Foto da entidade Pessoa. 50 51 52 53 @Lob @Column(length=10240) // 10kb @PropertyDescriptor(index = 7) @Editor(propertyType=PropertyType.IMAGE) private byte[] foto; A anotação @Editor indica que se deve apresentar o campo Foto como uma imagem e não como um comando. A nova tela fica assim: Marcar para mudar o nome da pasta também deve-se, então, digitar o novo nome da aplicação, marcar para renomear também a pasta e clicar sobre o botão Renomear. A ordem de apresentação dos campos, assim como seus rótulos podem ser customizados pela anotação @PropertyDescription do Entities. A classe da entidade Pessoa customizações é mostrada a seguir. modificada com algumas 21 @Entity 22 public class Pessoa implements Serializable { 23 Segunda-feira, 3 de Maio de 2010-9

IV.6 - Adicionando Novas Entidades Nota: Fontes em 'exemplos/mais-de-uma-entidade' 19 // implementação dos GETTERS & SETTERS 62 63 // implementação do equals e hashcode 94 } Resta agora incluir o acesso ao CRUD desta entidade no menu. IV.6.a - Menu da Aplicação Neste exemplo será adicionada a entidade Cargo na aplicação. Como aplicação tem mais de uma entidade, é conveniente se ter um menu para escolher qual entidade será manipulada. Como no exemplo anterior, é preciso editar o arquivo de página padrão do Entities de nome main.xhtml. O arquivo main.xhtml contém: No arquivo main.xhtml duplicamos as linhas 26-45 e as alteramos para referenciar a entidade Cargo. 11<h:form> 15 <rich:panelmenu mode="ajax" width="160px"> 22 <rich:panelmenugroup label="menu" expanded="true"> 26 <rich:panelmenuitem> 32 <e:go label="pessoa" 33 viewname="model.pessoa@table_crud" 34 35 36 <rich:panelmenuitem> 42 <e:go label="cargo" 43 viewname="model.cargo@table_crud" 44 45 46 </rich:panelmenugroup> 47 </rich:panelmenu> 51</h:form> Por fim, deve-se incluir a referência à entidade Cargo no arquivo hibernate.cfg.xml para que esta entidade possa ser persistida. 13... 1 <?xml version='1.0' encoding='utf-8'?> 14 <mapping class="model.pessoa"/> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 15 <mapping class="model.cargo"/> Transitional//EN" "http://www.w3.org/tr/xhtml1/dtd/xhtml116 </session-factory> transitional.dtd"> 17 </hibernate-configuration> 3 <html xmlns="http://www.w3.org/1999/xhtml" 4 xmlns:ui="http://java.sun.com/jsf/facelets" Uma vez criadas as entidades só com anotações JPA e 5 xmlns:h="http://java.sun.com/jsf/html" 6 xmlns:e="http://entities.br"> incluídas no menu as chamadas de edição de cada uma delas, pode7 <body> se compilar e executar a aplicação. 8 <ui:composition template="./template.xhtml"> 9 <ui:define name="body"> A tela com o menu fica assim: 10 <!-11 Escrever tela aqui! 12 --> 13 </ui:define> 14 </ui:composition> 15 </body> 16 </html> Pronto! Como agora existe um menu, inicialmente somente o menu é As linhas 10-12 devem ser substituídas pelo código que referencia apresentado. Clica-se na opção Pessoa e tem-se a tela de edição da as páginas CRUD com menu: entidade Pessoa. 01<h:form> 02 <rich:panelmenu mode="ajax" width="160px"> 03 <rich:panelmenugroup label="menu" 04 expanded="true"> 05 <rich:panelmenuitem> 06 <e:go label="pessoa" 07 viewname="model.pessoa@table_crud" 08 09 10 </rich:panelmenugroup> 11 </rich:panelmenu> 12</h:form> Clica-se sobre a opção Cargo e obtém-se a tela de edição da Na linha 3 o rótulo do grupo de menu foi denominado 'Menu' entidade Cargo, que após algumas edições tem-se: (label="menu"); na linha 6 o rótulo do item de menu foi denominado 'Editar' (label="pessoa"); na linha 7 está sendo indicado ao Entities que Título sem acento se deseja como tela um CRUD sobre a entidade Pessoa utilizando a forma de tabela (viewname="model.pessoa@table_crud"). Desta a forma a aplicação já está preparada para trabalhar com menu e editar a entidade Pessoa. Deve-se então criar uma nova entidade, por exemplo Cargo no mesmo pacote model : 9 @Entity 10 public class Cargo implements Serializable { 11 12 @Id 13 @GeneratedValue 14 private long id; 15 @NotEmpty(message="Informe o título do cargo") 16 private String titulo; 17 private String sigla; 18 Note-se que o rótulo Titulo está sem acentuação porque o nome do campo da classe Cargo está sem acentuação, como é comum de se fazer em programa,ão. Para corrigir este problema foi criada a anotação @PropertyDescryptor no Entities. Podemos ver esta anotação na linha 19 da entidade Cargo. Uma anotação similar também foi usada na linha 12. 11 @Entity Segunda-feira, 3 de Maio de 2010-10

12 @EntityDescriptor(displayName = "Cargo", pluraldisplayname = "Cargos") 13 public class Cargo implements Serializable { 14 15 @Id 16 @GeneratedValue 17 private long id; 18 @NotEmpty(message="Informe o título do cargo") 19 @PropertyDescriptor(displayName = "Título") 20 private String titulo; 21 @NotEmpty(message="Informe a sigla do cargo") 22 @PropertyDescriptor(displayName = "Sigla") 23 private String sigla; 24 // implementação dos GETTERS & SETTERS 68 69 // implementação do equals e hashcode 100 } Após recompilar e executar a aplicação, podemos ver a mudança no nome da coluna do campo Titulo. Título com acento A aplicação utilizará o idioma definido na máquina onde está rodando o navegador (browser) do cliente. IV.9 - Distribuição da Aplicação A aplicação a ser distribuída foi criada na forma de um arquivo WAR (Web Archive) na pasta dist após a sua montagem. Este arquivo contém todos os recursos necessários à aplicação e pode ser implantado em qualquer servidor de aplicações Web para Java. IV.10 - Passos Para Montar uma Aplicação Os passos necessários para se criar uma aplicação baseada no Entities são: 1. 2. 3. 4. 5. 6. Descompactar o arquivo 'Entities-Blank-v.zip' onde 'v' é a versão do Entities-Blank. Renomear a aplicação Entities-Blank para o nome desejado Criar as entidades Referenciar as entidades em 'main.xhtml' Referenciar as entidades em 'hibernate.cfg.xml Montar e distribuir a aplicação WAR 0 - IV.7 - Mudando a Pele Skins O Entities permite a mudança de pele, no que tange a tonalidades de cores. Os ícones usados no Entities foram obtidos no sítio http://iconza.com Estes ícones, assim como a costumização do RichFaces foram utilizados para gerar as peles default, skyblue e wine. Desta forma, configurando o RichFaces para uma destas peles, os ícones do Entities automaticamente se adaptam ao padrão de cor. IV.8 - Internacionalização O Entities permite a internacionalização das telas geradas por meio de arquivos de recursos de nome I18N.propreties que deve ser criado para cada idioma a ser utilizado na pasta raiz de recursos (pacotes). O arquivo 'I18N.propreties' contém o idioma padrão, português. Para uma versão em inglês basta criar o arquivo 'I18N_en.propreties' na pasta raiz de recursos. Para cada entidade a ter seus rótulos internacionalizados o arquivo de idioma deve ter as seguintes propriedades: Entities.<entidade>.displayName=<txt> Entities.<entidade>.pluralDisplayName=<txt> Entities.<entidade>.shortDescription=<txt> Onde <entidade> é o nome da entidade e <txt> em cada linha é o texto no idioma desejado. Para cada propriedade de entidade a ter seus rótulos internacionalizados o arquivo de idioma deve ter as seguintes propriedades: Entities.<entidade>.<propriedade>.displayName=<txt> Entities.<entidade>.<propriedade>.pluralDisplayName=<txt> Entities.<entidade>.<propriedade>.shortDescription=<txt> Onde <entidade>.<propriedade> é o nome da entidade e da propriedade e <txt> em cada linha é o texto no idioma desejado. O Entities automaticamente carrega todos os arquivos I18N e aplica a internacionalização nas entidades e campos cobertos por estes arquivos. Segunda-feira, 3 de Maio de 2010-11

V.2.b - TABLE_CRUD V - Tela Formulário Padrão Nota: Fontes em 'exemplos/tela-formulario-padrao' Apresenta todos os campos da entidade na forma de uma tabela mas com comandos que permitem ações de incluir, alterar e excluir. Assim como no caso de TABLE são também criados comandos Até este ponto, as listas de entidades foram apresentadas sob a de auxílio à navegação. forma de linhas em uma tabela onde cada coluna representa um campo. Isto correu porque na referência à tela desejada no arquivo 'main.xhtml' se usou '@TABLE_CRUD' que é uma das formas V.2.c - FORM padrões de apresentação de uma entidade no Entities. Uma outra forma padrão de apresentação de entidade no Entities é a '@FORM_CRUD' que apresenta a entidade na forma de um formulário vertical. A aplicação CRUD da entidade Pessoa (exemplo Primeira Aplicação Quick Start) teria apenas o arquivo 'main.xhtml' modificado para: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 <?xml version='1.0' encoding='utf-8'?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 > <html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:e="http://entities.br"> <body> <ui:composition template="./template.xhtml"> <ui:define name="body"> <h:messages/> <e:view name="model.pessoa@form_crud"/> </ui:define> </ui:composition> </body> </html> Simplesmente apresenta todos os campos da entidade em um formulário não editável. Também é criado um conjunto de comandos para auxiliar na navegação. V.2.d - FORM_CRUD Apresenta todos os campos da entidade em um formulário mas com comandos que permitem ações de incluir, alterar e excluir. Assim como no caso de FORM são também criados comandos de auxílio à navegação. 0 - Note-se que a tag 'e:view' tem a propriedade 'name' alterada para o novo formato padrão. Um exemplo de tela neste formato é mostrado a seguir. V.1 - Só para Leitura No caso de se querer apresentar entidades só para leitura, basta utilizar a '@FORM' no lugar de '@FORM_CRUD'. O mesmo é válido para o caso tabular. Deve-se neste caso usar '@TABLE' no lugar de '@TABLE_CRUD'. Toda customização feita nos exemplos com '@TABLE_CRUD' também funcionam com '@TABLE', '@FORM' e '@FORM_CRUD'. V.2 - Visões Padrões Na definição do menu, quando se necessita especificar um nome de visão (View), pode-se informar uma visão definida pelo desenvolvedor na classe da entidade ou uma visão padrão. Uma visão padrão é referenciada pelo nome da entidade seguido de '@' (arroba) e seguido do nome da visão padrão. O Entities se encarrega de gerar as telas necessárias. Por exemplo: Na primeira aplicação apresentada neste manual o desenvolvedor especificou a visão padrão TABLE_CRUD da seguinte forma: model.pessoa@table_crud. Onde model.pessoa é o nome da entidade para qual serão geradas as telas TABLE_CRUD especifica que se deseja as telas de CRUD na forma de tabelas. V.2.a - TABLE Simplesmente apresenta todos os campos da entidade na forma de uma tabela não editável. Também é criado um conjunto de comandos para auxiliar na navegação. A navegação é feita linha a linha e em blocos (ou páginas) de tamanho fixo. Segunda-feira, 3 de Maio de 2010-12

VI - Relacionamentos Nota: Fontes em 'exemplos/relacionamentos' Neste exemplo é mostrada uma aplicação envolvendo três entidades, País, Estado e Cidade, que possuem relacionamentos entre si. Como resultados vai-se notar que os relacionamentos geram listas de escolhas nos campos quando se está na tela de edição. Entidade País: 12 13 14 15 16 17 18 19 20 21 22 23 24 26 27 91 @Entity @Table(name="cidade") public class Cidade implements Serializable { @Id @NotNull private Long id; @NotEmpty @Length(max = 40) private String nome; @ManyToOne private Estado estado; // GETTERS & SETTERS } Entidade Estado: 17 @Entity 18 @Table(name = "estado") 19 public class Estado implements Serializable { 20 21 /* Id baseado no código do IBGE */ 22 @Id 23 @NotEmpty 24 @Length(min = 2, max = 2) private String id; 26 27 @NotEmpty 28 @Length(max = 30) 29 private String nome; 30 31 @NotEmpty 32 @Length(max = 30) 33 private String capital; 34 35 @Column(unique = true) 36 private int codigoibge; 37 38 @OneToMany(cascade = CascadeType.ALL, mappedby = "estado") 39 private List<Cidade> cidades = new ArrayList<Cidade>(); 40 41 @ManyToOne 42 private Pais pais; 43 44 // GETTERS & SETTERS 129 } 38 39 40 41 42 43 44 45 46 47 48 49 @NotEmpty @Length(max=2) @Pattern(regex = "[A-Z]{2}") private String code2; @NotEmpty @Length(max=3) @Pattern(regex = "[A-Z]{3}") private String code3; @OneToMany(cascade = CascadeType.ALL, mappedby = "pais") private List<Estado> estados = new ArrayList<Estado>(); 50 51 // SETTERS & GETTERS 135 } Incluindo o acesso ao CRUD de cada entidade no menu, o arquivo main.xhtml fica assim. 14 <rich:panelmenu mode="ajax" width="160px"> 15 <rich:panelmenugroup label="locais" expanded="true"> 16 <rich:panelmenuitem> 17 <e:go label="países" 18 viewname="model.pais@table_crud" 19 20 21 <rich:panelmenuitem> 22 <e:go label="estados" 23 viewname="model.estado@table_crud" 24 26 <rich:panelmenuitem> 27 <e:go label="cidades" 28 viewname="model.cidade@table_crud" 30 31 </rich:panelmenugroup> 32 </rich:panelmenu> Por fim, deve-se incluir a referência à entidade Cargo no arquivo hibernate.cfg.xml para que esta entidade possa ser persistida. 3 <hibernate-configuration> 4 <session-factory>... 14 <mapping class=".cidade"/> 15 <mapping class="model.estado"/> 16 <mapping class="model.pais"/> 17 </session-factory> 18 </hibernate-configuration> Pronto! Uma vez criadas as entidades só com anotações JPA e incluídas no menu as chamadas de edição de cada uma delas, podese compilar e executar a aplicação. A tela inicial da aplicação fica assim: Após a inclusão de dois países, a tela fica assim: Entidade Cidade: 21 @Entity 22 @Table(name="pais") 23 public class Pais implements Serializable { 24 private static final long serialversionuid = 1L; 26 27 @Id 28 @Basic 29 @NotEmpty 30 @Length(max=3) 31 @Pattern(regex = "[0-9]{3}") 32 private String id; 33 34 @NotEmpty 35 @Length(max=50) 36 private String nome; 37 Ao se incluir um estado notamos a presença da lista de países devido ao relacionamento entre países e estados. Lista de paises obtida do relacionamento Segunda-feira, 3 de Maio de 2010-13

Ao se incluir uma cidade notamos a presença da lista de estados devido ao relacionamento entre cidades e estados. VII - Indo Além do CRUD Lista de estados obtida do relacionamento Nota: Fontes em 'exemplos/indo-alem-do-crud' Um ponto forte no Entities é a possibilidade de facilmente se configurar um formulário. 0 - A anotação '@View' foi criada para este fim. Esta anotação é responsável por definir visões a serem mostradas na tela. Uma visão permite que se monte um formulário com os dados resultantes de uma consulta feita no modelo e ainda definir o layout do formulário. Esta anotação deve ser aplicada sobre uma entidade do modelo. Pois ela se refere à uma consulta pré-definida pela anotação '@NamedQuery'. A definição dos layouts envolvidos em uma visão é feita utilizando a Linguagem de Layout do Entities LLE. Uma visão produzida pela anotação @View possui as seguintes propriedades que definem o seu layout: namedquery Nome da consulta a ser utilizada para obtenção dos dados a serem mostrados. name Nome da visão ser referenciado no menu. title Título a ser mostrado no topo do painel da visão. filters (opcional) Layout do filtro a ser usado nas buscas filtradas. Define cada propriedade de entidade utilizada como filtro. (usando LLE) header (opcional) Título a ser mostrado no topo da tabela de dados. members Layout de apresentação dos dados. Cada linha da tabela de apresentação de dados obedecerá este layout. (usando a LLE) footer (opcional) Layout do rodapé a ser mostrado no final da tabela. (usando a LLE) Uma visão gera uma tela com a seguinte disposição: [ TITLE ] [ FILTERS ] [ HEADER ] [ MEMBERS ] [ FOOTER ] Como exemplo serão mostradas cinco visões de uma mesma consulta (query) no caso da entidade Pessoa. A seguir é mostrada a entidade Pessoa com as anotações de consultas e de visões e em seguida é descrita cada uma das visões nela definidas. A entidade Pessoa fica assim: 17 18 19 20 21 22 23 24 26 27 28 29 @Entity @NamedQueries({ @NamedQuery( name="consultapessoa", query="select p from model.pessoa p" ) }) @Views({ @View( name="visaopessoa_1", namedquery="consultapessoa", title="exemplo 1 de Visão do Entities", members="id,nome,sexo,altura," + Segunda-feira, 3 de Maio de 2010-14

30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 "datadenascimento,deficientefisico", footer = "Ctrl.List.scroll()" ), @View( name="visaopessoa_2", namedquery="consultapessoa", title="exemplo 2 de Visão do Entities", members="[[id,nome]:4;" + "sexo,altura,datadenascimento," + "deficientefisico]", footer = "Ctrl.List.scroll()" ), @View( name="visaopessoa_3", namedquery="consultapessoa", title="exemplo 3 de Visão do Entities", members="quem[id,nome]," + "Dados 1[sexo;altura]," + "Dados 2[dataDeNascimento;" + " deficientefisico]", footer = "Ctrl.List.scroll()" ), @View( name="visaopessoa_4", namedquery="consultapessoa", title="exemplo 4 de Visão do Entities", members="[ [ id,nome ];" + " [ Dados 1 [ sexo;altura ]," + " Dados 2 [ datadenascimento;" + " deficientefisico ]" + " ]" + "]", footer = "Ctrl.List.scroll()" ) 55 56 57 58 59 }) 60 public class Pessoa implements Serializable { 61 62 public enum Sexo { MASCULINO, FEMININO } 66 @Id 67 @GeneratedValue 68 private long id; 69 private Sexo sexo; 70 @Column(length=40) 71 @Pattern(regex = "^[A-Z,0-9\\s]{0,40}$") 72 @NotEmpty(message = "Informe o nome da pessoa") 73 private String nome; 74 @Temporal(javax.persistence.TemporalType.DATE) 75 private Date datadenascimento; 76 @Column(scale = 1, precision = 2) 77 private float altura; 78 private boolean deficientefisico; 79 80 // implementação dos GETTERS & SETTERS 129 130 // implementação do equals e hashcode 153 } Nesta classe nota-se as visões (@View) embutidas em @Views. Nota: O Entities espera que as anotações @View estejam sempre dentro de uma anotação @Views mesmo que só exista uma anotação @View. 24 @Views({ @View( 32 @View( 39 @View( 48 @View( 59 })............ 23 viewname="model.pessoa@visaopessoa_1" 24 26 <rich:panelmenuitem> 27 <e:go label="exemplo View 2" 28 viewname="model.pessoa@visaopessoa_2" 29 30 31 <rich:panelmenuitem> 32 <e:go label="exemplo View 3" 33 viewname="model.pessoa@visaopessoa_3" 34 35 36 <rich:panelmenuitem> 37 <e:go label="exemplo View 4" 38 viewname="model.pessoa@visaopessoa_4" 39 40 41 </rich:panelmenugroup> 42 </rich:panelmenu> 43 <e:view /> 44 </h:panelgrid> 45 </h:form> Nota: O Entities espera que a anotação @NamedQuery esteja dentro de uma anotação @NamedQueries mesmo que exista apenas uma @NamedQuery. 18 @NamedQueries({ 19 @NamedQuery( 20 name="consultapessoa", 21 query="select p from model.pessoa p" 22 ) 23 }) VII.1 - Primeira Visão Menu: 16 <rich:panelmenuitem> 17 <e:go label="crud" 18 viewname="model.pessoa@table_crud" 19 20 Tela: ), ), ), ) O menu criado referencia 5 visões, sendo a primeira o CRUD padrão já visto e as demais visões são definidas por uma das anotações @View na entidade Pessoa. O meu fica assim: 11 <h:form> 12 <h:panelgrid columns="2"> 13 <rich:panelmenu mode="ajax" width="160px"> 14 <rich:panelmenugroup label="visões" 15 expanded="true"> 16 <rich:panelmenuitem> 17 <e:go label="crud" 18 viewname="model.pessoa@table_crud" 19 20 21 <rich:panelmenuitem 22 <e:go label="exemplo View 1" VII.2 - Segunda Visão Menu: 21 22 23 24 <rich:panelmenuitem> <e:go label="exemplo View 1" viewname="model.pessoa@visaopessoa_1" Segunda-feira, 3 de Maio de 2010-15

Neste item de menu, a visão VisaoPessoa_1 da classe model.pessoa é referenciada. Visão: 26 27 28 29 30 31 externo envolvendo todos os itens, só existirá uma coluna na tela gerada. Dentro do grupo mais externo tem-se: [id,nome]:4;sexo,altura,datadenascimento,definientefisico @View( name="visaopessoa_1", namedquery="consultapessoa", title="exemplo 1 de Visão do Entities", members="id,nome,sexo,altura," + "datadenascimento,deficientefisico", footer = "Ctrl.List.scroll()" ), Neste exemplo, definição: a propriedade members tem a Como já foi visto o ponto-e-vírgula realiza uma quebra de linha, obtém-se assim duas linhas: [id,nome]:4 sexo,altura,datadenascimento,deficientefisico A primeira linha é formada por um grupo contendo os campos id e nome. Este grupo forma uma coluna. seguinte A segunda linha contém os demais 4 itens, formando então quatro colunas. Para evitar este desencontro de uma coluna sobre quatro id,nome,sexo,altura,datadenascimento,deficientefisico colunas, a primeira linha termina com ':4' que indica que a coluna Cada campo é separado do outro por uma vírgula o que indica que deve ocupar o lugar de quadro colunas, igualando a primeira linha com a segunda em números de colunas. devem ficar em uma mesma linha. Cada campo será apresentado como uma coluna na tabela de saída. Tela: Nesta visão, os campos foram simplesmente referenciados em uma lista que indica a ordem que devem ser apresentados em cada linha. O título de cada coluna é o nome do campo ou o nome especificado pela anotação @PropertyDescriptor aplicada ao campo. Tela: VII.4 - Quarta Visão Menu: 31 32 33 34 35 VII.3 - Terceira Visão Menu: <rich:panelmenuitem> <e:go label="exemplo View 3" viewname="model.pessoa@visaopessoa_3" Neste item de menu, a visão VisaoPessoa_3 da classe 26 27 28 29 30 <rich:panelmenuitem> model.pessoa é referenciada. <e:go label="exemplo View 2" viewname="model.pessoa@visaopessoa_2" Visão: 39 @View( 40 name="visaopessoa_3", Neste item de menu, a visão VisaoPessoa_2 da classe 41 namedquery="consultapessoa", model.pessoa é referenciada. 42 title="exemplo 3 de Visão do Entities", 43 members="quem[id,nome]," + Visão: 44 "Dados 1[sexo;altura]," + 45 "Dados 2[dataDeNascimento;" + 32 @View( " deficientefisico]", 33 name="visaopessoa_2", 46 footer = "Ctrl.List.scroll()" 34 namedquery="consultapessoa", 47 ), 35 title="exemplo 2 de Visão do Entities", 36 members="[[id,nome]:4;" + Neste exemplo, a propriedade members tem a seguinte "sexo,altura,datadenascimento," + definição: "deficientefisico]", Quem[id,nome],Dados 1[sexo;altura], 37 footer = "Ctrl.List.scroll()" Dados 2[dataDeNascimento;deficienteFisico] 38 ), Neste exemplo, definição: a propriedade members tem a seguinte [[id,nome]:4;sexo,altura,datadenascimento,definientefisico] As vírgulas separam a linha em três colunas: Quem[id,nome] Dados 1[sexo;altura] Dados 2[dataDeNascimento;deficienteFisico] Na LLE um ponto-e-vírgula ';' indica uma quebra de linha, assim A primeira coluna é um grupo com os campos id e nome. Na LLE sendo, duas linhas serão criadas para cada entidade. A primeira linha conterá os campos id e nome e a segunda linha conterá os campos quando um grupo é precedido de um texto este texto, chamado de rótulo do grupo, torna-se o nome da coluna. Neste caso, a primeira sexo, altura, datadenascimento e deficientefísico. coluna tem o nome 'Quem'. Na LLE colchetes ('[' e ']') delimitam um grupo. Desta forma temos A segunda coluna é um grupo de rótulo 'Dados 1' que se tornará o um grupo que engloba toda a visão e um outro grupo interno que nome da coluna. O conteúdo desta coluna são os campos sexo e engloba os campos id e nome. altura separados por ponto-e-vírgula que provocará a quebra de Na LLE cada grupo forma uma coluna. Como só existe um grupo linha entre eles. Segunda-feira, 3 de Maio de 2010-16

A terceira coluna é um grupo de rótulo 'Dados 2' que se tornará o nome da coluna. O conteúdo desta coluna são os campos datadenascimento e deficientefisico separados por ponto-evírgula que provocará a quebra de linha entre eles. Tela: VII.5 - Quinta Visão Menu: 36 37 38 39 40 <rich:panelmenuitem> <e:go label="exemplo View 4" viewname="model.pessoa@visaopessoa_4" Neste item de menu, a visão VisaoPessoa_4 da classe model.pessoa é referenciada. Visão: 48 49 50 51 52 53 54 55 56 57 58 @View( name="visaopessoa_4", namedquery="consultapessoa", title="exemplo 4 de Visão do Entities", members="[ [ id,nome ];" + " [ Dados 1 [ sexo;altura ]," + " Dados 2 [ datadenascimento;" + " deficientefisico ]" + " ]" + "]", footer = "Ctrl.List.scroll()" ) Neste exemplo, definição: a propriedade members tem a Nota: A seção 'LLE - Linguagem de Layout do Entities' tem mais detalhes sobre a definição de layouts de visões. 0 - seguinte [[id,nome];[dados1[sexo;altura],dados 2 [datadenascimento;deficientefisico]]] Existem um grupo mais externo que apresentará tudo em uma única coluna. Resta então: [id,nome];[dados1[sexo;altura],dados 2 [datadenascimento;deficientefisico]] O ponto-e-vírgula após o primeiro grupo separa a saída em duas linhas. A primeira linha contém o grupo: [id,nome] e a segunda linha linha contém o grupo: [Dados1[sexo;altura],Dados 2 [datadenascimento;deficientefisico]] Assim sendo a primeira linha terá os campos id e nome em linha, e a segunda linha terá os grupos: Dados1[sexo;altura] Dados 2 [datadenascimento;deficientefisico]] Como estes dois grupos estão dentro de um outro grupo que já forma uma coluna de saída, a presença dos rótulos gerará painéis formando duas novas colunas com seus respectivos rótulos internamente à coluna mais externa. Tela: Segunda-feira, 3 de Maio de 2010-17

Comando para Filtrar VIII - Adicionando Filtros Nota: Fontes em 'exemplos/filtrando' O Entities permite que sejam incluídos filtros em uma visão. Para isto é necessário apenas incluir a propriedade filters em @View. O código fonte de model.pessoa modificado para conter uma visão com filtro é o seguinte: 17 18 19 20 21 22 23 24 26 27 28 29 30 @Entity @NamedQueries({ @NamedQuery( name="consultapessoa", query="select p from model.pessoa p" ) }) @Views({ @View( name="visaopessoa", namedquery="consultapessoa", title="exemplo com Filtros", filters="filtro[nome,ctrl.dao.filter()]", members="id,nome,sexo,datadenascimento, + altura,deficientefisico", footer="ctrl.list.scroll()" ) }) public class Pessoa implements Serializable { 31 32 33 34 35 36 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 103 104 127 } public enum Sexo { MASCULINO, FEMININO } @Id @GeneratedValue private long id; private Sexo sexo; @Column(length=40) @Pattern(regex = "^[A-Z,0-9\\s]{0,40}$") @NotEmpty(message = "Informe o nome da pessoa") private String nome; @Temporal(javax.persistence.TemporalType.DATE) private Date datadenascimento; @Column(scale = 1, precision = 2) private float altura; private boolean deficientefisico; A mesma tela, agora com um valor de filtro aplicado ao se pressionar o comando de filtro. VIII.1 - Coringas O Entities permite o uso de construções de caracteres coringas para filtrar campos. No filtro de qualquer campo, é possível especificar valores assim como faixas de valores aceitas. Um valor também pode ser uma data no formato DD/MM/AAAA (DD - dia; MM - mês; AAAA - ano). Os valores ou faixa de valores possíveis são separados por ';' (ponto e vírgula). Por exemplo: // implementação dos GETTERS & SETTERS // implementação do equals e hashcode 1;2;5,6;9,8 Especifica os valores 1 (um), 2 (dois), 5,6 (cinco vírgula seis) e 9,8 (nove vírgula oito). A definição do filtro é feita usando a LLE. 1 a 5;7 a 19;21 a 35 Neste exemplo está-se criando um grupo com rótulo 'Filtro' Especifica as seguintes faixas de valores: 1 a 5 (de um a cinco), 7 a contendo o campo nome e o comando 'Ctrl.DAO.filter()' que é 19 (de sete a dezenove) e 21 a 35 (de vinte um a trinta e cinco). representado na tela como a imagem de um funil. 1 a 5;3,4;6;45 a 50 26 27 28 29 30 31 32 @View( name="visaopessoa", namedquery="consultapessoa", title="exemplo com Filtros", filters="filtro[nome,ctrl.dao.filter()]", members="id,nome,sexo,datadenascimento, + altura,deficientefisico", footer="ctrl.list.scroll()" ) Especifica: faixa de valores de 1 a 5 (de um a cinco), valor isolado 3,4 (três vírgula quatro), valor isolado 6 (seis) e faixa de valores de 45 a 60 (quarenta e cinco a sessenta). 21/08/2009;31/01/2010 a 20/04/2010 Especifica: a data 21/08/2009 (vinte e um de agosto de dois mil e nove) e a faixa de datas de 31/01/2010 a 20/04/2010 (trinta e um A seguir vê-se a tela com o filtro montado sobre a visão de de janeiro de dois mil e dez a vinte de abril de dois mil e dez). apresentação da entidade Pessoa. O caractere '*' (asterisco) indica zero ou mais caracteres. Por exemplo: *XYZ especifica qualquer texto terminado com XYZ. A* especifica qualquer texto começado com A. Para*fim especifica qualquer texto começado com Para e terminado com fim. Segunda-feira, 3 de Maio de 2010-18

*oba* especifica qualquer texto que contenha oba. O caractere '_' (sublinha) Indica um caractere qualquer. Por exemplo: L_pis IX - Ação Nota: Fontes em 'exemplos/primeira-acao' Neste exemplo é mostrado o uso de uma ação. Uma ação é um comando disparado pelo operador do sistema. Em indica uma palavra iniciada com L, seguido de um caractere geral trata-se de um botão. qualquer e terminada com pis. O Entities obedece os preceitos de Naked Objects onde os X métodos de uma entidade são ações que retornam valores para o indica uma palavra iniciada com X, seguido de três caracteres operador do sistema. Se um método retorna um valor do tipo texto (String), o texto retornado será mostrado ao operador como se fosse quaisquer. uma mensagem do sistema para o operador. Limitadores indicam valores limites superiores, inferiores ou de Neste exemplo, adicionaremos à entidade Pessoa do exemplo igualdade. QuickStart um campo de nome peso (float) e um método que calcula o Por exemplo: índice de massa corpórea da pessoa e emite uma mensagem ao operador sobre a situação da pessoa quanto ao seu peso. >20 especifica valores acima de vinte. <=31 especifica valores menores ou iguais a trinta e um. 0 - A nova entidade Pessoa fica assim: 22 @Entity 23 @EntityDescriptor(displayName="Pessoa", pluraldisplayname="pessoas") 24 public class Pessoa implements Serializable { 26 public enum Sexo { MASCULINO, FEMININO } 27 28 @Id 29 @GeneratedValue 30 @PropertyDescriptor(index = 1) 31 private long id; 32 33 @PropertyDescriptor(index = 2) 34 private Sexo sexo; 35 36 @Column(length = 40) 37 @PropertyDescriptor(index = 3) 38 @Pattern(regex = "^[A-Z,0-9\\s]{0,40}$") 39 @NotEmpty(message = "Informe o nome da pessoa") 40 private String nome; 41 42 @PropertyDescriptor(index = 4) 43 @Temporal(javax.persistence.TemporalType.DATE) 44 private Date datadenascimento; 45 46 @PropertyDescriptor(index = 5) 47 @Column(scale = 1, precision = 2) 48 private float altura; 49 50 @PropertyDescriptor(index = 6) 51 @Column(scale = 3, precision = 2) 52 private float peso; 53 54 @PropertyDescriptor(index = 7, displayname = "Def. Físico") 55 private boolean deficientefisico; 56 57 @ActionDescriptor(displayName="",value="IMC") 58 public String calculaimc() { 59 float imc = peso / (altura * altura); 60 if (imc < 18.5) return String.format( "%s está abaixo do peso ideal (IMC=%4.1f)", nome, imc); 61 if (18.5 <= imc && imc < ) return String.format( "%s está no peso normal (IMC=%4.1f)", nome, imc); 62 if ( <= imc && imc < 30) return String.format( "%s está acima do peso (IMC=%4.1f)", nome, imc); 63 if (30 <= imc && imc < 35) return String.format( "%s está com obesidade grau I (IMC=%4.1f)", nome, imc); 64 if (35 <= imc && imc < 40) return String.format( "%s está com obesidade grau II (IMC=%4.1f)", nome, imc); 65 return String.format( "%s está com obesidade grau III", Segunda-feira, 3 de Maio de 2010-19

nome, imc); 66 67 68 1 126 149 } este método se tornará uma ação e quando esta ação for disparada pelo operador, a aplicação automaticamente abrirá um diálogo pedindo ao operador o valor de cada argumento. } // implementação dos GETTERS & SETTERS // implementação do equals e hashcode Como exemplo, o método: A tela da aplicação, após incluir um registro fica assim: public String calculaarea( @ParameterDescriptor(displayName="largura") double x, @ParameterDescriptor(displayName="altura") double y) { return Área = + x * y; } Botão da ação Os argumentos largura e altura serão pedidos ao operador por meio de um quadro de diálogo. Nota-se que um botão de rótulo IMC foi inserido na linha de registro da pessoa. Este botão foi uma conseqüência da inclusão do método: 57 58 @ActionDescriptor(displayName="",value="IMC") public String calculaimc() { } Ao se clicar neste botão a aplicação retorna com a seguinte tela: Mensagem ao operador O título que aparace no quadro de diálogo é obtido do método tostring() da entidade. Dependendo do tipo do argumento o Entities pode tomar as seguintes ações: Tipo do Valor Retornado Ao se pressionar o botão IMC o método calcularimc() foi chamado e o texto retornado por ele foi mostrado ao operador. IX.1 - Ações no Entities Tipo do Valor Retornado Retorna como uma mensagem para o operador. Retorna o valor como mensagem para o operador. uma (e envelopes) OutpustStream Pede ao operador que digite via um quadro de diálogo. byte, short, int, float, double Pede ao operador que digite via um quadro de diálogo. (e envelopes) Sobe algum arquivo que será lido pelo método (upload). IX.3 - Métodos Escondidos Para um método de uma entidade não ser apresentado como uma ação, basta usar a propriedade hide da anotação @ActionDescriptor: Ação Tomada byte, short, int, float, double String InpustStream O Entities tem algumas ações padrões de acordo com o tipo do valor retornado pelo método da ação. String Ação Tomada Baixa a imagem gerada (download). @ActionDescriptor(hide=true) public String calculoescondido() { } IX.4 - Transação Se uma ação vai atualizar valores na entidade e estes valores devem ser persistidos, deve-se usa a anotação @Transaction do Entities. Esta anotação insere o uso de uma transação na execução do método e assim toda alteração feita no modelo é persistida. 0 - WorkBook (Apache-POI) [ WorkBook, String ] (Vetor contendo planilha e um texto) uma Baixa a planilha (download). Baixa a planilha como um arquivo cujo nome é o texto (download). Para os resultados não apresentados na tabela, o Entities não toma nenhuma atitude. IX.2 - Ação com Argumentos No Entities ações podem receber argumentos. Neste caso, ainda obedecendo ao DDD, os argumentos têm que ser obtidos do operador do sistema. Ao inserir um método com argumentos em uma entidade, Segunda-feira, 3 de Maio de 2010-20

X - Distribuição No caso de se desejar utilizar outro gerenciador de base de dados, deve-se estar de posse do driver JDBC do gerenciador e da URL da base de dados a ser utilizada. É claro que a base de dados precisa ser criada também. A aplicação a ser distribuída é criada na forma de um arquivo WAR O driver da base de dados deve ser copiado para um lugar (Web Archive) na pasta dist após a sua montagem. Este arquivo contém todos os recursos necessários à aplicação e pode ser conhecido pela aplicação. É sugerida a pasta lib que já vem criada na aplicação vazia. No Netbeans deve-se, então, clicar com o botão implantado em qualquer servidor de aplicações Web para Java. direito do ratinho sobre o item Bibliotecas, da aba Projetos, e escolher a opção de informar um arquivo JAR. Navega-se até a pasta lib e escolhe-se o arquivo do driver desejado. Desta forma o JDBC será Nota: Convém lembrar que antes de implantar a aplicação as incluído no arquivo WAR da aplicação gerada. configurações de bases de dados devem ser alteradas para as bases de dados a serem usadas em produção e a aplicação deve ser recompilada. XI.1 - Múltiplas Bases de Dados O Entities permite o uso de múltiplas bases de dados, neste caso basta criar um arquivo de configuração do Hibernate para cada base de dados no pacote raiz. O Entities carrega automaticamente todos os O Entities utiliza as configurações de bases de dados do Hibernate. arquivos que terminarem com: O arquivo 'hibernate.cfg.xml' está localizado no pacote padrão.hibernate.cfg.xml da aplicação (ou pacote raiz). que estejam no pacote padrão (pasta raiz de pacotes da aplicação). XI - Configuração de SGBD 0 - O Entities-Blank vem pré-configurado para uma base de dados embutida na aplicação utilizando o Java DB. Desta forma o arquivo 'hibernate.cfg.xml' inicialmente contém: 3<hibernate-configuration> 4 <session-factory> 5 <property name="hibernate.dialect"> org.hibernate.dialect.derbydialect </property> 6 <property name="hibernate.connection.driver_class"> org.apache.derby.jdbc.embeddeddriver </property> 7 <property name="hibernate.connection.url"> jdbc:derby:entitiesdb;create=true </property> 8 <property name="hibernate.current_session_context_class"> thread</property> 9 <property name="hibernate.hbm2ddl.auto"> update </property> 10 </session-factory> 11 </hibernate-configuration> Neste arquivo as seguintes propriedades devem ser definidas de acordo com a base de dados a se utilizar: hibernate.dialect nome do dialeto de base de dados a ser usado pelo Hibernate (em geral é org.hibernate.dialect. acrescentado do nome do gerenciador de base de dados) hibernate.connection.driver_class nome da classe driver do gerenciador de base de dados a ser usado (fornecido pelo fabricante do gerenciador). hibernate.connection.url URL que referencia a base de dados a ser usada (depende do gerenciador de base de dados). hibernate.connection.username nome de usuário a ser usado para acessar a base de dados. hibernate.connection.password senha do usuário usado para acessar a base de dados. Nota: Somente estas propriedades devem ser adaptadas à situação corrente, as demais propriedades devem ficar inalteradas. Segunda-feira, 3 de Maio de 2010-21

XII - Casos de Sucesso Nesta seção são citados alguns sistemas implantados utilizando a plataforma Entities. XII.1 - DER No DER, Departamento de Edificações e Rodovias do Estado do Ceará, todos os sistemas estão sendo desenvolvidos na plataforma do Entities deste janeiro de 2009. Contato: Antônio Gomes Ferreira antogofe@yahoo.com.br XII.1.a - Controle de Ponto XII.1.c - Pró-Estradas XII.1.b - Avaliação de Temporários Segunda-feira, 3 de Maio de 2010-22

XII.1.d - Sistema Corporativo SIGDER Segunda-feira, 3 de Maio de 2010-23