org.apache.myfaces.trinidad.webapp.UploadedFileProcessor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of trinidad-api Show documentation
Public API for the Apache MyFaces Trinidad project
The newest version!
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.myfaces.trinidad.webapp;

import java.io.IOException;

import org.apache.myfaces.trinidad.model.UploadedFile;

/**
 * Interface responsible for processing file uploads.  An Apache Trinidad
 * application has a single UploadedFileProcessor instance. For
 * more simpler, multiple chained UploadedFileProcessor option please look at
 * {@link  org.apache.myfaces.trinidad.webapp.ChainedUploadedFileProcessor}.
 * UploadedFileProcessor is accessible from the {@link org.apache.myfaces.trinidad.context.RequestContext},
 * but will be invoked automatically by the framework as needed.  Developers
 * can replace the standard processor using the
 * trinidad-config.xml file.
 * 
 * To configure file uploads, the default instance supports three context
 * initialization parameters :
 * 

 * org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY: the maximum amount of memory
 *  that can be used in a single request to store
 *  uploaded files. (Default of 100K)
 * 
org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE: the maximum amount of
 *  disk space that can be used in a single request to store
 *  uploaded files.  (Default of 2000K)
 * 
org.apache.myfaces.trinidad.UPLOAD_MAX_FILE_SIZE: the maximum
 *  file size that can be uploaded.  (Default of 2000K)
 * 
org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR: the name of a directory
 *   to store temporary files.  (Defaults to the user's temporary directory)
 * 
org.apache.myfaces.trinidad.UPLOAD_MAX_CHUNK_SIZE: the maximum
 *  chunk size that large files will be split into during upload.  (Default of 2000M)
 * 
 * 
 * @see org.apache.myfaces.trinidad.model.UploadedFile
 */
public interface UploadedFileProcessor
{
  /**
   * Initialization parameter for the default
   * UploadedFileProcessor that configures the maximum
   * amount of memory that can be used in a single request to store
   * uploaded files.  Any requirements above this will be stored on disk.
   * The default is 100 kilobytes.
   */
  public static final String MAX_MEMORY_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_MEMORY";

  /**
   * Initialization parameter for the default
   * UploadedFileProcessor that configures the maximum
   * amount of disk space that can be used in a single request to store
   * uploaded files.  The default is 2000 kilobytes.  Any requests that
   * exceed this size will result in an EOFException being thrown
   * on that request.
   */
  public static final String MAX_DISK_SPACE_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_DISK_SPACE";

  /**
   * Initialization parameter for the default
   * UploadedFileProcessor that configures the 
   * to the directory where temporary files should be stored while
   * uploading.  This defaults to the the application server's temporary
   * directory, as provided by the "javax.servlet.context.tempdir"
   * property.  If that is not set, the System "java.io.tempdir" property
   * will be used as a backup.
   */
  public static final String TEMP_DIR_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_TEMP_DIR";

  /**
   * Initialization parameter for the default
   * UploadedFileProcessor that configures the maximum
   * file size that can be uploaded. The default is -1 (unlimited).  Any requests that
   * exceed this size will result in an EOFException being thrown
   * on that request.
   */
  public static final String MAX_FILE_SIZE_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_FILE_SIZE";
  
  /**
   * Initialization parameter for the default
   * UploadedFileProcessor that configures the maximum
   * chunk size that large files will be split into during upload. 
   * The default is 2000M and is also the maximum allowed value.
   */
  public static final String MAX_CHUNK_SIZE_PARAM_NAME = "org.apache.myfaces.trinidad.UPLOAD_MAX_CHUNK_SIZE";
  
  /**
   * Initialization parameter default value of 100 kilobytes for the default
   * UploadedFileProcessor parameter MAX_MEMORY_PARAM_NAME.
   */
  public static final long DEFAULT_MAX_MEMORY = 102400L;
  
  /**
   * Initialization parameter default value of 2000 kilobytes for the default
   * UploadedFileProcessor parameter MAX_DISK_SPACE_PARAM_NAME.
   */
  public static final long DEFAULT_MAX_DISK_SPACE = 2048000L;
  
  /**
   * Initialization parameter default value of 2000 kilobytes for the default
   * UploadedFileProcessor parameter MAX_FILE_SIZE_PARAM_NAME.
   */
  public static final long DEFAULT_MAX_FILE_SIZE = -1L;
  
  /**
   * Initialization parameter default value of 2000 megabytes for the default
   * UploadedFileProcessor parameter MAX_CHUNK_PARAM_NAME.
   */
  public static final long DEFAULT_MAX_CHUNK_SIZE = 2000000000L;
  
  /**
   * Initialize the UploadedFileProcessor with access to the current
   * web application context. 
   * 
   * @param context the current ServletContext or PortletContext
   */
  public void init(Object context);

  /**
   * Process a single uploaded file, moving it from temporary
   *   storage to per-request storage.  An implementation of this
   *   method must process an incoming UploadedFile object
   *   and return a new UploadedFile instance that will
   *   remain valid for the duration of this request.  The incoming
   *   UploadedFile
   *   object is a temporary file object that has a number of 
   *   restrictions:
   *  
   *    {@link UploadedFile#getInputStream} may only be called once
   *    {@link UploadedFile#getLength} returns -1, since the length is not yet available
   *    {@link UploadedFile#getFilename} has not yet been internationalized;  users should not
   *      rely on its value, but simply use it unmodified in the
   *      outgoing UploadedFile
   *  
   *  
   *  The UploadedFile object returned from this method
   *  must remain valid for the duration of this request.  The framework
   *  guarantees that {@link UploadedFile#dispose} will be called before
   *  the request completes.
   *  
   *  
   *  If any implementation of this method throws an IOException, it is considered that there is a 
   *  error in processing the uploaded file, and the message contained in the IOException is shown 
   *  to the user as a value conversion warning.
   *  If the processing failure is less severe, and if the failure need to be meaningfully reported 
   *  to the end users, the length of the returned UploadedFile should be set to -1, and its 
   *  getOpaqueData() should provide the error details. The object returned by getOpaqueData() 
   *  should implement a toString() that returns a detailed error message. During the JSF life cycle 
   *  later, the input file component would show this message as value conversion warning to the 
   *  user.
   *  @see UploadedFile#getLength()
   *  @see UploadedFile#getOpaqueData()
   *  
   * @param request the current servlet or portlet request
   * @param file a temporary file object
   * @return a new instance of UploadedFile.  It is legal to return null,
   *   in which case the file will not be available later in the request.
   */
  public UploadedFile processFile(
    Object request, UploadedFile file) throws IOException;
}