org.apache.myfaces.trinidad.webapp

## Interface UploadedFileProcessor

- All Known Subinterfaces:
    ChainedUploadedFileProcessor

      public interface UploadedFileProcessor

  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 `ChainedUploadedFileProcessor`. UploadedFileProcessor is accessible from the `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 Also:
    `UploadedFile`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `DEFAULT_MAX_CHUNK_SIZE` Initialization parameter default value of 2000 megabytes for the default `UploadedFileProcessor` parameter MAX_CHUNK_PARAM_NAME.
    `static long` | `DEFAULT_MAX_DISK_SPACE` Initialization parameter default value of 2000 kilobytes for the default `UploadedFileProcessor` parameter MAX_DISK_SPACE_PARAM_NAME.
    `static long` | `DEFAULT_MAX_FILE_SIZE` Initialization parameter default value of 2000 kilobytes for the default `UploadedFileProcessor` parameter MAX_FILE_SIZE_PARAM_NAME.
    `static long` | `DEFAULT_MAX_MEMORY` Initialization parameter default value of 100 kilobytes for the default `UploadedFileProcessor` parameter MAX_MEMORY_PARAM_NAME.
    `static String` | `MAX_CHUNK_SIZE_PARAM_NAME` Initialization parameter for the default `UploadedFileProcessor` that configures the maximum chunk size that large files will be split into during upload.
    `static String` | `MAX_DISK_SPACE_PARAM_NAME` 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.
    `static String` | `MAX_FILE_SIZE_PARAM_NAME` Initialization parameter for the default `UploadedFileProcessor` that configures the maximum file size that can be uploaded.
    `static String` | `MAX_MEMORY_PARAM_NAME` 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.
    `static String` | `TEMP_DIR_PARAM_NAME` Initialization parameter for the default `UploadedFileProcessor` that configures the to the directory where temporary files should be stored while uploading.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `init(Object context)` Initialize the UploadedFileProcessor with access to the current web application context.
    `UploadedFile` | `processFile(Object request, UploadedFile file)` Process a single uploaded file, moving it from temporary storage to per-request storage.

- - ### Field Detail

    - #### MAX_MEMORY_PARAM_NAME

          static final String MAX_MEMORY_PARAM_NAME

      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.
      See Also:
        Constant Field Values

    - #### MAX_DISK_SPACE_PARAM_NAME

          static final String MAX_DISK_SPACE_PARAM_NAME

      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.
      See Also:
        Constant Field Values

    - #### TEMP_DIR_PARAM_NAME

          static final String TEMP_DIR_PARAM_NAME

      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.
      See Also:
        Constant Field Values

    - #### MAX_FILE_SIZE_PARAM_NAME

          static final String MAX_FILE_SIZE_PARAM_NAME

      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.
      See Also:
        Constant Field Values

    - #### MAX_CHUNK_SIZE_PARAM_NAME

          static final String MAX_CHUNK_SIZE_PARAM_NAME

      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.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_MEMORY

          static final long DEFAULT_MAX_MEMORY

      Initialization parameter default value of 100 kilobytes for the default `UploadedFileProcessor` parameter MAX_MEMORY_PARAM_NAME.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_DISK_SPACE

          static final long DEFAULT_MAX_DISK_SPACE

      Initialization parameter default value of 2000 kilobytes for the default `UploadedFileProcessor` parameter MAX_DISK_SPACE_PARAM_NAME.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_FILE_SIZE

          static final long DEFAULT_MAX_FILE_SIZE

      Initialization parameter default value of 2000 kilobytes for the default `UploadedFileProcessor` parameter MAX_FILE_SIZE_PARAM_NAME.
      See Also:
        Constant Field Values

    - #### DEFAULT_MAX_CHUNK_SIZE

          static final long DEFAULT_MAX_CHUNK_SIZE

      Initialization parameter default value of 2000 megabytes for the default `UploadedFileProcessor` parameter MAX_CHUNK_PARAM_NAME.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### init

          void init(Object context)

      Initialize the UploadedFileProcessor with access to the current web application context.
      Parameters:
        `context` - the current ServletContext or PortletContext

    - #### processFile

          UploadedFile processFile(Object request,
                                 UploadedFile file)
                                   throws IOException

      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:
      - `UploadedFile.getInputStream()` may only be called once
      - `UploadedFile.getLength()` returns -1, since the length is not yet available
      - `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 `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.

      Parameters:
        `request` - the current servlet or portlet request
        `file` - a temporary file object
      Returns:
        a new instance of UploadedFile. It is legal to return null, in which case the file will not be available later in the request.
      Throws:
        `IOException`
      See Also:
        `UploadedFile.getLength()`, ``

Copyright © 2001-2017 The Apache Software Foundation. All Rights Reserved.