Skip navigation links

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

DEFAULT_MAX_CHUNK_SIZE, DEFAULT_MAX_DISK_SPACE, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_MEMORY, MAX_CHUNK_SIZE_PARAM_NAME, MAX_DISK_SPACE_PARAM_NAME, MAX_FILE_SIZE_PARAM_NAME, MAX_MEMORY_PARAM_NAME, TEMP_DIR_PARAM_NAME

Method Summary

void	init(java.lang.Object context) Initialize the ChainedUploadedFileProcessor with access to the current web application context.
UploadedFile	processFile(java.lang.Object request, UploadedFile file) Process a single uploaded file.

Method Detail

init

void init(java.lang.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(java.lang.Object request,
                         UploadedFile file)
                         throws java.io.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).

If one of chained file processor throws an IOException in this method, it is considered that there is a error in processing the uploaded file, the chain is broken hence, the file upload process stops, 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.

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:

java.io.IOException

See Also:

UploadedFile.getLength(),



Skip navigation links