Amazon S3 Plugin

  • Tags : utility
  • Latest : 0.8.2
  • Last Updated: 24 March 2010
  • Grails version : *
  • Authors : Cantina Consulting, Refactor
7 votes
Dependency :
compile ":amazon-s3:0.8.2"

Documentation

Summary

Description

Amazon S3 Grails Plugin

This plugin is written for the Grails web application framework, and intends to make it relatively easy to host files such as images, Flash, movies and audio all on the Amazon Web Services Simple Storage Service (S3). The goals of this plugin are as follows:

  • Host and manage file assets on Amazon S3 for storage and performance advantages
  • Provide easy mechanisms to reference S3-hosted assets in Grails applications
  • Make most efficient and cost-effective use of S3 hosting resources
To achieve these goals, the plugin provides services to manage static media assets for a Grails application. For the first revision of the plugin, the focus is on managing user uploaded static content. Later revisions will place a focus on providing tools to migrate existing static content in a site (such as items under the /images folder) into S3.

This plugin uses the excellent JetS3t Toolkit (http://jets3t.s3.amazonaws.com/index.html) to communicate with the Amazon S3 service.

Author: Cantina Consulting, with additions from Refactor

Features

The initial revision of the plugin focuses on managing user uploaded content. As such it provides these features:

  • Grails Service artifact that provides synchronous and asynchronous (background) upload of assets to S3
  • Utilizes the jets3t Java S3 library for efficient upload to S3

Requirements

This plugin depends on Quartz

Installation

Latest released version depends on Quartz and will run on Grails 1.1 and above. To install:

grails install-plugin quartz
grails install-plugin amazon-s3

Contributing

Latest development version can be found at:

http://svn.codehaus.org/grails-plugins/grails-amazon-s3/trunk

Grails plugin component in JIRA can be found here:

http://jira.codehaus.org/browse/GRAILSPLUGINS/component/13788

Usage

The plugin makes use of whatever datasource the application has defined for database access, as all assets entered into the system are managed using a domain class called S3Asset.

You can use the various fields on S3Asset to override the defaults e.g. key and bucket.

The options map provides additional configuration:

KeyDescription
addAsyncupload this asset asynchronously
deleteAsyncdelete this asset asynchronously
removeLocalOnPutdelete the local file once uploaded
removeLocalOnDeletedelete the local file after deleting from S3
accessKeythe access key to use when uploading
secretKeythe secret key to use when uploading (encrypted when stored in db)
aclthe S3 ACL to apply to the asset. Use one of the constants from org.jets3t.service.acl.AccessControlList

You create an asset and provide the content and the plugin will generate a unique key.

You can then use S3AssetService to put and delete assets from S3.

S3BucketService can be used to get the actual bucket name on S3 for an asset (the bucket name is prefixed with the access key to keep it unique by default but it can be disabled) and to also completely delete a bucket and all objects inside it.

The plugin also requires specific configuration information to be able to connect to the Amazon S3 service. This configuration should appear in your application's Config.groovy file. An example of this configuration is given below:

aws {
domain="s3.amazonaws.com"
accessKey="0123456789ABCDEFG"
secretKey="0123456789ABCDEFGHIJKLMNOPQRS"
bucketName="files"
}

Since version 0.6.3, you are able to specify the access keys and bucket on a per asset basis

def a = new S3Asset()
a.options.accessKey = <somekey>
a.options.secretKey = <somekey>
a.bucket = <some custom bucket>

You can also specify the S3 ACL (access control list) to apply to the file. It is a string matching one of the constants from the AccessControlList that is provided by the jets3t library

def a = new S3Asset(file, [acl: 'REST_CANNED_PRIVATE'])

or

def a = new S3Asset()
a.options.acl = "REST_CANNED_PRIVATE"
a.optionList << new S3AssetOption(name: "acl", value: "REST_CANNED_PRIVATE", asset: a)

You can also specify whether or not you want uploading/deleting in synchronous or asynchronous (background) mode

def a = new S3Asset()
a.options.addAsync = 'false' //Sets the uploading of assets to S3 in synchronous mode
a.options.deleteAsync = 'false //Sets the deletion of resources in S3 in synchronous mode

Configuration

A description of each of the configuration elements is given below:
KeyDescription
domainThe domain from which Amazon S3 assets will be served. This by default will be s3.amazonaws.com, unless you've created a DNS CNAME to provide a different domain for your Amazon S3 assets
accessKeyYour public API access key for AWS. This will be used is an asset specific key is not provided via the options map.
secretKeyYour private API access key for AWS. This is used with the above access key.
bucketNameThe name of the default bucket where all files should reside. The bucket can be set on an individual asset via the bucket property. Note that the plugin prefixes any given bucket name with the access key in order to avoid naming clashes (a bucket name must be unique across all S3 users)
localAssetPathA directory that the util controller will store it's uploads in
timeoutthe timeout of the quartz jobs used to upload/delete resources (see quartz plugin doc for an explanation). Default is 5 seconds. Jobs will not run concurrently
startDelaythe startDelay of the quartz jobs used to upload/delete resources (see quartz plugin doc for an explanation). Default is 60 seconds
lazyInitwhen set to true (the default) the connection to S3 will not be initiated until first used. This stops the connection being made during every application start
batchSizethe pluging utilised jets3t S3Multi object to upload/delete using multiple threads. This setting controls how many assets are parsed to the service at once. Default is 10
s3clientCacheSizewhen using multiple access keys, the plugin will cache a client for each one. This option sets the maxium number to cache in case of memory issues. Default is 10.
secretKeyEncryptPasswordIf a per-asset key pair is given, the secret key is encrypted in the database using this password. If not provided, a default one will be used. Be careful changing this as it will make it impossible to remove existing assets that have been encrypted using the old password.
prefixBucketWithKeya boolean option to enable/disable automatic prefixing of the bucket name with your access key too ensure it is unique

Licensing

This plugin is open source and is licensed under the Apache License, version 2.0 (http://www.apache.org/licenses/LICENSE-2.0).

Feedback

The Grails community has been an amazing resource during our own development with the Grails framework and we welcome (and hope for) feedback from the community on the design and purpose of the plugin as well as possible usability and performance enhancements.

Please contributes bug reports and enhancements in JIRA at:

http://jira.codehaus.org/browse/GRAILSPLUGINS/component/13788