AWS SDK for Android Documentation

stickscarpenterMobile - Wireless

Jul 19, 2012 (4 years and 10 months ago)

773 views

AWS SDK for Android
Documentation
Getting Started Guide
AWS SDK for Android Documentation: Getting Started Guide
Copyright © 2012 Amazon Web Services LLC or its affiliates. All rights reserved.
The following are trademarks or registered trademarks of Amazon: Amazon, Amazon.com, Amazon.com
Design, Amazon DevPay, Amazon EC2, Amazon Web Services Design, AWS, CloudFront, EC2, Elastic
Compute Cloud, Kindle, and Mechanical Turk. In addition, Amazon.com graphics, logos, page headers,
button icons, scripts, and service names are trademarks, or trade dress of Amazon in the U.S. and/or other
countries. Amazon's trademarks and trade dress may not be used in connection with any product or service
that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner
that disparages or discredits Amazon.
All other trademarks not owned by Amazon are the property of their respective owners, who may or may
not be affiliated with, connected to, or sponsored by Amazon.
AWS SDK for Android Documentation Getting Started
Guide
Getting Started with the AWS SDK for Android......................................................................................1
3
AWS SDK for Android Documentation Getting Started
Guide
Getting Started with the AWS SDK
for Android
The AWS SDK for Android provides libraries, code samples, and documentation for developers to build
connected mobile applications using AWS.This guide walks through the steps for setting up the SDK
and running the code samples.
About the SDK
The AWS SDK for Android includes:
• Class libraries. Build Android applications on top of class libraries that hide much of the lower-level
plumbing of the web service interface, including authentication, request retries, and error handling.
Each service has its own library, so you can include class libraries for only the services you need and
keep your application as small as possible.
• Code samples. Practical examples of using the class libraries to build applications.
• Documentation. Reference documentation of AWS SDK for Android API.
Get Set Up
Get Your Credentials
If you haven't already signed up for Amazon Web Services, you will need to do that first to get your AWS
credentials.Then you can set up your environment.Sign In or Create an AWS Account.
To get your AWS Access Key ID and Secret Access Key
1.Go to the AWS Account page, then click Security Credentials. If you are prompted to log in, do so.
2.To see your AWS Access Key ID, scroll down to Access Credentials and ensure that the Access
Keys tab is selected.
3.To view your Secret Access Key, click Show.
1
AWS SDK for Android Documentation Getting Started
Guide
About the SDK
Important
Your Secret Access Key should be known only to you and AWS. Store it in a safe place. Never
include it in your requests to AWS, and never email it to anyone. Do not share it outside your
organization, even if an inquiry appears to come from AWS or Amazon.com. No one who
legitimately represents Amazon will ever ask you for your Secret Access Key.
Get the Android SDK
Minimum requirements for using the AWS SDK for Android are:
• Android 2.1 (API Level 7) or higher. For more information on the Android SDK, see
http://developer.android.com/index.html.
• To run the code examples, you also need the Android Development Tools
Download the SDK from http://aws.amazon.com/sdkforandroid.The SDK is stored in a compressed file
named aws-android-sdk.zip.The zip file contains the following:
•/documentation folder. Contains the documentation in JavaDoc format.
•/lib folder. Contains Java archive files (.jar) that include AWS class libraries.To manage the size of
your application, you can include only the files that you need for the services your application is using.
The .jar files can also help you with debugging your application.The following files are included:
• aws-android-sdk-VERSION.jar. Contains all necessary files (including third-party dependencies)
for all supported AWS services. All class files were compiled without the debug option.
• aws-android-sdk-VERSION-autoscaling.jar. Contains the classes necessary to use Auto Scaling.
Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled without
debug.
• aws-android-sdk-VERSION-cloudwatch.jar. Contains the classes necessary to use Amazon
CloudWatch. Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled
without debug.
• aws-android-sdk-VERSION-core.jar. Contains all third-party dependencies and the base platform
used to send and process requests to AWS services. All services were built using these classes.
The classes were compiled without debug.
• aws-android-sdk-VERSION-ddb.jar. Contains all the classes necessary to use Amazon DynamoDB.
Must be used with aws-android-sdk-VERSION-core.jar file. All classes were compiled without debug.
• aws-android-sdk-VERSION-ddb-mapper.jar. Contains all the classes necessary to use the Amazon
DynamoDB Object Mapper. Must be used with aws-android-sdk-VERSION-core.jar and
aws-android-sdk-VERSION-ddb.jar files and only with Android API levels 8 and up (Android 2.2 or
later). All classes were compiled without debug.
• aws-android-sdk-VERSION-ddb-mapper-debug.jar. Contains all the classes necessary to use the
Amazon DynamoDB Object Mapper. Must be used with the aws-android-sdk-VERSION-debug.jar
file and only with Android API levels 8 and up (Android 2.2 or later).The code was compiled with the
debug option on with all symbols retained.
• aws-android-sdk-VERSION-debug.jar. Contains all files (including third-party dependencies)
necessary for debugging.The code was compiled with the debug option on with all symbols retained.
• aws-android-sdk-VERSION-ec2.jar. Contains the classes necessary to use Amazon Elastic Compute
Cloud (EC2). Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were without
debug.
• aws-android-sdk-VERSION-elb.jar. Contains the classes necessary to use Amazon Elastic Load
Balancing. Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled
without debug.
• aws-android-sdk-VERSION-s3.jar. Contains the classes necessary to use Amazon S3. Must be
used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled without debug.
2
AWS SDK for Android Documentation Getting Started
Guide
Get the Android SDK
• aws-android-sdk-VERSION-sdb.jar. Contains the classes necessary to use Amazon SimpleDB.
Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were compiled without
debug.
• aws-android-sdk-VERSION-ses.jar. Contains the classes necessary to use Amazon Simple Email
Service (SES). Must be used with the aws-android-sdk-VERSION-core.jar file. All classes were
compiled without debug.
• aws-android-sdk-VERSION-sns.jar. Contains the classes necessary to use the Amazon Simple
Notification Service (SNS). Must be used with the aws-android-sdk-VERSION-core.jar file. All classes
were compiled without debug.
• aws-android-sdk-VERSION-sqs.jar. Contains the classes necessary to use the Amazon Simple
Queue Service (SQS). Must be used with the aws-android-sdk-VERSION-core.jar file. All classes
were compiled without debug.
• aws-android-sdk-VERSION-sts.jar. Contains the classes necessary to use the Amazon Security
Token Service (STS). Must be used with the aws-android-sdk-VERSION-core.jar file. All classes
were compiled without debug.
•/samples folder. Contains code built using the aws-android-sdk-VERSION-debug.jar library. Samples
are named based on the services they demonstrate.
•/src folder. Contains the original source files for the class libraries.
•/third-party folder. Contains the individual .jar files and licenses for the third-party packages that the
SDK depends on.
About the Demos
The /samples folder in the SDK contains a number of demo applications, including three demos in
directories named S3_SimpleDB_SNS_SQS_Demo, S3_SimpleDB_SNS_SQS_DemoTVM, and
S3_SimpleDB_SNS_SQS_DemoTVMIdentity. Each demo demonstrates how to make requests to AWS,
but each takes a different approach to providing credentials to AWS.
In S3_SimpleDB_SNS_SQS_Demo, you enter your AWS Access Key ID and Secret Access Key directly
into the application code.This approach will get you running quickly, but we do not recommend it in a
production application: a malicious user could use decompiling techniques to steal your AWS security
credentials.
Caution
Do not include your credentials in source code for applications outside your control, such as
mobile applications.
S3_SimpleDB_SNS_SQS_DemoTVM and S3_SimpleDB_SNS_SQS_DemoTVMIdentity demonstrate a
more secure mechanism for transferring AWS security credentials to a mobile client.These demos require
a server application, in this case the token vending machine (TVM), which is provided as a separate
download.TVM uses the AWS Security Token Service to get temporary security credentials and pass
them to the mobile application.
The TVM is available in two forms: one that supports anonymous registration, and one that requires a
user name and password to register a device and receive security tokens. As implied by their names,
S3_SimpleDB_SNS_SQS_DemoTVM uses the anonymous registration TVM, while
S3_SimpleDB_SNS_SQS_DemoTVMIdentity uses the identity registration TVM.
Important
In order to run the samples that use the token vending machine, you must first download and
install the appropriate TVMs.
3
AWS SDK for Android Documentation Getting Started
Guide
About the Demos
• For the anonymous registration TVM, go to http://aws.amazon.com/code/8872061742402990.
• For the identity registration TVM, go to http://aws.amazon.com/code/7351543942956566.
All three demos demonstrate how to access AWS from a mobile device using the following services:
• Amazon Simple Notification Service (SNS), to create, delete, and list topics.You can list all subscribers,
subscribe to a topic, and publish to a topic.
• Amazon Simple Queue Service (SQS), to create, view, delete, and send messages to a queue.
• Amazon Simple Storage Service (S3), to create and view data storage components called buckets and
their contents.
• Amazon SimpleDB, to create and view domains and create items.
Run the Demos
Important
To run the demos in Eclipse, you will need the ADT Plugin for Eclipse to create a virtual device
for running the project.To download the ADT Plugin for Eclipse, go to
http://developer.android.com/sdk/eclipse-adt.html.
Except for the way you provide your AWS credentials, the procedure for preparing each demo to run is
the same.
To prepare the samples
1.In the Eclipse environment, on the File menu, click Import.
2.In the Import wizard, select General, then Existing Projects Into Workspace.
3.Click the Browse button next to Select root directory.
4.In the Browse For Folder dialog box, navigate to the samples folder and click Open.
5.Click the checkbox for each sample you want to import into your workspace.
The procedure you follow to configure the demo for acquiring AWS credentials depends on which demo
you are preparing to run:
• For the S3_SimpleDB_SNS_SQS_Demo, you enter your access key ID and secret key directly in a
properties file.
• For the S3_SimpleDB_SNS_SQS_DemoTVM, the mobile client registers anonymously with the token
vending machine and receives a token that provides access to the services that the sample uses.
• For S3_SimpleDB_SNS_SQS_DemoTVMIdentity, the mobile client registers with the token vending
machine by providing a user name and password and then receives a token that provides access to
the services that the sample uses.
To provide your AWS credentials for the demo you are preparing, proceed directly to the corresponding
procedure.
To provide your AWS Credentials to S3_SimpleDB_SNS_SQS_Demo
1.In the Eclipse environment, open the sample project and, navigate to the
src/com.amazon.aws.demo folder, and open the AwsCredential.properties file.
4
AWS SDK for Android Documentation Getting Started
Guide
Run the Demos
2.In the file, edit the ACCESS_KEY_ID and SECRET_KEY attributes to reflect the corresponding keys
for your own AWS account, then save and close the file.
3.Build the project by selecting Project, then click Build Project.
4.Run the application by selecting Run, then click Run.
To allow anonymous registration for S3_SimpleDB_SNS_SQS_DemoTVM
1.In the Eclipse environment, open the sample project and, navigate to the
src/com.amazon.aws.demo.anonymous folder, and open the AwsCredential.properties
file.
2.In the file, edit the tokenVendingMachineURL attribute to reflect the address of your TVM
deployment.
3.Build the project by selecting Project, then click Build Project.
4.Run the application by selecting Run, then click Run.
To require a user name and password for S3_SimpleDB_SNS_SQS_DemoTVMIdentity
1.In the Eclipse environment, open the project and, navigate to the
src/com.amazon.aws.demo.identity folder, select the AwsCredential.properties file,
then click Open.
2.In the file, edit the tokenVendingMachineURL to reflect the address of your TVM deployment.
3.Edit the appName attribute to reflect the name that you gave to the mobile application when you
installed it, then save and close the file.
4.In a browser, sign in to the AWS Management Console. At the top of the AWS Management Console,
click the drop-down arrow to open a list of services. In the service list, click AWS Elastic Beanstalk.
5.On the Actions menu for your TVM application, click Edit/Load Configuration and select the
Container tab.
6.In the PARAM1 box, type the name that you gave to the mobile application.This is the same name
that you entered as the value for the appName attribute earlier. Click Apply Changes.
7.Build the project by selecting Project, then click Build Project.
8.Run the application by selecting Run, then click Run.
S3_SimpleDB_SNS_SQS_DemoTVMIdentity requires the user to register with a user name and password
before using any AWS features.
To register a user for the S3_SimpleDB_SNS_SQS_DemoTVMIdentity demo
1.In the Android Virtual Device running the S3_SimpleDB_SNS_SQS_DemoTVMIdentity demo, click
Login.
2.On the Login screen, click Register.
3.In the registration form, enter a user name and password. User names and passwords must be at
least six (6) characters long. Once you've entered them, click Register.
4.Press the back button twice to switch back to the to the S3_SimpleDB_SNS_SQS_DemoTVMIdentity
demo.
5.On the Login screen, enter the user name and password of the user you registered, then click Login.
You can now use the AWS features in the demo.
5
AWS SDK for Android Documentation Getting Started
Guide
Run the Demos
Running the Other Supplied Demos
To build and run the other provided demo applications, please refer to the supplied README for
instructions.
Where Do I Go from Here?
For more information about the AWS SDK for Android, including a complete list of supported AWS
products, go to http://aws.amazon.com/sdkforandroid.
View the SDK Reference Documentation Online
The SDK reference documentation includes the ability to browse and search across all code included
with the SDK. It provides thorough documentation, usage examples, and even the ability to browse method
source.You can find it at http://docs.amazonwebservices.com/AWSAndroidSDK/latest/javadoc/.
Other Resources
• AWS SDK for Android API Reference
• Mobile Developer Forum
• AWS SDK for Android project on GitHub
• FAQs
6
AWS SDK for Android Documentation Getting Started
Guide
Running the Other Supplied Demos