(Quick Reference)

AWS SDK Plugin - Reference Documentation

Authors: Benoit Hediard

Version: 1.9.40

1 Introduction

The AWS SDK Plugin allows your Grails application to use the Amazon Web Services infrastructure services.

The aim is to provide a lightweight amazonWebService Grails service wrapper around the official AWS SDK for Java

It uses the official AWS SDK for Java which provides a Java API for AWS infrastructure services, making it even easier for developers to build applications that tap into the cost-effective, scalable, and reliable AWS cloud.

Using the SDK, developers can build solutions for Amazon Simple Storage Service (Amazon S3), Amazon Elastic Compute Cloud (Amazon EC2), Amazon SimpleDB, and more.

The Grails plugin handles :

  • convenient Grails configuration/management of all AWS API java clients for each AWS region,
  • easy access to all AWS API java clients through an amazonWebService Grails service wrapper.

Supported AWS Services

AWS clients supported by AWS SDK for Java :

  • Amazon CloudFormation
  • Amazon CloudFront
  • Amazon CloudSearch
  • Amazon CloudWatch
  • Amazon CodeDeploy
  • Amazon Cognito Identity
  • Amazon Cognito Sync
  • Amazon Config
  • Amazon DynamoDB
  • Amazon Elastic Compute Cloud (EC2)
  • Amazon Elastic MapReduce
  • Amazon Elastic Transcoder
  • Amazon ElastiCache
  • Amazon Glacier
  • Amazon Kinesis
  • Amazon Key Management Service (KMS)
  • Amazon Relational Database Service (RDS)
  • Amazon Redshift
  • Amazon Route 53
  • Amazon Simple Email Service (SES)
  • Amazon SimpleDB (SDB)
  • Amazon Simple Notification Service (SNS)
  • Amazon Simple Queue Service (SQS)
  • Amazon Simple Storage Service (S3)
  • Amazon Simple Workflow (SWF)
  • Auto Scaling
  • AWS Elastic Beanstalk
  • AWS Identity & Access Management (IAM)
  • AWS Import/Export
  • AWS OpsWorks
  • AWS Security Token Service
  • AWS Storage Gateway
  • Elastic Load Balancing

