Upload com o RichFaces

Não é incomum uma aplicação web ter a necessidade de receber algum tipo de arquivo de seus usuários. Este arquivo pode ser um documento, uma imagem, um vídeo ou um arquivo compactado. Desta forma, sua aplicação tem a necessidade de oferecer este recurso, mais conhecido com Upload.

por Everton Coimbra de Araújo

Este é mais um artigo que submeto ao Linha de Código, dando sequência a uma série de material, resultado obtido através de pesquisas e laboratórios com meus alunos da UTFPR, campus Medianeira. Reforço o empenho e dedicação destes alunos, que foi extremamente comprometido com a pesquisa e aprendizado durante os semestres que mantivemos contato próximo nas disciplinas que a eles eu ministrava. Isso me motivou muito e fazer com que o resultado dos trabalhos deles aparecesse para o mundo e, nada melhor do que o Linha de Código para isso.

INTRODUÇÃO

Não é incomum uma aplicação web ter a necessidade de receber algum tipo de arquivo de seus usuários. Este arquivo pode ser um documento, uma imagem, um vídeo ou um arquivo compactado. Desta forma, sua aplicação tem a necessidade de oferecer este recurso, mais conhecido com Upload.

Para a implementação da aplicação de exemplo demonstrada neste material faz-se necessário o uso de algumas bibliotecas, softwares e componentes. O IDE utilizado para a implementação foi o Eclipse Galileo JEE, sendo a aplicação publicada no Apache Tomcat 6.0.18. Em relação aos demais recursos, estão relacionados a seguir.

CONHECIMENTOS NECESSÁRIOS

Para a aplicação do apresentado neste material os conhecimentos abaixo se fazem necessário para um melhor aproveitamento do conteúdo:

CRIANDO UM PROJETO JSF

Para criar uma aplicação web, com o JSF habilitado, através do Eclipse, tendo o WTP (Web Tools Platform) habilitado, é necessária uma atividade relativamente simples. Clique no menu File→New→Other→Web→Dynamic Web Project, pressione Next e será exibida a janela representada pela Figura 1.





Figura 1 – Criando um projeto Web

1. Na janela exibida e representada pela Figura 1 informe o nome para seu projeto no campo Project Name.

2. Selecione o Runtime do servidor web onde o deploy será realizado. Caso não apareça um Runtime, é preciso adicionar e configurar um. O Runtime representa uma configuração para um servidor web específico, onde, normalmente sua aplicação será publicada.

3. Selecione a configuração para o projeto JSF.

4. Clique no botão Next e uma janela de acordo à exibida pela Figura 2 será exibida.

Figura 2 – Configurando a estrutura de pastas

A janela representada pela Figura 2 habilita a criação de pastas que seu projeto possa necessitar, neste caso, clique em Next e a tela representada pela Figura 3 será exibida.

Figura 3 – Configurando dados web do projeto

Na janela representada pela Figura 3, caso não deseje alterar os valores informados, pressione Next, ou, altere os dados e em seguida pressione Next. A janela apresentada na Figura 4 será então exibida.

Figura 4 – Configurações dos recursos JSF

Marque a biblioteca que possui a implementação JSF e então clique no botão Finish. Caso a biblioteca do JSF não apareça para você, é preciso criá-la.

CONFIGURANDO O RICHFACES

Uma vez criada a aplicação, o arquivo de configuração da mesma (web.xml) já foi criado e também disponibilizado. Como será feito uso do Richfaces para implementação do exemplo de upload, é preciso configurar a aplicação para uso dele. Para isso, adicione em seu web.xml o trecho apresentado no código apresentado na Listagem 1. Insira este código antes do Servlet do JSF.

Listagem 1 – Configurando o Richfaces no web.xml

É preciso também importar para sua aplicação os jars do Richfaces (richfaces-api-3.3.1.GA.jar, richfaces-impl-3.3.1.GA e richfaces-ui-3.3.1.GA)., do Apache Commons Logging (commons-logging-1.1.1.jar), Apache Commons Digester  (commons-digester-2.0.jar), Apache Commons Bean Utils (commons-beanutils-1.8.0.jar) e o JSTL (jstl-api-1.2.jar). A importação de JARs para a aplicação não faz parte do escopo deste material.

CRIANDO A PÁGINA PARA ENVIO DO ARQUIVO

A página JSF que permitirá a interação do usuário para o envio de um determinado arquivo tem a implementação exibida na Listagem 2. Lembre-se que este arquivo (que é um JSP) deve estar na pasta do contexto da aplicação web. Neste caso, a WebContent.

