Transferindo arquivos em aplicativos NetBeans Visual Web JSF

Este tutorial descreve como usar o NetBeans IDE 6.0 e 6.1 para transferir e exibir um arquivo de imagem (JPEG, PJPEG, GIF, PNG, ou X-PNG). Também esta incluído um minitutorial sobre como transferir um arquivo de texto.

Conteúdo

• Sobre o componente de Transferência de arquivo
• Criando uma página que inclui um componente Transferência de arquivo
• Adicionando código para transferências de imagem
• Testando a aplicação
• Fazer mais n° 1: Transferindo um arquivo de texto
• Fazer mais n° 2: Modificando o tamanho máximo da transferência de arquivo
• Fazer mais n° 3: Salvando a transferência de arquivo para outros locais
• Problemas conhecidos

Para seguir este tutorial, você precisa dos seguintes recursos e softwares.

* Para tirar vantagem dos recursos Java EE 5 do NetBeans IDE , use um servidor da aplicação que seja totalmente compatível com a especificação Java EE 5, tal como o Servidor da aplicação GlassFish V2 UR2. Se você estiver usando um servidor diferente, consulte as Notas de versão e as Perguntas freqüentes para saber problemas conhecidos e soluções alternativas. Para obter informações detalhadas sobre os servidores suportados e a plataforma Java EE, consulte as Notas de versão.

Observação para usuários do NetBeans IDE 6.1:

Criar um projeto no NetBeans 6.1 inclui novas opções que podem ser deixadas como padrão. Por exemplo, a caixa de verificação Usar pasta dedicada para armazenar bibliotecas pode ficar desmarcada.

Vinculação sob demanda dos recursos do NetBeans IDE 6.1. Onde os componentes requerem codificação de Java, agora você deve adicionar manualmente o atributo de vinculação aos componentes em uma aplicação Visual Web JSF. Para fazê-lo, clique com o botão direito do mouse em cada componente e escolha Adicionar atributo de vinculação. Para obter mais informações, consulte o On-demand Binding Attribute Wiki.

Sobre o componente de Transferência de arquivo

O componente Transferência de arquivo permite aos usuários da aplicação Web localizar um arquivo em seu sistema e transferir esse arquivo para o servidor. Este componente é útil para reunir arquivos de texto, arquivos de imagem e outros dados. O conteúdo do arquivo transferido é armazenado juntamente com algumas informações sobre tal arquivo, incluindo o nome, o tamanho e o tipo MIME (como texto/simples ou imagem/jpeg).

O servidor mantém o arquivo transferido na memória a menos que este ultrapasse 4096 bytes. Do contrário, o servidor mantém o conteúdo do arquivo em um arquivo temporário. Você pode alterar este limite modificando o parâmetro sizeThreshold da entrada do filtro UploadFilter no arquivo web.xml da aplicação Web, conforme descrito abaixo. Para obter mais informações sobre como modificar o arquivo web.xml, consulte a última seção deste tutorial, Fazer mais: Modificando o tamanho máximo da transferência de arquivo.

Em casos em que deseja manter o arquivo transferido, você tem três opções:

• Gravar o arquivo em um local da suas escolha, como mostrado neste tutorial.
• Criar uma propriedade UploadedFile em um bean gerenciado e defini-la como o valor do componente antes de você sair da página (como no método de ação do botão).
• Salve o arquivo em um banco de dados.

Por padrão, o componente Transferência de arquivos pode manipular arquivos de até um megabyte. Você pode alterar o tamanho máximo do arquivo, modificando o parâmetro maxSize do filtro UploadFilter no arquivo web.xml do aplicativo, como descrito na última seção deste tutorial, Fazer mais: Modificando o tamanho máximo da transferência de arquivo.

Criando uma página que inclui um componente Transferência de arquivo

Primeiro, você constrói um formulário que permite aos usuários selecionar um arquivo a ser transferido.

Observação: Vinculação sob demanda dos recursos do NetBeans IDE 6.1. Onde os componentes requerem codificação de Java, agora você deve adicionar manualmente o atributo de vinculação aos componentes em uma aplicação Visual Web JSF. Para fazê-lo, clique com o botão direito do mouse em cada componente e escolha Adicionar atributo de vinculação. Para obter mais informações, consulte o On-demand Binding Attribute Wiki.

1. Crie um novo projeto Aplicação Web , nomeie-o como FileUploadExample e ative o framework Visual Web JavaServer Faces.

   A figura abaixo mostra a página que você criará nas etapas a seguir:

   
