updated S3 example topics

Author: EronHennessey

doc_source/.gitignore

@@ -0,0 +1 @@
+example_code

doc_source/examples/s3.rst

@@ -5,7 +5,9 @@
 This section provides examples of programming |S3|_ using the |sdk-java|_.
 
 .. toctree::
-    :glob:
+    :titlesonly:
+    :maxdepth: 1
 
-    s3/*
+    s3/buckets
+    s3/objects
 

doc_source/examples/s3/buckets.rst

@@ -11,6 +11,7 @@ the the |s3-dg|.
 
 .. contents::
     :local:
+    :depth: 1
 
 .. _create-bucket:
 
@@ -20,6 +21,13 @@ Create a bucket
 Use the |s3client| client's :methodname:`createBucket` method. The new :java-api:`Bucket
 <services/s3/model/Bucket>` is returned.
 
+**Imports:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/CreateBucket.java
+   :lines: 15-17
+
+**Code:**
+
 .. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/CreateBucket.java
    :lines: 43-50
    :dedent: 8
@@ -33,6 +41,13 @@ List buckets
 Use the |s3client| client's :methodname:`listBucket` method. If successful, a List of
 :java-api:`Bucket <services/s3/model/Bucket>` objects will be returned.
 
+**Imports:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/ListBuckets.java
+   :lines: 16-18
+
+**Code:**
+
 .. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/ListBuckets.java
    :lines: 31-37
    :dedent: 8
@@ -46,6 +61,13 @@ Delete a bucket
 Use the |s3client| client's :methodname:`deleteBucket` method. *The bucket must be empty, or an
 error will result*.
 
+**Imports:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java
+   :lines: 15-17
+
+**Code:**
+
 .. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteBucket.java
    :lines: 45-52
    :dedent: 8

doc_source/examples/s3/objects.rst

@@ -1,6 +1,6 @@
-############
-|S3| Objects
-############
+#####################
+Operations on Objects
+#####################
 
 An |S3| object represents a *file*, or collection of data. Every object must reside within a
 :doc:`bucket <buckets>`.
@@ -9,6 +9,8 @@ An |S3| object represents a *file*, or collection of data. Every object must res
 
 .. contents::
     :local:
+    :depth: 1
+
 
 .. _upload-object:
 
@@ -18,6 +20,13 @@ Upload an object
 Use the |s3client| client's :methodname:`putObject` method, supplying it with a bucket name, key
 name, and file to upload. *The bucket must exist, or an error will result*.
 
+**Imports:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/PutObject.java
+   :lines: 15-17
+
+**Code:**
+
 .. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/PutObject.java
    :lines: 47-54
    :dedent: 8
@@ -30,19 +39,22 @@ List objects
 To get a list of objects within a bucket, use the |s3client| client's :methodname:`listObjects`
 method, supplying it with the name of a bucket.
 
-.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/ListObjects.java
-   :lines: 46-47
-   :dedent: 8
-
 The :methodname:`listObjects` method returns an :java-api:`ObjectListing
 <services/s3/model/ObjectListing>` object that provides information about the objects in the bucket.
 To list the object names (keys), use the :methodname:`getObjectSummaries` method to get a List of
 :java-api:`S3ObjectSummary <services/s3/model/S3ObjectSummary>` objects, each of which represents a
 single object in the bucket, then call its :methodname:`getKey` method to retrieve the object's
 name.
 
+**Imports:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/ListObjects.java
+   :lines: 16-20
+
+**Code:**
+
 .. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/ListObjects.java
-   :lines: 48-52
+   :lines: 46-52
    :dedent: 8
 
 
@@ -64,11 +76,43 @@ object.
 The following example downloads an object from S3 and saves its contents to a file (using the same
 name as the object's key):
 
+**Imports:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/GetObject.java
+   :lines: 15-23
+
+**Code:**
+
 .. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/GetObject.java
    :lines: 51-75
    :dedent: 8
 
 
+.. _copy-object:
+
+Copying, moving or renaming objects
+===================================
+
+You can copy an object from one bucket to another by using the |s3client| client's
+:methodname:`copyObject` method. It takes the name of the bucket to copy from, the object to copy,
+and the destination bucket and name.
+
+**Imports:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/CopyObject.java
+   :lines: 15-17
+
+**Code:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/CopyObject.java
+   :lines: 45-54
+   :dedent: 8
+
+You can use :methodname:`copyObject` with :ref:`deleteObject <delete-object>` to **move** or
+**rename** an object, by first copying the object to a new name (you can use the same bucket as both
+the source and destination) and then deleting the object from its old location.
+
+
 .. _delete-object:
 
 Delete an object
@@ -77,7 +121,35 @@ Delete an object
 Use the |s3client| client's :methodname:`deleteObject` method, passing it the name of a bucket and
 object to delete. *The specified bucket and object key must exist, or an error will result*.
 
+**Imports:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteObject.java
+   :lines: 15-17
+
+**Code:**
+
 .. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteObject.java
    :lines: 48-55
    :dedent: 8
 
+
+.. _delete-objects:
+
+Deleting multiple objects at once
+=================================
+
+Using the |s3client| client's :methodname:`deleteObjects` method, you can delete multiple objects
+from the same bucket by passing their names to the :java-api:`DeleteObjectRequest
+<services/s3/model/DeleteObjectsRequest>` :methodname:`withKeys` method.
+
+**Imports:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteObjects.java
+   :lines: 15-18
+
+**Code:**
+
+.. literalinclude:: ../../example_code/s3/src/main/java/aws/example/s3/DeleteObjects.java
+   :lines: 53-62
+   :dedent: 8
+