Listagem 4 – Página JSF para realização do Upload

EXECUTANDO A APLICAÇÃO

Ao realizar o deploy e acessar este recurso em sua aplicação web, a página representada pela Figura 5 é exibida em seu navegador. Não faz parte deste artigo a formatação visual do controle.

Figura 5 – Aplicação de Upload

Ao clicar sobre o botão Add... uma janela de abertura de arquivo (padrão do sistema operacional) para seleção do arquivo é exibida. Selecione seu arquivo e então o componente é atualizado, conforme exibido pela Figura 6.

Figura 6 – Upload com arquivos selecionados para envio

Agora, para realizar o upload do arquivo desejado, basta clicar no botão Upload, o qual é exibido pela Figura 6, acima. O arquivo enviado é gravado por padrão na pasta de arquivos temporários do usuário, desta forma, pode variar de sistema operacional para sistema operacional. No Windows Vista esta pasta é a C:\Users\<nomeusuarioconectado>\AppData\Local\Temp. Verifique na Figura 7 a existência do arquivo que teve seu upload realizado.

Figura 7 – Arquivo de upload recebido

Após o envio do arquivo ter sido finalizado, o controle de Upload tem uma nova representação, demonstrada na sequência, pela Figura 8.

Figura 8 – Componente de Upload após o envio do arquivo

As opções “Clear” e “Clear All” que aparecem logo após o envio do(s) arquivo(s), são utilizadas para limpar o componente de Upload. O “Clear” é utilizado para limpar o arquivo ao qual se refere e o “Clear All” é usado para limpar todos os arquivos listados.

Se for necessário limpar toda a lista de arquivos imediatamente após que estes são enviados pelo componente utiliza-se então o atributo “autoclear” como na Figura 9.

Figura 9 – Utilização do atributo autoclear no file upload

DESTINO PARA OS ARQUIVOS DE UPLOAD

Como visto anteriormente, o componente de Upload do Richfaces por si só já envia o arquivo para o servidor de sua aplicação web, porém, muitas vezes, quando se recebe um arquivo através de upload, existe a necessidade de ter este arquivo em um local físico específico, quer seja para puro armazenamento, quer seja para persistência deste arquivo, como binário, em uma tabela de uma base de dados. Desta forma, todos os arquivos enviados através do upload deverão ser armazenados em um diretório específico de sua aplicação. É preciso reforçar que este diretório necessita de direito de escrita. Crie este diretório dentro da pasta WebContent. O nome dele fica a seu critério.

CRIANDO A CLASSE GERENCIADORA DE UPLOADS

Como visto na configuração do Richfaces, na Listagem 1, ele oferece suporte à criação de arquivos temporários quando se faz uploads e esta característica está habilitada, por isso o envio do arquivo no exemplo anterior funcionou sem nenhuma configuração. Mas, a necessidade nem sempre é receber o arquivo no diretório temporário do usuário, como comentado anteriormente. Para isso é preciso que o upload seja gerenciado, como é apresentado na sequência.

FAZENDO USO DE ARQUIVOS TEMPORÁRIOS

O componente do RichFaces permite o upload de arquivos praticamente sem a necessidade de códigos, como visto anteriormente, porém, o arquivo enviado, sem um método responsável pelo gerenciamento do upload, é gravado na pasta temporária, definida pelo sistema operacional, onde a aplicação web está hospedada. Esta operação é realizada devido a configuração do Richfaces que habilita a criação de arquivos temporários e que está presente na Listagem 1.

O gerenciamento do controle de upload do Richfaces pode ser realizado através de Managed Beans, desta forma, a implementação do Managed Bean com o método responsável pelo tratamento deste serviço é apresentada na Listagem 5.

Listagem 5 – Método que gerencia o upload com o criação de arquivo temporário habilitado

É possível verificar no código apresentado na Listagem 5 que as instruções possuem as seguintes finalidades:

· Linha 18: Obtenção do contexto da aplicação Faces;

· Linha 19: Obtenção do contexto do Servlet, pois é preciso obter informações relacionadas à aplicação, como por exemplo, o local físico onde ela está sendo executada;

· Linha 20:Obtém o caminho físico real onde o Servlet (sua aplicação) está sendo executado;

· Linha 21: Obtém o item recebido como upload pelo evento do Managed Bean;

· Linha 22: Obtém o arquivo vinculado ao item do upload;