2. Na seção Básico da Paleta, solte um componente Rótulo na página, digite Escolher um arquivo a ser transferido: e pressione Enter.
3. Arraste um componente Transferência de arquivo para a página e solte-o abaixo do componente Rótulo.
4. Arraste um componente Botão para a página, digite Transferir arquivo e pressione Enter. Na janela Propriedades, defina a propriedade id do Botão como uploadFileButton.
5. Arraste um componente Rótulo para a página e defina o texto como Nome do arquivo:
6. Coloque um componente Texto estático à direita do rótulo. Na janela Propriedades, defina a propriedade id do Texto estático como fileNameStaticText.
7. Arraste outro Rótulo para a página. Defina o texto do rótulo como Tipo de arquivo:
8. Coloque um componente Texto estático à direita do novo rótulo. Defina o id do Texto estático como fileTypeStaticText.
9. Arraste outro par Rótulo e Texto estático para a página. Defina o texto do Rótulo como Tamanho do arquivo: e o id do Texto estático como fileSizeStaticText.
10. Coloque um componente Imagem abaixo dos componentes Texto estático.
11. Coloque um componente Grupo de mensagens abaixo do componente Imagem.

Adicionando código para transferências de imagem

Agora que possui o formulário de transferência de arquivo básico, você deve adicionar o código para manipular a transferência de arquivo.

Observação: Vinculação sob demanda dos recursos do NetBeans IDE 6.1. Onde os componentes requerem codificação de Java, agora você deve adicionar manualmente o atributo de vinculação aos componentes em uma aplicação Visual Web JSF. Para fazê-lo, clique com o botão direito do mouse em cada componente e escolha Adicionar atributo de vinculação. Para obter mais informações, consulte o On-demand Binding Attribute Wiki.

1. Clique duas vezes no botão Transferir arquivo para abrir o editor Java e adicione o manipulador de eventos do botão, uploadFileButton_action, ao bean de página.

   Antes de adicionar o código a esse método, defina as variáveis para armazenar o arquivo de imagem e adicione código aos métodos init() e prerender().

2. Role para o método init() e adicione as duas variáveis seguintes antes do método.

   Amostra de código 1: Variáveis

   private String realImageFilePath; private static final String IMAGE_URL = "/resources/image-file";

   
   A variável realImageFilePath é o caminho real e o nome do arquivo de imagem no servidor. A variável IMAGE_URL é o caminho lógico do arquivo de imagem na aplicação Web em execução.

