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 :

See Also:
UploadedFile

Field Summary
 
Fields inherited from interface org.apache.myfaces.trinidad.webapp.UploadedFileProcessor
MAX_DISK_SPACE_PARAM_NAME, MAX_FILE_SIZE_PARAM_NAME, MAX_MEMORY_PARAM_NAME, TEMP_DIR_PARAM_NAME
 
Method Summary
 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:

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

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:
IOException
See Also:
UploadedFile.getLength(),



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