File Upload Builder

File Upload Builder

In this topic ...

Quick Tips
Specifying Inputs
Enabling and Configuring Upload
Create a Dynamic Upload Path
Related Topics ...

Overview: Creating Forms

The File Upload Builder allows the user to copy files from their client computer to a specific directory on the machine hosting the Factory servlet. To support this functionality, the File Upload Builder creates a page control that is used for selecting and uploading a file to the server. The HTML control created is of the form: <input type="FILE"/>
For an HTML page which has a control such as <span name="uploadit" /> or pre-existing <input name="uploadit"/> , we can apply this Builder to that control, and the necessary attributes of that control will be set for File Upload. The parent form will have its encoding type set appropriately for File Upload and the form method will be set to type "POST".
The Factory must have File Upload functionality enabled via a property setting. (Click here for more information.)

Quick Tips

This control must exist within a <form> element on the page.
You should post such elements with an <input type="submit"> button. For example, if using the Button Builder to enable form submission, select "form submission to a model action", not "link to a model action" for the button Builder call's Action Type value.
We can use this Builder to provide models with upload functionality. (This Builder cannot be used in JSR 168 portlets or vendor-proprietary portlets unless otherwise specified in your portal-specific documentation.)

Specifying Values in the Builder Dialog

The File Upload Builder takes the inputs described in the table below. For help on inputs common to many or all Builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor."

Input name Description
Name Enter a name for this builder call. The designer tool displays this name in the builder call list.
Page Location Use the Page Location input to specify the page or pages on which this Builder call will act.
See "Locating Control Builders on Pages" for detailed documentation about the Page Location input and page location syntax.
Subfolder (Optional) Specify a subfolder (of the Factory configured upload folder) to store the uploaded file in.
Setting this optional subfolder in this Builder sets it for the entire form being submitted. If you have multiple File Upload controls in a single html page/form, they must all use the same subfolder, since the subfolder to save to is saved once for the entire page/form.
If we need to save different types of files to different subfolders, do so using multiple html pages/forms.
Process Upload Errors When you enable this check box, all exceptions are caught, stored in the request in an attribute (bowstreet.fileUploadException), and processing will continue to the webApp.
This allows you to look for an exception in the request in the action that is about to run.

Using the File Upload Builder

When the page is submitted, the following occurs:

The Builder checks for the maximum file size.
The file is uploaded in the directory specified in the Builder's "subfolder" input, provided that the file does not have the same name as a previously saved file in the directory.
The file is saved with the name specified.
The Builder verifies whether a pre-existing file with the same name should be overwritten.

Enabling and Configuring Upload

Before we can use the File Upload Builder, enable file uploading. You must restart the Factory servlet on each computer in the cluster for the change to take effect on that computer.
When you edit the following in Server Administrator, you must restart the Factory servlet. In a cluster, make the change on the administration server and restart the Factory servlets in the cluster. For more information, refer to the online help for Server Administrator.

Locate the .../WEB-INF/config/cluster.properties file.
In this file locate the following section:

# [ bowstreet.upload ]
# File Upload Settings
# This determines whether file upload is active for this server.
bowstreet.upload.enabled=
# This sets the directory where uploaded files will be stored upon successful upload.
bowstreet.upload.destinationPath=${bowstreet.rootDirectory}/upload
# This determines the maximum file size that can be uploaded at one time in KiloBytes.
bowstreet.upload.maxFileSizeK=500

Enable File Upload - Set the value of bowstreet.upload.enabled= to true.
Upload Destination Path - Set this property to the location in the Factory servlet file system where the uploaded file will be temporarily stored.
Upload Maximum File Size (KB) - This option puts a limit on how many kilobytes can be uploaded at a time (default 500 KB). If you are using multiple File Upload Builders on a page, the combined size of all files being uploaded from a single submit action must not exceed the limit specified in the Maximum File Size K field. Exceeding the upload limit will cause the upload to fail.

If you use Microsoft Internet Explorer to upload a file that is more than the maximum file size specified the Web browser interprets that as a Web page that cannot be found. As a result, you will be shown the default error message for your application server when the browser cannot find a Web page.
On the page that contains the File Upload control, you may want to include some text explaining the what the user can expect if they try to upload a file whose size is greater than the maximum file size property. There is no graceful way to handle the event (for example using an error handler method) in which a user tries to upload a file greater than the size allowed because the processing takes place within the browser, not in the Factory servlet.

Using an Indirect Reference for a Dynamic Upload Path

To create a dynamic upload path, where a user can enter a path to be used for the upload, we can build a model that provides a subfolder field. This field should be a Text Input field with an onChange event (HTML Event Action) assigned to it. This action should set the subfolder path and re-display the page. When the page is re-displayed, the subfolder value will be picked up and used during the upload operation. Add a validity check to the input field to insure than no illegal characters are included in the path entry
The method com.bowstreet.webapp.util.FileUpload.allowFileUpload is used to set the subfolder.

Input name	Description
Name	Enter a name for this builder call. The designer tool displays this name in the builder call list.
Page Location	Use the Page Location input to specify the page or pages on which this Builder call will act. See "Locating Control Builders on Pages" for detailed documentation about the Page Location input and page location syntax.
Subfolder	(Optional) Specify a subfolder (of the Factory configured upload folder) to store the uploaded file in. Setting this optional subfolder in this Builder sets it for the entire form being submitted. If you have multiple File Upload controls in a single html page/form, they must all use the same subfolder, since the subfolder to save to is saved once for the entire page/form. If we need to save different types of files to different subfolders, do so using multiple html pages/forms.
Process Upload Errors	When you enable this check box, all exceptions are caught, stored in the request in an attribute (bowstreet.fileUploadException), and processing will continue to the webApp. This allows you to look for an exception in the request in the action that is about to run.