Amazon S3 File Uploader

In Amazon’s own words, “Amazon S3 provides a simple web services interface that can be used to store and retrieve any amount of data, at any time, from anywhere on the web.” Morfik’s Amazon S3 package is designed to make working with Amazon’s S3 service as simple as possible, allowing you to take advantage of this service in your application without worrying about all the details involved. If you are not already registered with Amazon S3, you can do so here: www.aws.amazon.com/s3/.


package-view.png
package-down.png


Quick Start Guide

To get started, the first thing required is to add the package to your project. This can be done using the “Used Packages” command found on the Project Ribbon, or by dragging the package file onto the client area of your Project tab.


Morfik 3 Beta NOTE: - the Amazon S3 Uploader package requires the Indy library for it to compile. While in Morfik 2 the Indy library is a part of the framework, in Morfik 3 this library has been taken out and turned in to an independent package. Therefore to use the current version of this package (V 1.0) in Morfik 3, one has to install the Indy package in the target project. You can download the Indy package from here.


Functionality for this package is provided by the TS3Manager class, which first needs to be initialized with your access and secret keys (provided by Amazon). This is best done in your application’s OnStart event, which can be found in the Events panel of the project view:



FX Code

Uses
    mfk_S3Manager;
 
Procedure AmazonS3DemoXApp.XAppStart(Sender: TObject);
Var
    AccessKey : String;
    SecretKey : String;
Begin
    AccessKey := 'xxx';
    SecretKey := 'xxx';
    InitializeS3Manager(AccessKey, SecretKey);
End;


Once this has been done, your application can now make use of the S3Manager’s methods. The following server side code shows how a web method can be used to create a new bucket:


FX Code

Unit NewBucket;
 
Interface
 
Type
NewBucket = Class(WebMethod)
    BucketName   : String;
    BucketResult : String;
  Private
    { Private declarations }
  Public
    { Public declarations }
    Procedure Execute; override;
End;
 
Implementation
 
Uses
    mfk_S3Manager;
 
Procedure NewBucket.Execute;
Begin
    If S3Manager.CreateBucket(BucketName) Then
       BucketResult := BucketName + ' successfully created!'
    Else
       BucketResult := S3Manager.ErrorMessage;
End;

Amazon S3 Uploader widget

The Amazon S3 Uploader widget provides an easy method for uploading files to Amazon S3 Buckets. All that is required is for the S3Manager to be initialized (as outlined above), and a bucket name to be provided.

Published Properties:

  • ACLOption – This is an enumerated type that controls the Access Control Policy of the file being uploaded. The available options and their meanings are listed below:
  1. private – Owner gets FULL_CONTROL.
  2. public-read – Owner gets FULL_CONTROL and the anonymous principal is granted READ access. If this policy is used on an object, it can be read from a browser with no authentication.
  3. public-read-write – Owner gets FULL_CONTROL, and the anonymous principal is granted READ and WRITE access.
  4. authenticated-read – Owner gets FULL_CONTROL, and any principal authenticated as a registered Amazon S3 user is granted READ access.
  5. bucket-owner-read – Object Owner gets FULL_CONTROL, and Bucket Owner gets READ access. This ACL applies only to objects and is equivalent to ‘private’ when used with PUT Bucket. You use this ACL to let someone other than the bucket owner write content (get full control) in the bucket but still grant the bucket owner read access to the objects.
  6. bucket-owner-full-control – Object Owner gets FULL_CONTROL, and Bucket Owner gets FULL_CONTROL. This ACL applies only to objects and is equivalent to private when used with PUT Bucket. You use this ACL to let someone other than the Bucket Owner write content (get full control) in the bucket but still grant the Bucket Owner full rights over the objects.
  • BucketName – This is the name of the bucket to which you can upload
  • KeyNamePrefix – This is a prefix for the file to be uploaded. This can also be used to specify subfolder names using the forward slash “/” character.
  • MaxFileSizeKB – This is the maximum file size, in KB, that you allow to be uploaded.
  • ShowSubmitButton – This controls whether or not the uploader’s submit button is visible.

Published Events:

OnUploadComplete – This is a browser event that is triggered once the upload has completed. This provides an opportunity to notify the user of the upload’s success. The code below shows how this can be done:



FX Code

Procedure Index.mfk_S3Uploader1UploadComplete(Sender: TObject);
Begin
    If mfk_S3Uploader(Sender).UploadSuccess Then
       ShowMessage('Upload Complete!')
    Else
       ShowMessage(mfk_S3Uploader(Sender).UploadMessage);
End;

Extending/Overriding the Uploader’s default behavior

When a file is uploaded using the Amazon S3 Uploader widget, the application’s OnBeforeUploadFinalize event is triggered. This event provides access to the upload data before finalization (in this case, posting to the S3 server) and can be used to either extend or override the server-side’s default behavior for the file.

Since there is no per-instance server side handling of events for the Uploader, it is often necessary to add extra information to the data you are uploading. Below is the code required to do this, and how it can be used to control what happens to the file:



FX Code

Procedure Index.btnUploadClick(Event: TDOMEvent);
Begin
    mfk_S3Uploader1.AddParam('SaveToFile', 'True');
    mfk_S3Uploader1.SubmitFile;
End;
 
Uses
    SystemServerFileUpload,
    mfk_S3Manager;
 
Procedure AmazonS3DemoXApp.XAppBeforeUploadFinalize(UploadData: TUploadData;
          Response: THTTPResponse; Var DoProceed: Boolean);
Begin
    If UploadData['SaveToFile'] = 'True' Then
    Begin
        DoProceed := False;
        UploadData.DataStream.SaveToFile(UploadData[cFileUploadNameParam]);
    End;
End;


See Also

Back to top