Padrão "Arquivo Anexado"

Transcrição

1 6Implementando a Inclusão Padrão "Arquivo Anexado" Capítulo 9 - Prosseguindo na Implementação de UC002 Manter Funcionário! - Introdução No capítulo anterior, implementamos a manutenção de toda a Agregação de Funcionário, representada na Figura B9.1, com exceção das classes Foto e "Curriculo". Iremos tratá-las separadamente porque possuem características especiais que o justificam. Figura B9.1. Modelo de domínio com destaque para classes com estereótipo plcarquivoanexado. São muitas as possibilidades de se gerar problemas em programações que manipulam de arquivos anexados via Web, sejam eles para exibição de imagens (ex.: fotos ou diagramas em formatos png, jpg, gif ou outros) ou documentos (ex.: leis, currículo ou prova, em formatos PDF, DOC, XLS ou outros). Problemas de performance nesta área são recorrentes e eventualmente ocorrerão se a organização não estabelece e promove um padrão para a gravação e manipulação deste tipo de artefato. Neste capítulo, iremos conhecer e implementar a Inclusão Padrão de Arquivo Anexado, sugerida e automatizada pelo jcompany. São algumas características deste padrão, que evitam erros frequentes quando implementados artesanalmente: 1. (Otimização) Evita que mapeamentos manytoone para classes que contenham binários causem downloads invisíveis ao desenvolvedor, no servidor (por exemplo, quando recuperando nome para exibição de um anexo). 2. (Otimização) Provê um ajuste dinâmico de declaração do formulário HTML, para que funcione como multipart apenas no momento do uploads e como text/plain nos demais momentos. O uso inapropriado de multipart degrada considerável a performance de transmissão e recepção dos dados de formulários.

2 Capítulo B9 3. (Otimização) Evita manter o arquivo em áreas de memória do servidor por mais tempo que o mínimo necessário, evitando perdas significativas de memória (leaks), frequentes quando desenvolvedores gerenciam este armazenamento temporário por sua conta. 4. (Usabilidade) Provê componente visual padrão para upload/download, que permite também a exclusão do arquivo de forma independente do restante do documento (quando este é opcional) ou substituição direta do mesmo, além de outros recursos sempre padronizados. 5. (Integridade) Facilita a garantia da integridade quando o arquivo é obrigatório. Provê gravação do arquivo na mesma transação JPA dos dados da Agregação. Qualquer exceção na gravação dos dados da classe Raiz/Mestre ou Detalhe irá implicar em rollback de todas as informações*. 6. (Produtividade/Qualidade) Provê suporte a validações declarativas de obrigatoriedade, tamanho, tipos (mime types) e variações de implementações (arquivos simples ou múltiplos, imagens ou documentos), com generalização completa MVC. - Gerando Mapeamento para Arquivos Anexados - Objeto-Relacional IV Segundo o padrão que utilizaremos, as classes Foto e "Curriculo" seguirão uma sugestão de mapeamento bem peculiar: o o o Elas devem herdar propriedades básicas de PlcBaseMapFile. É a primeira herança que faremos de classes pré-mapeadas disponíveis no jcompany. Se precisarem de mais propriedades além das básicas, elas devem utilizar os mapeamentos nos métodos getters e não nas propriedades, como fizemos até aqui. Desta forma, é possível sobrepor os mapeamentos herdados. Note que se os mapeamentos da classe ancestral fossem feitos em propriedades, não seria possível sobrepô-los. Elas não necessitam de parte abstrata, por serem triviais e não expressarem um conceito de domínio relevante com o Funcionário, por exemplo. Os plugins de geração de mapeamento Objeto-Relacional não irão gerar os mapeamentos para Foto e Curriculo, até porque são totalmente herdados. Mas por serem bem simples poderão ser realizados rapidamente de forma manual. 1. Inclua os mapeamentos e método OneToOne em "Foto"e "Curriculo" utilizando como base o exemplo da Figura B9.2. Figura B9.2. Mapeamentos para classes para arquivos anexados. * Obs.: Muito embora seja interessante, este recurso pode tornar as Unidades Lógicas de Transação do SGBD mais longas devido ao tempo de se gravar conteúdos de maior tamanho. Isso pode ser crítico se há alto índice de concorrência na manipulação dos dados da Agregação, mas costuma ser aceitável na maior parte dos casos. Pode-se customizar este padrão para gravar em transação distinta, conforme o caso, especializando-se as classes do jcompany via DP Template Method ou DP Observer (CDI)

