src/ceph/doc/radosgw/s3/java.rst

   1 .. _java:
   2
   3 Java S3 Examples
   4 ================
   5
   6 Setup
   7 -----
   8
   9 The following examples may require some or all of the following java
  10 classes to be imported:
  11
  12 .. code-block:: java
  13
  14         import java.io.ByteArrayInputStream;
  15         import java.io.File;
  16         import java.util.List;
  17         import com.amazonaws.auth.AWSCredentials;
  18         import com.amazonaws.auth.BasicAWSCredentials;
  19         import com.amazonaws.util.StringUtils;
  20         import com.amazonaws.services.s3.AmazonS3;
  21         import com.amazonaws.services.s3.AmazonS3Client;
  22         import com.amazonaws.services.s3.model.Bucket;
  23         import com.amazonaws.services.s3.model.CannedAccessControlList;
  24         import com.amazonaws.services.s3.model.GeneratePresignedUrlRequest;
  25         import com.amazonaws.services.s3.model.GetObjectRequest;
  26         import com.amazonaws.services.s3.model.ObjectListing;
  27         import com.amazonaws.services.s3.model.ObjectMetadata;
  28         import com.amazonaws.services.s3.model.S3ObjectSummary;
  29
  30
  31 If you are just testing the Ceph Object Storage services, consider
  32 using HTTP protocol instead of HTTPS protocol.
  33
  34 First, import the ``ClientConfiguration`` and ``Protocol`` classes.
  35
  36 .. code-block:: java
  37
  38         import com.amazonaws.ClientConfiguration;
  39         import com.amazonaws.Protocol;
  40
  41
  42 Then, define the client configuration, and add the client configuration
  43 as an argument for the S3 client.
  44
  45 .. code-block:: java
  46
  47         AWSCredentials credentials = new BasicAWSCredentials(accessKey, secretKey);
  48
  49         ClientConfiguration clientConfig = new ClientConfiguration();
  50         clientConfig.setProtocol(Protocol.HTTP);
  51
  52         AmazonS3 conn = new AmazonS3Client(credentials, clientConfig);
  53         conn.setEndpoint("endpoint.com");
  54
  55
  56 Creating a Connection
  57 ---------------------
  58
  59 This creates a connection so that you can interact with the server.
  60
  61 .. code-block:: java
  62
  63         String accessKey = "insert your access key here!";
  64         String secretKey = "insert your secret key here!";
  65
  66         AWSCredentials credentials = new BasicAWSCredentials(accessKey, secretKey);
  67         AmazonS3 conn = new AmazonS3Client(credentials);
  68         conn.setEndpoint("objects.dreamhost.com");
  69
  70
  71 Listing Owned Buckets
  72 ---------------------
  73
  74 This gets a list of Buckets that you own.
  75 This also prints out the bucket name and creation date of each bucket.
  76
  77 .. code-block:: java
  78
  79         List<Bucket> buckets = conn.listBuckets();
  80         for (Bucket bucket : buckets) {
  81                 System.out.println(bucket.getName() + "\t" +
  82                         StringUtils.fromDate(bucket.getCreationDate()));
  83         }
  84
  85 The output will look something like this::
  86
  87    mahbuckat1   2011-04-21T18:05:39.000Z
  88    mahbuckat2   2011-04-21T18:05:48.000Z
  89    mahbuckat3   2011-04-21T18:07:18.000Z
  90
  91
  92 Creating a Bucket
  93 -----------------
  94
  95 This creates a new bucket called ``my-new-bucket``
  96
  97 .. code-block:: java
  98
  99         Bucket bucket = conn.createBucket("my-new-bucket");
 100
 101
 102 Listing a Bucket's Content
 103 --------------------------
 104 This gets a list of objects in the bucket.
 105 This also prints out each object's name, the file size, and last
 106 modified date.
 107
 108 .. code-block:: java
 109
 110         ObjectListing objects = conn.listObjects(bucket.getName());
 111         do {
 112                 for (S3ObjectSummary objectSummary : objects.getObjectSummaries()) {
 113                         System.out.println(objectSummary.getKey() + "\t" +
 114                                 objectSummary.getSize() + "\t" +
 115                                 StringUtils.fromDate(objectSummary.getLastModified()));
 116                 }
 117                 objects = conn.listNextBatchOfObjects(objects);
 118         } while (objects.isTruncated());
 119
 120 The output will look something like this::
 121
 122    myphoto1.jpg 251262  2011-08-08T21:35:48.000Z
 123    myphoto2.jpg 262518  2011-08-08T21:38:01.000Z
 124
 125
 126 Deleting a Bucket
 127 -----------------
 128
 129 .. note::
 130    The Bucket must be empty! Otherwise it won't work!
 131
 132 .. code-block:: java
 133
 134         conn.deleteBucket(bucket.getName());
 135
 136
 137 Forced Delete for Non-empty Buckets
 138 -----------------------------------
 139 .. attention::
 140    not available
 141
 142
 143 Creating an Object
 144 ------------------
 145
 146 This creates a file ``hello.txt`` with the string ``"Hello World!"``
 147
 148 .. code-block:: java
 149
 150         ByteArrayInputStream input = new ByteArrayInputStream("Hello World!".getBytes());
 151         conn.putObject(bucket.getName(), "hello.txt", input, new ObjectMetadata());
 152
 153
 154 Change an Object's ACL
 155 ----------------------
 156
 157 This makes the object ``hello.txt`` to be publicly readable, and
 158 ``secret_plans.txt`` to be private.
 159
 160 .. code-block:: java
 161
 162         conn.setObjectAcl(bucket.getName(), "hello.txt", CannedAccessControlList.PublicRead);
 163         conn.setObjectAcl(bucket.getName(), "secret_plans.txt", CannedAccessControlList.Private);
 164
 165
 166 Download an Object (to a file)
 167 ------------------------------
 168
 169 This downloads the object ``perl_poetry.pdf`` and saves it in
 170 ``/home/larry/documents``
 171
 172 .. code-block:: java
 173
 174         conn.getObject(
 175                 new GetObjectRequest(bucket.getName(), "perl_poetry.pdf"),
 176                 new File("/home/larry/documents/perl_poetry.pdf")
 177         );
 178
 179
 180 Delete an Object
 181 ----------------
 182
 183 This deletes the object ``goodbye.txt``
 184
 185 .. code-block:: java
 186
 187         conn.deleteObject(bucket.getName(), "goodbye.txt");
 188
 189
 190 Generate Object Download URLs (signed and unsigned)
 191 ---------------------------------------------------
 192
 193 This generates an unsigned download URL for ``hello.txt``. This works
 194 because we made ``hello.txt`` public by setting the ACL above.
 195 This then generates a signed download URL for ``secret_plans.txt`` that
 196 will work for 1 hour. Signed download URLs will work for the time
 197 period even if the object is private (when the time period is up, the
 198 URL will stop working).
 199
 200 .. note::
 201    The java library does not have a method for generating unsigned
 202    URLs, so the example below just generates a signed URL.
 203
 204 .. code-block:: java
 205
 206         GeneratePresignedUrlRequest request = new GeneratePresignedUrlRequest(bucket.getName(), "secret_plans.txt");
 207         System.out.println(conn.generatePresignedUrl(request));
 208
 209 The output will look something like this::
 210
 211    https://my-bucket-name.objects.dreamhost.com/secret_plans.txt?Signature=XXXXXXXXXXXXXXXXXXXXXXXXXXX&Expires=1316027075&AWSAccessKeyId=XXXXXXXXXXXXXXXXXXX
 212