Latest releases

  • 2015-06-05 V1.9.40 : AWS SDK for Java updated to V1.9.40
  • 2015-05-26 V1.9.37.1 : cloudSearchDomain client added
  • 2015-05-22 V1.9.37 : AWS SDK for Java updated to V1.9.37
  • 2015-05-01 V1.9.33 : AWS SDK for Java updated to V1.9.33 + Cognito services abbreviation (fix #34)
  • 2015-04-08 V1.9.29 : AWS SDK for Java updated to V1.9.29
  • 2015-02-25 V1.9.22 : AWS SDK for Java updated to V1.9.22
  • 2015-02-11 V1.9.18 : AWS SDK for Java updated to V1.9.18
  • 2015-01-27 V1.9.17 : AWS SDK for Java updated to V1.9.17
  • 2015-01-09 V1.9.14 : AWS SDK for Java updated to V1.9.14
  • 2015-01-08 V1.9.13 : AWS SDK for Java updated to V1.9.13
  • 2014-12-05 V1.9.10 : AWS SDK for Java updated to V1.9.10
  • 2014-12-05 V1.9.9.1 : Fix an issue with groovy setter method selection when setting client region
  • 2014-12-05 V1.9.9 : AWS SDK for Java updated to V1.9.9
  • 2014-11-15 V1.9.6 : AWS SDK for Java updated to V1.9.6 + CodeDeploy, Config and KMS support added
  • 2014-11-12 V1.9.4 : AWS SDK for Java updated to V1.9.4
  • 2014-10-24 V1.9.2 : AWS SDK for Java updated to V1.9.2
  • 2014-10-09 V1.9.0 : AWS SDK for Java updated to V1.9.0

WARNING: Breaking change, since V1.9.0, new CloudSearch API Version 2013-01-01 are used (package com.amazonaws.services.cloudsearchbv2 instead of com.amazonaws.services.cloudsearch ). If you are using CloudSearch, please update your calls to the API.
  • 2014-10-01 V1.8.11 : AWS SDK for Java updated to V1.8.11
  • 2014-09-18 V1.8.10.2 : AWS SDK for Java updated to V1.8.10.2 (fix release)
  • 2014-09-12 V1.8.10 : AWS SDK for Java updated to V1.8.10
  • 2014-08-18 V1.8.9 : AWS SDK for Java updated to V1.8.9
  • 2014-07-14 V1.8.4 : AWS SDK for Java updated to V1.8.4 + Amazon Cognito Identity and Sync support added
  • 2014-07-03 V1.8.3 : AWS SDK for Java updated to V1.8.3
  • 2014-06-27 V1.8.2 : AWS SDK for Java updated to V1.8.2
  • 2014-06-23 V1.8.0 : AWS SDK for Java updated to V1.8.0
  • 2014-05-23 V1.7.11 : AWS SDK for Java updated to V1.7.11
  • 2014-04-28 V1.7.7 : AWS SDK for Java updated to V1.7.7
  • 2014-04-04 V1.7.5 : AWS SDK for Java updated to V1.7.5
  • 2014-03-21 V1.7.4 : AWS SDK for Java updated to V1.7.4
  • 2013-02-12 V1.7.1 : AWS SDK for Java updated to V1.7.1
  • 2013-01-11 V1.6.12 : AWS SDK for Java updated to V1.6.12 + DynamoDB mapper support added
  • 2013-01-07 V1.6.11 : AWS SDK for Java updated to V1.6.11
  • 2013-12-17 V1.6.9 : AWS SDK for Java updated to V1.6.9 + Amazon CloudTrail and Amazon Kinesis support added
  • 2013-11-27 V1.6.7 : AWS SDK for Java updated to V1.6.7
  • 2013-11-07 V1.6.4 : AWS SDK for Java updated to V1.6.4 + proxy settings added in config (thanks to pull request by Jeff Purser)
  • 2013-10-25 V1.6.3 : AWS SDK for Java updated to V1.6.3 + AmazonS3EncryptionClient added
  • 2013-10-03 V1.6.0 : AWS SDK for Java updated to V1.6.0
  • 2013-09-11 V1.5.6 : AWS SDK for Java updated to V1.5.6 + Grails 2.3.0 support
  • 2013-08-27 V1.5.5 : AWS SDK for Java updated to V1.5.5
  • 2013-07-11 V1.5.0 : AWS SDK for Java updated to V1.5.0
  • 2013-06-20 V1.4.7 : AWS SDK for Java updated to V1.4.7
  • 2013-06-06 V1.4.5 : AWS SDK for Java updated to V1.4.5 + DynamoDB V2 support by default

WARNING: Breaking change, since V1.4.5, new DynamoDB API Version 2012-08-10 are used (package com.amazonaws.services.dynamodbv2 instead of com.amazonaws.services.dynamodb ). If you are using DynamoDB, please update your calls to the API.
  • 2013-05-11 V1.4.3 : AWS SDK for Java updated to V1.4.3 + Security Token Service support added and bug fixes (thanks to pull requests by craigforster and jako512)
  • 2013-04-22 V1.4.2 : AWS SDK for Java updated to V1.4.2 (DynamoDB adds support for local secondary indexes)
  • 2013-03-19 V1.4.1 : AWS SDK for Java updated to V1.4.1 + Better endpoints management with new region utils
  • 2013-03-05 V1.3.33 : AWS SDK for Java updated to V1.3.33 + Unit tests added + refactor/bug fixes (thanks to Martin Gotink)
  • 2013-02-21 V1.3.32 : AWS SDK for Java updated to V1.3.32 + Amazon OpsWorks and Redshift support added + bug fix
  • 2013-02-05 V1.3.30 : AWS SDK for Java updated to V1.3.30 + Amazon Elastic Transcoder support added
  • 2012-12-20 V1.3.26 : AWS SDK for Java updated to V1.3.26 + S3 Resources scripts (to use with CDN Resources plugin)
  • 2012-11-12 V1.3.24 : AWS SDK for Java updated to V1.3.24 (adds support for long polling in SQS)
  • 2012-10-06 V1.3.22 : AWS SDK for Java updated to V1.3.22 + S3 transfer manager support added (for async upload/download and multiple files upload/download)
  • 2012-09-27 V1.3.21 : AWS SDK for Java updated to V1.3.21.1 + Amazon Glacier support added
  • 2012-07-04 V1.3.12 : AWS SDK for Java updated to V1.3.12
  • 2012-07-02 V1.3.11 : initial release

Bugs

To report any bug, please use the project Issues section on GitHub.

Other AWS Grails plugin

FYI, there is another great AWS Grails plugin with a different approach: its aim is to provide an easy "groovy" access to SES (through a groovy DSL) and S3 (through methods injection), based on JetS3 java lib. If you just need basic SES or S3 features, you might give it a try.

We decided to write our own AWS plugin because it did not meet our requirements as we wanted:

  1. to have a direct access to ALL AWS SDK for Java features, including ALL AWS services with custom client configuration,
  2. to only use AWS SDK for Java with a consistent way to access ALL AWS services (and not JetS3 java lib specific methods and a custom SES DSL),
  3. fast release update with 100% compatibility with AWS SDK for Java as it is just a simple lightweight wrapper around the official java clients,
  4. no need for additional DSL/methods injection, since we found the AWS SDK for Java clients pretty straightforward to use

2 Installation

Declare the plugin dependency in the BuildConfig.groovy file, as shown here:

grails.project.dependency.resolution = {
    inherits "global"
    log "info"
    repositories {
        // your repositories
    }
    dependencies {
        // Workaround to resolve dependency issue with aws-java-sdk and http-builder (dependent on httpcore:4.0)
        build 'org.apache.httpcomponents:httpcore:4.3.2'
        build 'org.apache.httpcomponents:httpclient:4.3.2'
        runtime 'org.apache.httpcomponents:httpcore:4.3.2'
        runtime 'org.apache.httpcomponents:httpclient:4.3.2'
    }
    plugins {
        // here go your plugin dependencies
        runtime ':aws-sdk:1.9.40'
    }
}

3 Configuration

Credentials

Add your AWS credentials parameters to your grails-app/conf/Config.groovy :

grails.plugin.awssdk.accessKey = {ACCESS_KEY}
grails.plugin.awssdk.secretKey = {SECRET_KEY}

If you do not provide credentials in grails-app/conf/Config.groovy , a credentials provider chain will be used that searches for credentials in this order:

  • Environment Variables - AWS_ACCESS_KEY_ID and AWS_SECRET_KEY
  • Java System Properties - aws.accessKeyId and aws.secretKey
  • Instance profile credentials delivered through the Amazon EC2 metadata service (IAM role)

For example, you can pass your credentials through VM Options:

grails run-app -Daws.accessKeyId={ACCESS_KEY} -Daws.secretKey={SECRET_KEY}

Or you can create an IAM role with custom permissions/policy and select this role when you launch your EC2 instance.

Region

The default region used is us-east-1. You might override it in your config:

grails.plugin.awssdk.region = 'eu-west-1'

Client config

If required, you can override default client configuration, which will be used each time a new client is created by amazonWebService.

grails {
    plugin {
        awssdk {
            // Amount of time to wait (in milliseconds) when initially establishing a connection before giving up and timing out.
            connectionTimeout = {CONNECTION_TIMEOUT}
            // Maximum number of allowed open HTTP connections.
            maxConnections = {MAX_CONNECTIONS}
            // Maximum number of retry attempts for failed retryable requests (ex: 5xx error responses from a service).
            maxErrorRetry = {MAX_ERROR_RETRY}
            // Protocol (HTTP or HTTPS) to use when connecting to Amazon Web Services.
            protocol = {PROTOCOL}
            // Size hints (in bytes) for the low level TCP send and receive buffers.
            socketBufferSizeHints = [{SOCKET_SEND_BUFFER _SIZE_HINT},{SOCKET_RECEIVE_BUFFER_SIZE_HINT}]
            // Amount of time to wait (in milliseconds) for data to be transfered over an established, open connection before the connection times out and is closed.
            socketTimeout = {SOCKET_TIMEOUT}
            // HTTP user agent header to send with all requests.
            userAgent = {USER_AGENT}
            // Proxy settings
            proxyDomain = {PROXY_DOMAIN}
            proxyHost = {PROXY_HOST}
            proxyPassword = {PROXY_PASSWORD}
            proxyPort = {PROXY_PORT}
            proxyUsername = {PROXY_USERNAME}
            proxyWorkstation = {PROXY_WORKSTATION}
        }
    }
}

If required, you can also override default client configuration for each service.

For example this will define specific properties for SQS and SES.

grails {
    plugin {
        awssdk {
            accessKey = {ACCESS_KEY}    // Default access key
            secretKey = {SECRET_KEY}    // Default secret key
            region = 'eu-west-1'        // Default region
            sqs {
                accessKey = {SQS_ACCESS_KEY}    // Custom access key
                secretKey = {SQS_SECRET_KEY}    // Custom secret key
                region = {SQS_REGION}           // Custom region
                connectionTimeout = {SQS_CONNECTION_TIMEOUT}  // Custom timeout
            }
            ses {
                region = 'us-east-1'    // Since SES is currently only available in this region
            }
            // Other available services
            autoScaling {}
            cloudFormation {}
            cloudFront {}
            cloudSearch {}
            cloudTrail {}
            cloudWatch {}
            codeDeploy {}
            cognitoIdentity {}
            cognitoSync {}
            config {}
            dynamoDB {}
            ec2 {}
            elasticBeanstalk {}
            elasticLoadBalancing {}
            elasticMapReduce {}
            elasticTranscoder {}
            elastiCache {}
            glacier {}
            iam {}
            importExport {}
            kms {}
            kinesis {}
            opsWorks {}
            rds {}
            redshift {}
            route53 {}
            s3 {}
            s3Encryption {}
            sdb {}
            sns {}
            sqs {}
            storagegateway {}
            sts {}
            swf {}
        }
    }
}

4 Amazon Web Service

Reference amazonWebService from any of your Grails artefacts (controllers, domain, services...) to automatically inject it.

def amazonWebService

Or get it from ctx if you want to test it in Grails console.

def amazonWebService = ctx.amazonWebService

You can then access any services directly from amazonWebService.

// Available service clients
amazonWebService.autoScaling
amazonWebService.cloudFormation
amazonWebService.cloudFront
amazonWebService.cloudSearch
amazonWebService.cloudSearchDomain
amazonWebService.cloudTrail
amazonWebService.cloudWatch
amazonWebService.codeDeploy
amazonWebService.cognitoIdentity
amazonWebService.cognitoSync
amazonWebService.config
amazonWebService.dynamoDB
amazonWebService.dynamoDBMapper
amazonWebService.ec2
amazonWebService.elasticBeanstalk
amazonWebService.elasticLoadBalancing
amazonWebService.elasticMapreduce
amazonWebService.elasticTranscoder
amazonWebService.elastiCache
amazonWebService.glacier
amazonWebService.iam
amazonWebService.importExport
amazonWebService.kinesis
amazonWebService.kms
amazonWebService.opsWorks
amazonWebService.rds
amazonWebService.redshift
amazonWebService.route53
amazonWebService.s3
amazonWebService.s3Encryption
amazonWebService.ses
amazonWebService.sdb
amazonWebService.sns
amazonWebService.sqs
amazonWebService.sqsBufferedAsync
amazonWebService.storageGateway
amazonWebService.swf
amazonWebService.transferManager

It will return an instance of Java client class extending AmazonWebServiceClient with default region endpoint (defined in our Config.groovy).

You can then call any available client methods.

To know available methods for each service clients, check the latest version of online AWS SDK Java docs

Custom region

If required, you can pass the region name, to get a client with a different region endpoint.

// Use SQS for region 'eu-west-1'
amazonWebService.getSqs('eu-west-1').sendMessage(new SendMessageRequest(queueUrl, messageBody))

Async clients

If required, you can also get asynchronous client (which return Future on each async methods).

// Get async client
amazonWebService.sqsAsync.sendMessageAsync(new SendMessageRequest(queueUrl, messageBody))
// Get async client for region 'eu-west-1'
amazonWebService.getSqsAsync('eu-west-1').sendMessageAsync(new SendMessageRequest(queueUrl, messageBody))

Exception handling

You should surround all your amazonWebService client calls around try/catch block, in order to catch AmazonServiceException or AmazonClientException.

4.1 EC2 example

Start an EC2 t1.micro instance with Amazon Linux in eu-west1.

import com.amazonaws.services.ec2.model.*

// If your default region is eu-west-1 def reservation = amazonWebService.ec2.runInstances(new RunInstancesRequest('ami-fd231b89', 1, 1).withInstanceType('t1.micro')) // Or if your default region is not eu-west-1 (this ami ID is only runnable eu-west-1) def reservation = amazonWebService.getEc2('eu-west-1').runInstances(new RunInstancesRequest('ami-fd231b89', 1, 1).withInstanceType('t1.micro'))

List all your EC2 instances.

List reservations = amazonWebService.ec2.describeInstances().reservations
reservations.each { Reservation reservation ->
    println "reservationId: ${reservation.reservationId}"
    reservation.instances.each() { Instance instance ->
        println "instanceId: ${instance.instanceId}, imageId: ${instance.imageId}, instanceType: ${instance.instanceType}"
    }

}

Stop an EC2 instance.

amazonWebService.ec2.stopInstances(new StopInstancesRequest([instanceId]))

Terminate an EC2 instance.

amazonWebService.ec2.terminateInstances(new TerminateInstancesRequest([instanceId]))

Java doc

To know available methods for EC2 client, check AmazonEC2Client Java doc

4.2 RDS example

Start a RDS instance.

import com.amazonaws.services.rds.model.*

DBInstance dbInstance = amazonWebService.rds.createDBInstance(new CreateDBInstanceRequest('mydbserver', 5, 'db.t1.micro', 'MySQL', 'admin', 'password'))

List all your RDS instances.

List dbInstances = amazonWebService.rds.describeDBInstances().DBInstances
dbInstances.each { DBInstance dbInstance ->
    println "DBInstanceIdentifier: ${dbInstance.DBInstanceIdentifier}, DBInstanceStatus: ${dbInstance.DBInstanceStatus}, engine: ${dbInstance.engine}, allocatedStorage: ${dbInstance.allocatedStorage}"

}

Snapshot a RDS instance.

amazonWebService.rds.createDBSnapshot(new CreateDBSnapshotRequest('someSnapshot', 'mydbserver'))

Terminate a RDS instance without final snapshot.

amazonWebService.rds.deleteDBInstance(new DeleteDBInstanceRequest('mydbserver').withSkipFinalSnapshot(true))

Java doc

To know available methods for RDS client, check AmazonRDSClient Java doc

4.3 S3 example

Create a bucket.

import com.amazonaws.services.s3.model.*

// Bucket will be created in default config region amazonWebService.s3.createBucket('some-grails-bucket')

List buckets.

List buckets = amazonWebService.s3.listBuckets()
buckets.each { Bucket bucket ->
    println "bucketName: ${bucket.name}, creationDate: ${bucket.creationDate}"
}

List bucket files.

ObjectListing objectListing = amazonWebService.s3.listObjects('some-grails-bucket')
objectListing.objectSummaries.each { S3ObjectSummary summary ->
    println "key: ${summary.key}, lastModified: ${summary.lastModified}, size: ${summary.size}"
}

Upload a file with public read permissions.

amazonWebService.s3.putObject(new PutObjectRequest('some-grails-bucket', 'somePath/someKey.jpg', new File('/Users/ben/Desktop/photo.jpg')).withCannedAcl(CannedAccessControlList.PublicRead))

Download a file.

amazonWebService.s3.getObject(new GetObjectRequest('some-grails-bucket', 'somePath/someKey.jpg'), new File('/Users/ben/Downloads/photo.jpg'))

Delete a file.

amazonWebService.s3.deleteObject('some-grails-bucket', 'somePath/someKey.jpg')

Transfer manager

TransferManager provides a simple API for uploading content to Amazon S3, and makes extensive use of Amazon S3 multipart uploads to achieve enhanced throughput, performance and reliability.

Upload asynchronously a file with public read permissions.

import com.amazonaws.services.s3.model.CannedAccessControlList
import com.amazonaws.services.s3.transfer.*

PutObjectRequest putObjectRequest = new PutObjectRequest('some-grails-bucket', 'somePath/someKey.jpg', new File('/Users/ben/Desktop/photo.jpg')).withCannedAcl(CannedAccessControlList.PublicRead) Upload upload = amazonWebService.transferManager.upload(putObjectRequest)

while (!upload.done) { println "Transfer: $upload.description" println " - State: $upload.state" println " - Progress: $upload.progress.bytesTransfered" // Do work while we wait for our upload to complete… Thread.sleep(500) }

Upload asynchronously multiple files from a directory.

MultipleFileUpload upload = amazonWebService.transferManager.uploadDirectory('some-grails-bucket', 'some-virtual-directory', new File('/Users/ben/Desktop/SomeDirectory'), false)

while (!upload.done) { println "Transfer: $upload.description" println " - State: $upload.state" println " - Progress: $upload.progress.bytesTransfered" // Do work while we wait for our upload to complete… Thread.sleep(500) }

Download asynchronously a file.

Download download = amazonWebService.transferManager.download(new GetObjectRequest('some-grails-bucket', 'somePath/someKey.jpg'),  new File('/Users/ben/Downloads/photo.jpg'))

while (!download.done) { println "Transfer: $download.description" println " - State: $download.state" println " - Progress: $download.progress.bytesTransfered" // Do work while we wait for our upload to complete… Thread.sleep(500) }

Download asynchronously multiple files.

MultipleFileDownload download = amazonWebService.transferManager.downloadDirectory('some-grails-bucket', 'some-virtual-directory',  new File('/Users/ben/Downloads'))

while (!download.done) { println "Transfer: $download.description" println " - State: $download.state" println " - Progress: $download.progress.bytesTransfered" // Do work while we wait for our upload to complete… Thread.sleep(500) }

Note: you might want to increase S3 connection timeout config parameter for large uploads/downloads.

Java doc

To know available methods for S3 client, check AmazonS3Client Java doc

To know available methods for S3 transfer manager, check TransferManager Java doc

4.4 SES example

SES is currently only available in some region (us-east-1, us-west-2, eu-west-1), so you might define it in your config if required or use amazonWebService.getSes('us-east-1').

Verifies an email address (send a confirmation email).

import com.amazonaws.services.simpleemail.model.*

amazonWebService.ses.verifyEmailIdentity(new VerifyEmailIdentityRequest().withEmailAddress('notification@mydomain.com'))

List verified address.

List emailAddresses = amazonWebService.ses.listVerifiedEmailAddresses().verifiedEmailAddresses
emailAddresses.each {
    println it
}

Send an email.

String source = 'notification@mydomain.com'
Destination destination = new Destination(['myemail@gmail.com'])
Content subject = new Content('Some subject...')
Body body = new Body().withHtml(new Content('''Hi,<br />
<br />
Some <b>HTML</b> body…
'''))
Message message = new Message(subject, body)
amazonWebService.ses.sendEmail(new SendEmailRequest(source, destination, message))

Get send statistics

GetSendStatisticsResult statistics = amazonWebService.ses.getSendStatistics()
statistics.sendDataPoints.each { SendDataPoint sendDataPoint ->
    println "bounces=${sendDataPoint.bounces}, complaints=${sendDataPoint.complaints}, deliveryAttempts=${sendDataPoint.deliveryAttempts}, rejects=${sendDataPoint.rejects}"
}

Get send quota

GetSendQuotaResult quota = amazonWebService.ses.getSendQuota()
println "max24HourSend: ${quota.max24HourSend}, sentLast24Hours: ${quota.sentLast24Hours}, sentLast24Hours: ${quota.sentLast24Hours}"

Java doc

To know available methods for SES client, check AmazonSimpleEmailServiceClient Java doc

4.5 SQS example

Create a queue.

import com.amazonaws.services.sqs.model.*

String queueUrl = amazonWebService.sqs.createQueue(new CreateQueueRequest('someQueue')).queueUrl

Send a message

amazonWebService.sqs.sendMessage(new SendMessageRequest(queueUrl, 'Some message...'))

Receive and delete messages

List messages = amazonWebService.sqs.receiveMessage(new ReceiveMessageRequest(queueUrl)).messages
messages.each { Message message ->
    println "id: ${message.messageId}, body: ${message.body}"
    amazonWebService.sqs.deleteMessage(new DeleteMessageRequest(queueUrl, message.receiptHandle))
}

Delete a queue.

amazonWebService.sqs.deleteQueue(new DeleteQueueRequest('someQueue'))

Java doc

To know available methods for SQS client, check AmazonSQSClient Java doc

4.6 Other services

For other services, check the Java doc :