The FileUpload widget supported by Web 2.0 runtime
The FileUpload widget
The FileUpload widget consists of the following widgets:
FileUploader
In the FileUpload widget, the Browse button is the FileUploader widget. When a FileUploader widget is clicked, a window opens that allows a user to select the file that they want to upload.
Text
If a file upload request has been processed successfully, the name of the file is displayed in the Text widget. If the file upload request fails, an error message is displayed instead.
Button
The Button widgets in a FileUpload widget can be configured to enable a user to cancel a file upload request and to remove an uploaded file.
Multilingual support is provided for Button widget in the FileUpload widget. Multilingual support for a FileUpload widget can be configured only by a developer. A user cannot change the text that is displayed on a button of the FileUpload widget.
Fore more information on the properties of the FileUpload widget, refer to the FileUpload section in the Widget description chapter of the Development Tooling guide.
The AJAX channel consists of the file upload handler and the file upload servlet. For more information on the file upload handler and the file upload servlet, refer to the following sections.
This section provides a description of the file upload handler.
A file handler is a key component in the implementation of a file upload request. Below is an example configuration of a file handler in the btt.xml file. In the example, file handlers are defined under the fileHandlers kColl. An ID and implementation class must be specified for every file handler. The parameters of every file upload handler are configured and defined according to the implementation of the handler.
Example configuration of a file upload handler in the btt.xml file
<kColl id="channelHandlers"> <field id="initializer" value="com.ibm.btt.channel.ChannelInitializer"/> <!-- allow opera users accesss the internet banking --> <kColl id="devices"> <field id="opera"value="html"description="contains"/> </kColl> <!--ajax channel configuration --> <kColl id="ajax"> <field id="encoding" value="UTF-8"/> <field id="cookies" value="true"/> <field id="runInSession" value="true"/> <field id="requestHandler" value="com.ibm.btt.cs.ajax.AjaxHtmlRequestHandler"/? <field id="presentationHandler" value="com.ibm.btt.cs.ajax.AjaxHtmlPresentationHandler"/> <!-- File handlers define all available file handlers for file upload widget. You can extend to create a new file handler, and then configure it here. --> <kColl id="fileHandlers"> <!-- sample handler, it can save and delete a file into file system with a file upload request --> <kColl>id="sampleFileHandler"> <!-- implementation class of the handler --> <field>id="implClass"value="com.ibm.btt.sample.SampleFileHandler"/> <!-- how many milli-seconds later, the fileupload handler will timeout, default value is 20 minutes --> <fieldid="timeout"value="2000"/> <!-- max file size that be allowed for the file upload handler --> <field id="maxSize" value="62914560"/> <!-- cache folder path of the file system, it is used to cache the upload file when uploading --> <field id="cachePath" value="c:\temp\fileupload\cache"/> <!-- file fold on the server, uploaded files will saved under the folder just support d:\er\wee" for DOS, or "/d/er/wee" for UNIX --> <field id="filepath" value="c:\temp\fileupload\upload"/> <!-- cache size, if file is bigger than the size, it will be saved in file system or else if will be hold in memory. --> <field id="memCacheSize" value="4096"/> </kColl> </kColl> </kColl>
A sample file handler that is implemented to save the file upload request stream to a file system is included in the sample.
The AbstractFileHandler class provides an extension point for developers to enable customers to submit file upload requests on demand.
The AbstractFileHandler class contains the following eight methods:
initConfig()
Initializes the parameters that are required by the handler, e.g. maximum file size, file path, and file extension.
requestValidate()
Validates the request, e.g. whether file type is supported or whether the file size is too large.
saveFile()
Saves the file request stream to a file system such as a database or a remote server.
deleteFile()
Removes a file from the server side. The deleteFile() method also cancels an uploaded file from the browser side.
retrieveFile()
Retrieves a file from the server side.
OnRequestExpired()
A timeout value can be configured for a file handler. If the time that is required to process a file upload request exceeds the timeout value, the onRequestExpired() method is called to drop the file upload request. The uploaded file is then removed, and an error message is displayed on the browser.
updateContext()
Updates the processor or session context when a file upload request is complete. Subsequent file upload request operations can access the updated context to retrieve data.
getFileInfo()
This method aligns with the UI widget customization. This method returns a JSON object that is processed for the reply message of the file upload request.
The FileuploadServlet class receives file upload requests, and then it uses back end operations that process the request. The file upload servlet must be configured in the btt.xml file.
Example file upload servlet configuration
<servlet> <display-name>FileUploadServlet</display-name> <servlet-name>FileUploadServlet</servlet-name> <servlet-class>com.ibm.btt.cs.ajax.FileUploadServlet</servlet-class> <init-param> <!-- request timeout check duration, in milli-seconds, default value is 20*60*1000 --> <param-name>checkDuration</param-name> <param-value>2000</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>FileUploadServlet</servlet-name> <url-pattern>/FileUploadServlet</url-pattern> </servlet-mapping>
In this example, the checkDuration parameter is specified. The checkDuration parameter specifies the length of time that is required for the file upload servlet to check the file upload request. If, at run time, the length of time that it takes for the file upload servlet to check the request is longer than the value that is specified in the checkDuration parameter, the file upload request times out. The value of the checkDuration parameter can be changed according to the operation environment.
File upload data is contained in an operation context or a session context to enable other operations to access the file when the file upload request is complete.
File upload data must contain the following three elements:
▪ An ID: The identifier is required to retrieve the file upload data. In this example, the ID of the file upload data is specified in the kColl tag as userImgs. The ID is the default dataName of the FileUpload widget to which the data is bound.
▪ A field to store file info, operation can access file info to retrieve file. e.g. in the below sample it use a refData file to save file info. File handler will know how to write and read the file info.
▪ There must be a field named handler, the value is the handler IDthat is defined in the btt.xml file.
Note that when an alpha developer creates a file handler and configures a FileUpload widget that is associated with the file handler, the structure of the file upload data must be the same as the structure of the file handler.
Note The file upload data definition must align with specific file handlers. E.g. in the sampleFileHandler class, it will need to get file info by key “file”, and update file into two field: fileId and name.
Example file upload data
<!-- data for a file uplaod --> <!-- a file info with name 'file' is mandatory, fileId field is mandatory developers can add more other file info here --> <kColl id="file"> <field id="name" /> <field id="size" /> <field id="fileId" /> </kColl> <kColl id="userImgs"> <!-- latest upload file, this item is mandatory --> <refDatarefId="file" /> <!-- if there more than one file is uploaded, information of the other uploaded files is added to the receivedFiles area --> <iColl id="receivedFiles"> <refDatarefId="file" /> </iColl> <!-- The file handler that handles the file upload request. This field mandatory --> <field id="handler" value="sampleFileHandler" /> </kColl>
Lifecycle of an AJAX file upload request made in a application
The following list describes how an AJAX request is processed in a application.
1 A file upload request is made by a user and is then sent from the browser to the server side. The file upload request contains the following information: the current processor ID, session ID and file upload data ID.
2 The FileuploadServlet class receives the request and assigns a thread to process the request. The FileuploadServlet class also assembles the resources that are required to process the file upload request, and then it delegates the service() method to the thread.
3 The thread processes the service() method, handles the file upload request, creates a new channel driver, channel request/response messages and a channel context.
4 The Channel driver initializes the channel context, parses file upload request data, and updates the channel context data.
5 The AjaxHtmlRequestHandler checks whether the request is a duplicated request, updates the channel context, and loads the file upload operation. The file upload operation retrieves the file upload data by using the ID of the file upload data, find the real file handler implClass, then load the file handler and then leverage file handler to finish the real file upload work
▪ File handler initializes parameters based on file upload request data.
▪ Validates the file upload request, e.g check file size limitation or extension, it depends on the real implementation.
▪ Saves the file stream to proper storage. E.g file system or database.
▪ Updates data in the processor context so that the file can be accessed later.
6 The AjaxHtmlPresentationHandler sends the response message to the FileuploadServlet class, then routes the response to the client browser.