3 Implementando a Inclusão Padrão Arquivo Anexado #1. Deve-se declarar o estereótipo CDI "@SPlcEntity" que é utilizado internamente no jcompany. #2. As declarações de Entidade principais do JPA devem ser incluídas. #3. A deve ter o nome "SE_ARQUIVO_PLC" para ser compatível com o nome utilizado no "generator" do "getid()". Já o nome da Sequence pode ser definido de modo independente. Informe os nomes exatos da figura. #4. Todas as propriedades relevantes serão herdadas, tais como mimetype, size, etc.! Pode-se, obviamente, complementar as propriedades herdadas com outras específicas, se necessário. #5. Os métodos de referenciamento ao conteúdo dos arquivos em si foram concebidos para possibilitar o download com maior controle. 2. Em seguida copie a classe "Foto" e "Curriculo" e as renomeie, respectivamente, para "FotoConteudo" e "CurriculoConteudo". Esta nova classe deverá herdar da classe "PlcBaseMapFileContent" e não ter nenhum método. Ela armazenará o conteúdo do arquivo em si (BLOB), de modo segmentado da classe principal do arquivo, deste modo evitando o "download invisível" em diversas situações onde se poderia ter graves impactos de perfomance. A Figura abaixo mostra as classes resultantes: Figura B9.3. Classe FotoConteudo e CurriculoConteudo, que armazenam o conteúdo dos arquivos. Assim como as classes "Foto" e "Curriculo", as classes "FotoConteudo" e "CurriculoConteudo" precisam do estereótipo CDI "@SPlcEntity", das declarações JPA e da que agora deve ser preenchida com o nome SE_ARQUIVO_CONTEUDO_PLC e nomes de Sequence, respectivamente: "SE_FOTO_CONTEUDO_PLC" e "SE_CURRICULO_CONTEUDO_PLC". Vamos entender um pouco mais sobre a herança de classes pré-mapeadas para arquivos anexados, antes de prosseguirmos. 1. Acione Control+Clique sobre o nome PlcBaseMapFile na classe "Foto". Desta forma, será aberto o código fonte desta classe para conferirmos o que estamos herdando:

4 Capítulo B9 Figura B9.4. Classe ancestral com mapeamentos padrões para arquivos anexados. #1. As propriedades em si são ainda definidas em um outro ancestral, que não contém mapeamentos e é mantido assim para compatibilidades com versões anteriores ao JPA. #2. As propriedades versao, dataultalteracao e usuarioultalteracao estão mapeadas, mas foram minimizadas na figura porque já as explicamos anteriormente. #3. Perceba que esta classe possui mapeamentos em getters para facilitar alteração em descendentes. #4. Na propriedade nome, o jcompany irá registrar o nome do arquivo, como existia no momento do upload. #5. Na propriedade tipo, o jcompany irá registrar o MimeType do arquivo, obtendo-o através de seu sufixo. É importante armazenar este tipo separadamente para facilitar manipulações (como explicitação de tipo em cabeçalhos HTTP para download). #6. Na propriedade tamanho, o jcompany irá registrar o tamanho em bytes do arquivo. Restrições de tamanho máximo para upload estão disponíveis para este padrão através de declarações de metadados. 2. Acione Control+Clique sobre o nome PlcBaseMapFileArquivo na classe "FotoConteudo ". Desta forma, será aberto o código fonte desta classe para conferirmos o que estamos herdando:

5 Implementando a Inclusão Padrão Arquivo Anexado Figura B9.5. Classe ancestral com mapeamentos padrões para arquivos anexados. #1. As propriedades em si são ainda definidas em um outro ancestral. #2. A propriedade id identifica o "Funcionário" que contém o arquivo anexado. #3. Na propriedade binarycontent o jcompany irá registrar todo o conteúdo do arquivo em si, como um "Blob" (Binary Large Object), formato relacional mapeado como "@Lob" no padrão JPA. 3. Após finalizar o entendimento, faça alguns pequenos ajustes na classe "Funcionario" para que referencie corretamente os arquivos, conforme a Figura B9.6. Figura B9.6. Mapeamento padrão para referência a arquivos anexados de Foto e Curriculo. #1. Desfaça o comentário feito no capítulo anterior e inclua mapeamentos JPA conforme a figura. As coleções seguem o mapeamento OneToMany padrão, tal como nos detalhes. #2. A cláusula OrderBy pelo id faz com que recuperemos os arquivos na ordem em que foram gravados. #3. A especificação obriga que se tenha um mínimo de 2 e um máximo de 4 arquivos em currículo (os demais são anexos como diploma, certificado e outros). Podemos neste caso usar a mesma validação de multiplicidade que já conhecemos, usando "nome" como propriedade de referencia. Obs.: não se esqueça de criar a mensagem no arquivo ApplicationResources_pt_BR.properties. #4. A anotação PlcFileAttach permite a declaração de metadados típicos de arquivos anexados. Para "List<Curriculo>" usaremos opções mais condizentes com documentos baixados por demanda, definindo formatos PDF e DOC e tamanho de até 2 MB. #5. Não se esqueça de sempre qualificar a classe contida na coleção, o que é importante para maior legibilidade e segurança das implementações. #6. Somente possuímos uma foto, então a associação neste caso usa o padrão ManyToOne. #7. A especificação não obriga o usuário a cadastrar a foto (multiplicidade "0..1"), portanto devemos usar "nullable=true".

6 Capítulo B9 #8. Se desejássemos validar a obrigatoriedade neste caso, deveríamos usar "@NotNull", uma vez que o "PlcValMultiplicity" somente trabalha com coleções. O comentário exemplifica como isso poderia ser feito. #9. A anotação PlcFileAttach para "Foto" indica que queremos sempre baixar e exibir o conteúdo como imagem para os usuários, por isso a opção "image=true". Além disso também selecionaremos apenas arquivos com extensão "png, jpg ou gif" e ainda limitaremos o tamanho a 100Kbytes. IMPORTANTE: Lembre-se de criar os métodos getter e setter, não representados. 4. Sempre que finalizar um mapeamento feito à mão, lembre-se de editar o arquivo "persistence.xml" (JPA) para acrescentar a declaração correspondente, como na Figura B9.7. Figura B9.7. Declaração de Entidade no arquivo "persistence.xml". - Inserindo componente visual para arquivo anexado em XHTML Edição de Camada Visão IV O jcompany disponibiliza uma tag que pode ser usada em arquivos XHTML para renderizar a parte visual da anexação de arquivo, chamada plct:fileattach". Este componente identifica se estamos tratando de um único arquivo ou de uma coleção pelo tipo da propriedade, e modifica a forma de renderização apropriadamente. Vamos aplicar a tag para nossos dois casos: 1. Selecione o arquivo "funcionariomdt.xhtml", onde desejamos incluir o componente. 2. Declare o uso da biblioteca de tags com prefixo "plct", conforme ilustrado na Figura B9.8. Figura B9.8. Declaração de importação de bibliotecas de componentes Facelets. 3. Após importar a biblioteca, inclua o trecho acrescentando duas novas linha abaixo do formulário, conforme a Figura B9.9.

7 Implementando a Inclusão Padrão Arquivo Anexado Figura B9.9. Inserção de tags de arquivo ao final do formulário. 4. Defina rótulos para os componentes no arquivo ApplicationResources_pt_BR.properties. Recortando os textos que aparecem nas mensagens de erro ao tentar executar o formulário a primeira vez. Ex.: "label.arquivo.anexado.curriculo=currículo" Figura B9.10. Mensagem de erro da tag Facelets que renderiza os arquivos. o Upload de Imagem. Quando um arquivo vai ser enviado ao servidor, o jcompany altera o formulário para enctype="multipart/form-data", para permitir upload do arquivo. Para vários arquivos, o mecanismo funciona como na figura abaixo: Figura B9.11. Campo que permite upload (com form HTML em multipart). Importante: Deve-se entender que o rótulo apresentado no botão "Enviar Arquivo..." acima é de responsabilidade do Navegador (Browser). Se o mesmo estiver em inglês, por exemplo, o rótulo poderá aparecer como "Browse...", e conforme o Navegador também irá variar. o Upload de Arquivos: Apresenta o arquivo para exclusão ou download. Mantém o formulário principal com enctype= text/plain". Figura B9.12. Opções que permitem exclusão ou baixar (download). Entendendo estes "modos padrões", defina as duas mensagens como na Figura B9.13. Figura B9.13. Rótulos para a parte de arquivo. - Realizando Liberação Rápida Com Reinício via Maven Construção e Liberação IV Neste ponto já podemos fazer uma nova liberação do nosso terceiro Caso de Uso Padrão, agora finalizado, utilizando a Liberação Rápida para Tomcat com Reinicio.

