JetS3t Uploader

Uploader is a simple wizard-based application that S3 account holders (Service Providers) may provide to clients to allow them to upload files to S3 without requiring access to the Service Provider's S3 credentials. The Uploader accesses S3 accounts via a Gatekeeper service. The Gatekeeper is a specialised application that will only be of interest to Service Providers who use S3 for storage behind the scenes.

The Uploader is likely to be useful mainly to Service Providers. It can be customized, branded, and configured to interact with the provider's Gatekeeper service to authorize the user's uploads. All configuration is performed in the uploader.properties configuration file, such as the one available in the configs directory of the JetS3t distribution.

A demonstration version of the Uploader, which doesn't require a Gatekeeper service, is available via the Applications page.

Picture of the Uploader Demo application

Uploader offers the following capabilities:

  • Simple wizard workflow to upload files
  • Configurable limits on the number, size and type of files that can be uploaded
  • Configurable user input fields
  • Highly configurable GUI display
  • Works with Gatekeeper server-side authentication servlet
  • Basic skinning support (this is fairly primitive though)
  • Basic branding support
  • Option to generate an XML Summary document after successful uploads
  • When run as an applet, can read variables from the surrounding HTML web page via applet parameters

Gatekeeper Authorization

The Uploader communicates with a Gatekeeper service to request authorization to perform its uploads. A general description of a Gatekeeper service is documented in Gatekeeper Concepts. Uploader should work with any Gatekeeper service implemented following these guidelines, but the easiest way to provide an authorization service may be to use the Gatekeeper Servlet implementation provided with JetS3t.

To allow you to test the Uploader, the application is configured by default not to communicate with a Gatekeeper servlet. To modify the Uploader configuration to communicate with your Gatekeeper servlet:

  • Comment-out the user input field properties field.1.name=AwsAccessKey, field.2.name=AwsSecretKey and field.3.name=S3BucketName referenced in the uploader.properties file - these fields should only ever be used in the demonstration version of Uploader
  • Provider the URL to your Gatekeeper service in the gatekeeperUrl property.

Workflow Wizard

The Uploader displays a simple wizard-based user interface that allows users to step through the process of uploading files. Each step in the process displays a separate Screen - there are five in total.
The content of each screen is configurable (see GUI Configuration below).

Screen 1 - User Input Screen 2 - Choose File
Displays the User Input fields that prompt a user for information Prompts the user to choose a file to upload, by drag-and-dropping a file into a drop zone or by selecting it with a browse button.
Picture of the Uploader's first screen Picture of the Uploader's second screen
Screen 3 - Confirm Upload Screen 4 - Upload Progress
Displays the file(s) the user has selected to upload Displays the progress of a file upload, and allows a user to cancel the upload
Picture of the Uploader's third screen Picture of the Uploader's fourth screen
Screen 5 - Finished
Displays a message telling the user the upload was successful, or an error message if a fatal error occurred
Picture of the Uploader's fifth screen

Limiting Files

The Uploader can be set to limit the number, size and type of files it will accept. These settings are configured in uploader.properties

File Upload Limiting
file.maxCount How many files may be uploaded at a time
Should be a value greater than or equal to 1.
Default: 1
file.minSizeMB The minimum size of each file the Uploader will allow, in Megabytes. If set to 0, even empty files can be uploaded
Default: 0
file.maxSizeMB The maximum size of each file the Uploader will allow, in Megabytes. If set to 0, the files can be any size.
Default: 200
file.extensions If specified, only files with an extension matching one in the comma-separated list will be allowed. If this property is not set, any file type/name can be uploaded
Default: Not set

User Input Fields

The Uploader can be set to display User Input fields to the user on Screen 1. These fields can have any name, and a range of GUI elements can be used for the user to provide an answer. When the user enters information for these fields, this information is provided to the Gatekeeper service when the Uploader requests permission to perform operations.

Picture of sample Uploader User Inputs

The demonstration version of the Uploader, as available online or in the JetS3t distribution archive, includes the field names AwsAccessKey, AwsSecretKey and S3BucketName. These are "magic" field names to allow the Uploader to be run in demonstration mode, where there is no Gatekeeper service available and users are required to specify their AWS credentials and the target S3 bucket. These fields should not be used except for demonstration mode.

User Input Fields
Each field must have a unique id number which determines the order in which the fields are displayed. This id number must be from 1 to n, where n is the number of fields.
field.id.name A unique name for the field. This name is not displayed to the user and should be a single word without spaces, eg favouriteColour
Always required
field.id.type The GUI element to display for the field, one of: textarea, text, password, selection, radio
Always required
field.id.options For selection or radio fields, a comma-separated list of options the user can choose from
For example, in the image above the options setting used is One,Two,ThreeOnly required for selection or radio fields
field.id.prompt The text to display to the user for the field. This text can be HTML text containing simple text formatting, such as colour or font changes
Always required

GUI Configuration

The content of the Screens displayed in the Uploader is configurable in uploader.properties. The different screens have different display items, these are mentioned when relevant.

The Uploader allows for parameter substitution to be performed in text messages it displays. Replacement variables are used with the format ${variableName}, where variableName is any of the following items:

  • Properties in the file uploader.properties
  • User Inputs
  • Applet or stand-alone parameters
  • File constraints (from uploader.properties): maxFileSize, maxFileCount, validFileExtensions
  • Chosen file information (only available after files have been chosen): fileNameList, filesSize
