Amazon S3 File Uploader

From Morfik Wiki

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/.

View Live Demo

Download Package

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. 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;

Using mfk_S3Manager
 
Published Message Sub XAppStart(Sender As TObject)
    Dim AccessKey As String
    Dim SecretKey As String
 
    AccessKey = "xxx"
    SecretKey = "xxx"
    InitializeS3Manager(AccessKey, SecretKey)
End Sub

using mfk_S3Manager;
 
published message void XAppStart(TObject Sender)
{
    String AccessKey;
    String SecretKey;
 
    AccessKey = "xxx";
    SecretKey = "xxx";
    InitializeS3Manager(AccessKey, SecretKey);
}

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;

Public Class NewBucket
    Inherits WebMethod
    Public BucketName As String
    Public BucketResult As String
 
    Public Overrides Sub Execute
        If S3Manager().CreateBucket(BucketName) Then
            BucketResult = BucketName & " successfully created!"
        Else
            BucketResult = S3Manager().ErrorMessage
        End If
    End Sub
End Class

public class NewBucket : WebMethod
{
    public String BucketName;
    public String BucketResult;
    // Public declarations
    public override void Execute()
    {
        if (S3Manager().CreateBucket(BucketName))
            BucketResult = BucketName + " successfully created!";
        else
            BucketResult = S3Manager().ErrorMessage;
    }
}

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:

• private – Owner gets FULL_CONTROL.
• 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.
• public-read-write – Owner gets FULL_CONTROL, and the anonymous principal is granted READ and WRITE access.
• authenticated-read – Owner gets FULL_CONTROL, and any principal authenticated as a registered Amazon S3 user is granted READ access.
• 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.
• 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;

Published Message Sub mfk_S3Uploader1UploadComplete(Sender As TObject)
    If Ctype(Sender, mfk_S3Uploader).UploadSuccess Then
        ShowMessage("Upload Complete!")
    Else
        ShowMessage(Ctype(Sender, mfk_S3Uploader).UploadMessage)
    End If
End Sub

published message void mfk_S3Uploader1UploadComplete(TObject Sender)
{
    if ((mfk_S3Uploader)(Sender).UploadSuccess)
        ShowMessage("Upload Complete!");
    else
        ShowMessage((mfk_S3Uploader)(Sender).UploadMessage);
}

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;

Published Message Sub btnUploadClick(Event As TDOMEvent)
    mfk_S3Uploader1.AddParam("SaveToFile", "True")
    mfk_S3Uploader1.SubmitFile()
End Sub
 
Using SystemServerFileUpload
Using mfk_S3Manager
 
Published Message Sub XAppBeforeUploadFinalize(UploadData As TUploadData, Response As THttpResponse, ByRef DoProceed As Boolean)
    If UploadData("SaveToFile") = "True" Then
        DoProceed = False
        UploadData.DataStream.SaveToFile(UploadData(cFileUploadNameParam))
    End If
End Sub

published message void btnUploadClick(TDOMEvent Event)
{
    mfk_S3Uploader1.AddParam("SaveToFile", "True");
    mfk_S3Uploader1.SubmitFile();
}
 
using SystemServerFileUpload;
using mfk_S3Manager;
 
published message void XAppBeforeUploadFinalize(TUploadData UploadData, THttpResponse Response, ref Boolean DoProceed)
{
    if (UploadData["SaveToFile"] == "True")
    {
        DoProceed = False;
        UploadData.DataStream.SaveToFile(UploadData[cFileUploadNameParam]);
    }
}

See Also

• Add-on Packages
• Creating Packages
• Widget writing in details