8 Capítulo B9 Mas antes uma observação: Dependendo do número de liberações realizadas em sequência com o Tomcat no ar, o Desenvolvedor pode-se deparar com uma mensagem de OutOfMemory no segmento de memória PermGen da JVM. Figura B9.14. Problema conhecido que exige reinício em desenvolvimento, após certo número de liberações. Este é um problema clássico na lista do Tomcat. Após uma liberação a quente (hot-deploy), sem parada do servidor, em alguns casos o Tomcat/JVM não consegue liberar toda a área de memória de código (PermGen), ocorrendo um leak (perda de memória que não retorna) a cada liberação. Em nossa experiência, de cerca de 5 a 10 MBytes por hot-deploy. Em tempo de desenvolvimento, o jcompany já configura o Tomcat com um aumento na área de PermGen para 128MBytes, conforme ilustra a Figura B9.15, o que deve permitir cerca de 10 (dez) ou mais liberações sem que seja preciso reiniciar o Tomcat*. Figura B9.15. Configuração do Tomcat com PermGen 256M. Ao receber esta mensagem, simplesmente pare o Tomcat e em seguida o reinicie. A parada pode ser realizada através do botão vermelho na janela de Console ou do ícone na barra de ferramentas, indicados na Figura B9.16. Figura B9.16. Parando o Tomcat no Eclipse. * Este é um problema na área de caching de código (XHTMLs, Singletons etc.) e não traz nenhum risco para a área de dados da aplicação, a memória HEAP (o que seria mais preocupante). Mas se pretender usar o Tomcat em produção, consulte um especialista, que poderá dar sugestões de contorno para esta situação.

9 Implementando a Inclusão Padrão Arquivo Anexado - Gerando Esquema Relacional (DDL) - Geração de DDL III 1. Abra o Navegador e chame 2. Acesse novamente a opção Área de TI -> Esquema DDL Geração. Em seguida selecione Atualização na lista Tipo de Esquema e clique em Gerar Esquema. Agora o jcompany irá exibir o esquema DDL necessário para sincronizarmos nosso mapeamento, tendo como novidades o uso do tipo blob e da cláusula Alter Table para acrescentar a nova coluna "ID_FOTO" a FUNCIONARIO. Veja em destaque na Figura B9.17. Figura B9.17. Esquema gerado para arquivos anexados (classes Foto e Curriculo). 3. Troque "varchar( ) for bit data" para apenas blob antes de submeter o esquema, tanto para " foto_conteudo" quanto para " curriculo_conteudo". 4. Note também que não seria possível acrescentar uma coluna "not null" a uma tabela já criada se ela possuir dados (no caso, se a coluna "id_foto" fosse Not Null). Se você possui experiência com SQL poderia deletar e recriar a tabela "funcionario", excluir seus registros com algum utilitário como o QuantumDB ou realizar alguma técnica. Mas para nosso exemplo não teremos este problema, pois a coluna "id_foto" pode ser nula. Se tudo correu bem, vamos averiguar o resultado de nosso trabalho no próximo capítulo.

10 Capítulo B9 Sumário Neste capítulo, desenvolvemos a Inclusão Padrão UC002.2 Anexar Foto e UC002.2 Anexar Currículo, o que finaliza a implementação do nosso terceiro Caso de Uso UC002 Manter Funcionário!. Discutimos peculiaridades importantes a respeito de manipulação de arquivos em suas diversas variações e implementamos um primeiro caso de herança total do mapeamento Objeto-Relacional e de reúso de componente Facelets. No próximo capítulo, iremos testar tudo o que desenvolvemos neste e no capítulo anterior, explicando em detalhes as características de usabilidade que produzimos para a manutenção de Funcionários.