Screen Display Settings
Each Screen has a unique id number which references the screen number, from 1 to 5. Screens all have a title, and images/text/tooltips for the back and next buttons - though it may not make sense to display buttons on some screens. See the sample uploader.properties file included in the configs directory of the JetS3t distributions for more information and examples.
screen.id.title Text displayed at the top of the Uploader display, may be HTML
Always required
screen.id.nextButton.text The text displayed on the Next button
Required only when the next button should be visible: Screens 1, 3
screen.id.nextButton.tooltip Tooltip text for the Next button
Required only when the next button should be visible: Screens 1, 3
screen.id.nextButton.image Path to an image icon for the Next button
Required only when the next button should be visible: Screens 1, 3
screen.id.backButton.text The text displayed on the Back button
Required only when the back button should be visible: Screens 2, 3
screen.id.backButton.tooltip Tooltip text for the Back button
Required only when the back button should be visible: Screens 2, 3
screen.id.backButton.image Path to an image icon for the Back button
Required only when the back button should be visible: Screens 2, 3
screen.2.dragDropPrompt Instructions for user to drag-drop file onto pane, or use browse button
Screen 2 only
screen.2.browseButton.text The text displayed on the file Browse button
Screen 2 only
screen.2.browseButton.tooltip Tooltip text for the file Browse button
Screen 2 only
screen.2.browseButton.image Path to an image icon for the file Browse button
Screen 2 only
screen.3.fileInformation Text with information about the file to be uploaded
Screen 3 only
screen.4.connectingMessage Message displayed while Uploader makes initial connection to S3
Screen 4 only
screen.4.hashingMessage Message displayed while Uploader hashes the upload file
Screen 4 only
screen.4.fileInformation Text with information about the file(s) being uploaded
Screen 4 only
screen.4.cancelButton.* Button properties for the Cancel Upload button: text, image, tooltip
Screen 4 only
screen.5.thankyouMessage Thankyou message to display when the upload completes successfully
Screen 5 only
screen.5.errorMessage Error message to display when an upload fails with a fatal error.
Screen 5 only

Skinning

Uploader support a fairly primitive skinning mechanism. To fully control the skinning special Java classes must be created (see documentation for SkinFactory) but there is an example implementation for HTML skinning included with Uploader. The HTML implementation is intended for when Uploader is run as an applet embedded in a Service Provider's web site, and will allow the provider to make the applet better match their web page design.

The Uploader with HTML skinning applied. The background colour is white, and the font is Verdana:
Picture of the Uploader with HTML Skinning applied

Skinning Properties
Each Screen has a unique id number which references the screen number, from 1 to 5. Screens all have a title, and images/text/tooltips for the back and next buttons - though it may not make sense to display buttons on some screens. See the sample uploader.properties file included in the configs directory of the JetS3t distributions for more information and examples.
skin.name The name of the skin implementation code package to use. This must be available in a package matching the skin.name inside org.jets3t.gui.skins.
Note: The only skin implementation included with the Uploader is called html
If this property is not set, or the value is default, no skinning is applied.
HTML Skinning Properties
Skinning properties specific to the HTML implementation
skin.html.textColor The colour of the text, in HTML-compatible format (eg "red", "#FAFAFA")
skin.html.backgroundColor The colour of the background, in HTML-compatible format (eg "red", "#FAFAFA")
skin.html.font The font to use, specified in a format compatible with the Java font class method Font.decode(fontValue) (eg "Verdana-PLAIN-15")

Branding

In addition to having configurable text content and skins, the Uploader can be branded with settings that control the application title, icon, and footer text.

Branding Properties
gui.applicationTitle The text displayed in the application's title bar, if it's running in stand-alone mode
Only applicable to stand-alone mode
gui.applicationIcon The icon displayed in the application's title bar, if it's running in stand-alone mode
Only applicable to stand-alone mode
gui.footerHtml HTML text displayed in the bottom of the Uploader's window. This would most commonly be used to contain a link to a Service Provider's website
gui.footerIcon An icon displayed in the bottom of the Uploader's window, next to the footer text

XML Summary

An XML Summary document can be created by the Uploader to describe an upload operation that has completed successfully. The XML document includes information about the files uploaded, and a full summary of the User Input field values provided by the user.

The XML Summary is turned on by setting the property applet.params in uploader.properties to true. The Uploader also requires that the Gatekeeper it uses support Transaction IDs, such that the Gatekeeper's response message will include a transactionId. This transaction ID is used as a prefix for the name for the XML summary document object uploaded to S3: transactionId.xml.

Note: If the XML Summary is turned on the Uploader will perform two series of uploads. The first series will upload the actual files, and the second will only upload the XML Summary document. This way, you can be assured that if a particular XML document exists in S3, the corresponding upload transaction was completed successfully.

Applet Parameters

When the Uploader is run as an applet it can be convenient to provide it with configuration information through the HTML page the applet is embedded in. This could allow Service Providers to include a client's name in the Uploader's text messages. The Uploader refers to the property applet.params in uploader.properties to learn which applet parameters it should expect. This property can include multiple parameter names in a comma-separated list.