3. Adicione as linhas seguintes (mostradas em negrito) no fim do método init, mas observe que o código contém um erro Classe não encontrada. Adicione instruções de importação para corrigir esses erros na etapa 6. Depois de inserir o código, você pode presisonar Ctrl-Shift-F para reformatar o código.

   Amostra de código 2: método init

   public void init() { super.init(); // Perform application initialization that must complete // *before* managed components are initialized // TODO - add your own initialiation code here // Managed Component Initialization // Perform application initialization that must complete // *after* managed components are initialized // TODO - add your own initialization code here ServletContext theApplicationsServletContext = (ServletContext) this.getExternalContext().getContext(); this.realImageFilePath = theApplicationsServletContext.getRealPath(IMAGE_URL); }

   
   Esse código converte IMAGE_URL para o caminho real do arquivo de imagem, de forma que o arquivo possa ser gravado no diretório correto no servidor.

4. Role para o método prerender e adicione o seguinte código:

   Amostra de código 3: Método prerender

   public void prerender() { String uploadedFileName = (String) this.fileNameStaticText.getValue(); if ( uploadedFileName != null ) { image1.setUrl(IMAGE_URL); } }

   
   Se houver um arquivo de imagem a ser exibido, esse código vincula o arquivo ao componente Imagem.

5. Adicione o seguinte código ao método uploadFileButton_action()

   Amostra de código 4: Código para transferir um arquivo de imagem

   public String uploadFileButton_action() { UploadedFile uploadedFile = fileUpload1.getUploadedFile(); if( uploadedFile == null ) return null; String uploadedFileName = uploadedFile.getOriginalName(); // Some browsers return complete path name, some don't // Make sure we only have the file name // First, try forward slash int index = uploadedFileName.lastIndexOf('/'); String justFileName; if ( index >= 0) { justFileName = uploadedFileName.substring( index + 1 ); } else { // Try backslash index = uploadedFileName.lastIndexOf('\\'); if (index >= 0) { justFileName = uploadedFileName.substring( index + 1 ); } else { // No forward or back slashes justFileName = uploadedFileName; } } this.fileNameStaticText.setValue(justFileName); Long uploadedFileSize = new Long(uploadedFile.getSize()); this.fileSizeStaticText.setValue(uploadedFileSize); String uploadedFileType = uploadedFile.getContentType(); this.fileTypeStaticText.setValue(uploadedFileType); if ( uploadedFileType.equals("image/jpeg") || uploadedFileType.equals("image/pjpeg") || uploadedFileType.equals("image/gif") || uploadedFileType.equals("image/png") || uploadedFileType.equals("image/x-png")) { try { File file = new File(this.realImageFilePath); uploadedFile.write(file); } catch (Exception ex) { error("Cannot upload file: " + justFileName); } } else { error("You must upload a JPEG, PJPEG, GIF, PNG, or X-PNG file."); new File(this.realImageFilePath).delete(); } return null; }

   
   Para cada arquivo, o programa extrai o nome do arquivo, o tamanho e o tipo a partir do objeto UploadedFile e vincula-os aos componentes Texto estático. O programa toma uma decisão importante com todas as transferências: Se o arquivo for JPEG, PJPEG, GIF, PNG ou X-PNG, o programa salva o arquivo transferido na variável realImageFilePath. Se o arquivo não for um arquivo de imagem válido ou se houver outros problemas para transferir o arquivo, o programa excluirá a imagem do servidor e exibirá uma mensagem de erro.

6. Clique com o botão direito do mouse no editor de Java e escolha Corrigir importações. Na caixa de diálogo Corrigir importação, garanta que java.io.File apareça na lista suspensa Arquivo e clique em OK.

   Essa ação corrige os erros no código.

Testando a aplicação

1. Execute a aplicação.

2. Clique em Explorar para navegar nas unidades locais e selecione um arquivo de imagem a ser transferido. Em seguida, clique no botão Transferir arquivo.

   A figura seguinte mostra o aplicativo com um arquivo JPEG transferido. A imagem é armazenada no diretório do projeto\FileUploadExample\build\web\resources.

   

3. Indique um arquivo de texto no componente Transferência de arquivo e clique no botão Transferir arquivo. Verifique se a mensagem de erro é exibida.

   Observação: A renderização do componente Transferência de arquivo do componente Transferência de arquivo pode diferir dependendo do navegador da Web. Certifique-se de testar o componente nos navegadores da Web que espera que os usuários utilizem.

Fazer mais n° 1: Transferindo um arquivo de texto

Esta seção é um minitutorial sobre como transferir um arquivo de texto. Este exemplo exibe o conteúdo do arquivo em um componente Área de texto, e o nome e o tamanho do arquivo em um componente Grupo de mensagens. Este exemplo não salva o conteúdo do arquivo. Para fazê-lo, você deve adicionar o código para salvar o arquivo no disco, como mostrado no exemplo anterior.

Observação: Vinculação sob demanda dos recursos do NetBeans IDE 6.1. Onde os componentes requerem codificação de Java, agora você deve adicionar manualmente o atributo de vinculação aos componentes em uma aplicação Visual Web JSF. Para fazê-lo, clique com o botão direito do mouse em cada componente e escolha Adicionar atributo de vinculação. Para obter mais informações, consulte o On-demand Binding Attribute Wiki.

1. Crie um novo projeto Aplicação Web que ative o framework Visual Web JavaServer Faces.
2. Arraste um componente Transferência de arquivo para a página.
3. Adicione um componente Botão, um componente Área de texto e um componente Grupo de mensagens.

Observação: Vinculação sob demanda dos recursos do NetBeans IDE 6.1. Se estiver usando o NetBeans IDE 6.1, você deve adicionar manualmente um atributo de vinculação aos componentes dos quais deseja criar o script em código Java. Para fazê-lo, clique com o botão direito do mouse em cada componente e escolha Adicionar atributo de vinculação. Para obter mais informações, consulte o On-demand Binding Attribute Wiki.

4. Clique duas vezes no componente Botão e adicione o código da ação seguinte ao método button1_action():

   Amostra de código 5: Código para transferir um arquivo de texto

   public String button1_action() { UploadedFile uploadedFile = (UploadedFile) fileUpload1.getUploadedFile(); if( uploadedFile == null ) return null; info("Uploaded file originally named '" + uploadedFile.getOriginalName() + "' of size '" + uploadedFile.getSize() + "'"); textArea1.setText(uploadedFile.getAsString()); return null; }

5. Pressione Ctrl-Shift-I para corrigir importações e adicionar automaticamente a instrução de importação UploadedFile.

6. Execute a aplicação. A figura seguinte mostra uma página de amostra com um arquivo de texto transferido.

   

Fazer mais n° 2: Modificando o tamanho máximo da transferência de arquivo

Para ativar a transferência de um arquivo maior que um megabyte (tal como um arquivo de imagem grande, ZIP, JAR ou arquivo executável), você deve modificar o parâmetro maxSize do filtro UploadFilter em no arquivo web.xml do aplicativo.

1. Abra a janela Arquivos, expanda nome-do-projeto > Web > WEB-INF.
2. Clique com o botão direito do mouse no nó web-xml e escolha Editar.
3. No editor XML, clique no botão Filtros.
4. Selecione o parâmetro maxSize do UploadFilter e clique no botão Editar.

5. Na caixa de diálogo, defina Valor do parâmetro como o valor desejado e clique em OK.

   Observação: Por motivos de segurança, não defina o parâmetro maxSize para um valor negativo, o que indica que não há limite no tamanho do arquivo.
6. Escolha Arquivo > Salvar para salvar as alterações.

Observação: Se um usuário do seu aplicativo tentar transferir um arquivo maior do que o valor do parâmetro maxSize, a exceção seguinte é lançada e interceptada como um erro de validação:

org.apache.commons.fileupload.FileUploadBase$SizeLimitExceededException

Nenhum arquivo foi transferido
   

Nenhum arquivo foi transferido. O arquivo especificado supera o tamanho máximo permitido de 1000000 Mb
   

onde 1000000 Mb é o valor de maxSize.

Fazer mais n° 3: Salvando a transferência de arquivo para outros locais

Este tutorial mostra como transferir um arquivo para a pasta /resources da aplicação Web. E se você quiser salvar os arquivos transferidos em outro lugar? Eis aqui algumas alternativas.

Uma pasta diferente na aplicação Web

Você pode colocar as imagens em um diretório na aplicação Web (ou seja, qualquer diretório sob o diretório web da aplicação Web). Por exemplo, você pode criar uma subpasta upload/images sob web e usar o código seguinte para armazenar as imagens aqui:

String realPath = theApplicationsServletContext.getRealPath("/upload/images");
File file = new File(realPath + File.separatorChar + justFileName);
         

Tenha cuidado ao colocar os arquivos transferidos na aplicação Web porque qualquer um pode acessar os arquivos por URL, tal como http://localhost:29080/MyWebApplication/faces/upload/images/myPicture.gif.

Um diretório conhecido no servidor

Para armazenar as imagens em qualquer outro lugar no servidor, você pode usar um código como o seguinte:

File file = new File("C:/upload/images" + File.separatorChar + justFileName);
uploadedFile.write(file);
         

Se planeja implantar o aplicativo em servidores diferentes, você pode usar um código como o seguinte para garantir que o diretório de transferência exista:

File dir = new File("C:/upload/images");
if (! dir.exists()) dir.mkdirs();
File file = new File(dir.getCanonicalPath() + File.separatorChar + justFileName);
uploadedFile.write(file);
         

Para obter mais informações sobre a classe Arquivo, consulte http://java.sun.com/j2se/1.3/docs/api/java/io/File.html.

Um diretório até agora desconhecido

Outra alternativa é colocar o caminho do diretório no descritor de deployment de forma que você possa alterar a localização dinamicamente.

1. Na janela Arquivos, expanda o nó Web e, em seguida, expanda WEB-INF. Clique duas vezes em web.xml para abri-lo.
2. Clique no botão Geral e expanda Parâmetros de contexto e clique no botão Adicionar.

3. Defina os seguintes valores e clique em OK.

   Nome do parâmetro: uploadDirectory (ou qualquer nome que você queira dar)
   Nome do parâmetro: C:/upload/images (ou qualquer que seja o caminho)
4. Feche e salve o arquivo web.xml.

5. Use o código seguinte:

   Amostra de código 9: Código para transferir um arquivo para um diretório que ainda é desconhecido

   String uploadDirectory = getExternalContext().getInitParameter ("uploadDirectory"); File file = new File(uploadDirectory + File.separatorChar + justFileName); uploadedFile.write(file);

Problemas conhecidos

• Se você executar o tutorial Transferência de arquivo usando o Internet Explorer 7, o primeiro carregamento da imagem funciona corretamente. O segundo carregamento da imagem atualiza o nome do arquivo, tipo de arquivo e tamanho de arquivo, mas não transfere a imagem. Se você recarregar o navegador, a imagem é exibida corretamente.
• O nome do arquivo da imagem deve conter caracteres ISO-8859-1.

Consulte também

• Introdução ao desenvolvimento de aplicações JSF Visual Web
• Desenvolvendo uma aplicação Web
• Trilha do aprendizado das aplicações Web