Back to home page.
How to Use the FileUpload Component
Mark Basler
Status: In Early Access
The
in-screen-fileupload component consists of a form that is uploaded in
the background using AJAX through the Dojo libraries. The
contents of the
in-screen-fileupload form is configured through the body of the
JSF
tag.
The tag library for the fileupload component can be accessed using the
declaration
<%@taglib prefix="ui" uri="http://java.sun.com/blueprints/ui"
%>.
An example of the JSF fileupload component's use is as follows:
<ui:fileUploadTag id="TestFileuploadForm0" retFunction="testRetFunction" retMimeType="text/xml"
postProcessingMethod="#{FileUploadProcessing.postProcessingMethod}"
progressBarDivId="progress" progressBarSubmitId="submit1x" progressBarSize="40">
<input type="file" size="40" name="fileToUpload0" id="fileToUpload0Id"/><br>
<input type="file" size="40" name="fileToUpload1" id="fileToUpload1Id"/><br>
<input type="file" size="40" name="fileToUpload2" id="fileToUpload2Id"/><br>
<input type="submit" name="submit1x" value="Submit"/>
<div id="progress"></div><br/>
</ui:fileUploadTag>
Above, the component tag name is "fileUploadTag", that has the
following
attributes added to a traditional HTML form component's attributes:
- id - The required attribute is used to associate the components
related functions.
- serverLocationDir - This optional attribute is used to reset the
default storage directory to the specified fully qualified
directory. The directory has to exist and be writable by the
application. The default file up load directory is the domain's
lib directory under "upload" (will be created automatically), for
example, if you installed your appserver at c:\glassfish and deployed
your application to "domain1", the default upload directory would be
c:\glassfish\domains\domain1\lib\upload.
- retFunction - This optional attribute contains a return
JavaScript function name that will be called when the AJAX call
returns. The signature of the return function is "functionName(type, data, evt)" and
is consistent with the dojo.bind function "handle" attribute. If
this attribute is not populated, a default JavaScript function will be
called that will display the return statistics. The default
return XML data accessible from the "data" parameter is in the
following format.
<response>
<message>File Upload has Completed Successfully!</message>
<status>COMPLETED</status>
<duration>188</duration>
<duration_string>0.188 seconds </duration_string>
<start_date>Wed Jan 25 12:21:58 PST 2006</start_date>
<end_date>Wed Jan 25 12:21:58 PST 2006</end_date>
<upload_size>67817</upload_size>
</response>
- retMimeType - This optional attribute specifies the return Mime
type of the AJAX call. The default value is "text/xml".
- postProcessingMethod - This optional attribute can invoke post
processing through a deferred method that resides in a JSF backing
bean. This allows the developer to execute custom functionality
after the file(s)/data has been uploaded. The signature of the
method is void(javax.faces.event.PhaseEvent, java.util.HashMap,
com.sun.javaee.blueprints.components.ui.fileupload.FileUploadStatus).
The method can elect to send a custom response but calling the instance
method,
com.sun.javaee.blueprints.components.ui.fileupload.FileUploadStatus.enableCustomReturn().
If this boolean flag isn't set then the default response will be sent.
- progressBarDivId - This optional attribute triggers a progress
bar to be displayed in the HTML div tag with the "id" name
corresponding to this attributes value. The div will be located
by using the document.getElementById function, so it must be
unique.
- progressBarSubmitId - This optional attribute is the "id" of the
submit button that submits the AJAX form. The Javascript
functions will enable and disable the button if the "id" is
entered. This attribute is only relevant when the
"progressBarDivId" is present.
- progressBarSize - This optional attribute is the size of the
progress bar, the default is set to 40. This number is multiplied
by 10 and used as the progress bar size in pixels. This attribute
is only relevant when the "progressBarDivId" is present.
The FileUpload JSF component utilized Dojo and Apache Commons
Fileupload & IO third party libraries to provide JavaScript
and Multi-part Mime parsing functionality. A
com.sun.javaee.blueprints.components.ui.fileupload.FileUploadStatus
instance is placed in the user's session once the file upload starts
under the key "fileuploadStatus". It holds the current and
completed status of the form being uploaded.
NOTE: The fileUploadTag must have the "enctype" attribute set to
"multipart/form-data" to upload files.
Back to home page.
© Sun Microsystems 2006. All of the material in The
Java BluePrints Solutions Catalog is copyright-protected
and may not be published in other works without express
written permission from Sun Microsystems.