org.apache.myfaces.trinidad.webapp

## Interface ChainedUploadedFileProcessor

- All Superinterfaces:
    UploadedFileProcessor

      public interface ChainedUploadedFileProcessor
      extends UploadedFileProcessor

  Interface responsible for processing file uploads by multiple processors one after another in a chained fashion. An Apache Trinidad application could have multiple `ChainedUploadedFileProcessor` instances. A composite UploadedFileProcessor is accessible from the `RequestContext`, but will be invoked automatically by the framework as needed. Developers can implement this interface and chain many of them up together using space separated class names in `trinidad-config.xml` file under `uploaded-file-processor` element. The order in which the processors will be instantated and called will be the same as how it appears inside the element.

  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_TEMP_DIR: the name of a directory to store temporary files. (Defaults to the user's temporary directory)
  See Also:
    `UploadedFile`

- - ### Field Summary

    - ### Fields inherited from interface org.apache.myfaces.trinidad.webapp.UploadedFileProcessor

      `MAX_DISK_SPACE_PARAM_NAME, MAX_MEMORY_PARAM_NAME, TEMP_DIR_PARAM_NAME`

  - ### Method Summary

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

- - ### Method Detail

    - #### init

          void init(Object context)

      Initialize the ChainedUploadedFileProcessor with access to the current web application context. The order of call is same as it appears in trinidad-config.xml
      Specified by:
        `init` in interface `UploadedFileProcessor`
      Parameters:
        `context` - the current ServletContext or PortletContext

    - #### processFile

          UploadedFile processFile(Object request,
                                 UploadedFile file)
                                   throws IOException

      Process a single uploaded file. 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 properties of the incoming `UploadedFile` object depends on the implementation detail of the previous ChainedUploadedFileProcessor in the chain. In general all the implementations must strive to return a `UploadedFile` that should at the least comply to following:
      - `UploadedFile.getInputStream()` may only be called once
      - `UploadedFile.getLength()` returns length as it should be available
      - `UploadedFile.getFilename()` may have been internationalized; users should not rely on its value, but simply use it unmodified in the outgoing `UploadedFile`

      First ChainedUploadedFileProcessor in the list gets an `UploadedFile` implementation from the framework with the above properties and the following few more:

      - `UploadedFile.getInputStream()` may be called multiple times. Each call gives a new InputStream
      - `UploadedFile.getLength()` returns length
      Due to the above properties, if there was no change made to the underlying stream significantly by the current ChainedUploadedFileProcessor, this `UploadedFile` object could be returned intact for subsequent processing by the framework. This avoids creation of new `UploadedFile` for simple ChainedUploadedFileProcessor implementations.

      The framework guarantees that `UploadedFile.dispose()` will be called before the request completes for each UploadedFile returned by every ChainedUploadedFileProcessor. The order in which dispose() will be called is the revers of the order they are declared in trinidad-config.xml. If same UploadedFile was returned by more than one processors, dispose() will be called only once on it. Any exception that happenes during dispose() call will be logged as warning and the processing continues with the rest of the UploadedFile(s).

      Specified by:
        `processFile` in interface `UploadedFileProcessor`
      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`

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