· Linha 23: Obtém o caminho físico do arquivo recebido;

· Linha 24 à 28: Obtém apenas o nome do arquivo recebido;

· Linha 29: Adiciona ao caminho da execução de sua aplicação a pasta destino para o arquivo recebido, seguido do nome do arquivo. Verifique é preciso que (se seguir este exemplo) possua uma pasta chamada uploads dentro de seu contexto; e

· Linha 30: Move o arquivo recebido, do caminho de origem, para o novo caminho, definido na Linha 29.

Uma vez criada a classe do Managed Bean, o mesmo deve ser configurado no faces-config.xml, como apresentado na Listagem 6.

Listagem 6 – Configuração do Managed Bean no faces-config.xml

CRIANDO A PÁGINA PARA ENVIO DO ARQUIVO

A página JSF que permitirá a interação do usuário para o envio de um determinado arquivo tem a implementação exibida na Listagem 7. Lembre-se que este arquivo (que é um JSP) deve estar na pasta do contexto da aplicação web. Neste caso, a WebContent.

Listagem 7 – Página JSF para realização do Upload

Realize o deploy de sua aplicação e a invoque em seu navegador. Verifique em sua pasta de destino que o arquivo enviado estará lá gravado.

NÃO FAZENDO USO DE ARQUIVOS TEMPORÁRIOS

Caso não seja seu desejo/necessidade fazer uso do recurso de criação de arquivos temporários, basta atribuir falso ao respectivo parâmetro apresentado na Listagem 1 e fazer uso da lógica apresentada no código da Listagem 8.

Listagem 8 – Método que gerencia o upload com a criação de arquivo temporário desabilitado

É possível verificar no código apresentado na Listagem 8 que as instruções possuem as seguintes finalidades :

· Linha 34: Obtenção do contexto da aplicação Faces;

· Linha 35: Obtenção do contexto do Servlet, pois é preciso obter informações relacionadas à aplicação, como por exemplo, o local físico onde ela está sendo executada;

· Linha 36: Obtém o caminho físico real onde o Servlet (sua aplicação) está sendo executado;

· Linha 38: Obtém nome do arquivo recebido, assim como caminho completo do mesmo;

· Linha 39 à 43: Obtém apenas o nome do arquivo recebido;

· Linha 44: Adiciona ao caminho da execução de sua aplicação a pasta destino para o arquivo recebido, seguido do nome do arquivo. Verifique é preciso que (se seguir este exemplo) possua uma pasta chamada uploads dentro de seu contexto; e

· Linha 45 a 49: Abre para leitura e grava o arquivo no destino.

A página JSF para realização do Upload sem uso da criação do arquivo temporário é a mesma apresentada pela Listagem 7, mudando apenas o método chamado no managed-bean.

ALGUMAS OPÇÕES ADICIONAIS

É possível também definir o tamanho máximo permitido para os arquivos upados através da inclusão, no elemento de filtro do Richfaces no web.xml, da tag <param-name>maxRequestSize</param-name>, como pode ser visualizado pela Listagem 9.

<init-param>    <param-name>maxRequestSize</param-name>       <param-value>999999</param-value> </init-param>

Listagem 9 – Configuração do tamanho limite para o arquivo enviado

É possível também restringir os arquivos através de seus tipos. Para isso basta usar o atributo acceptedTypes no componente <rich:fileUpload/>, como mostrado pela Listagem 10.

Listagem 10 – Definindo o tipo de arquivo que é aceito no envio

É possível também preparar o componente para o envio de múltiplos arquivos simultaneamente, delimitando a quantidade máxima permitida ao usuário. Para isso utiliza-se o atributo “maxFilesQuantity”. Na Listagem 11 foi definido uma quantidade máxima de 2 arquivos, assim, após atingir esse limite, o “addControlLabel” (botão Add...) é desabilitado automaticamente como mostrado na Listagem 12.

Listagem 11 – Definindo quantidade máxima de arquivos

CONCLUSÕES

A possibilidade do usuário enviar arquivos de diferentes extensões para diferentes fins em aplicações web é de extrema importância, pois além de deixar a aplicação mais completa, o programador que faz uso deste recurso pode apresentar aos seus usuários uma aplicação mais dinâmica com maior interatividade tornando-a mais agradável. O uso do Richfaces para a implementação desta funcionalidade é extremamente simples e eficaz, como pôde ser verificado por este artigo. É claro que muita funcionalidade não foi explorada por este material, ficando a cargo do leitor aguçar sua curiosidade e identificá-las.