JetS3t使用说明

偏执的太偏执、 2021-11-16 09:50 336阅读 0赞

**转自：[http://ywskycn.com/cloud-computing/jets3t-use.html][http_ywskycn.com_cloud-computing_jets3t-use.html]**

**最近需要使用JetS3t做一些开发工作，所以收集了一些相关的资料整理成中文。本文的pdf版本可从这里下载：[download][]。**

# 1. JetS3t简介 #

JetS3t\[1\]是一个用于与Amazon Simple Storage Service\[2\]（Amazon S3）和Amazon CloudFront\[3\]交互的Java开源工具箱。它将Amazon S3的一些API抽象成常见的Java方法和类，方便开发人员更好的与S3进行交互。JetS3t开发套件中包括5个主要的应用程序：

*  Cockpit：一个GUI工具用户传输文件，查看和管理Amazon S3帐号中的内容。
 *  Synchronize：用于同步用户计算机上的目录和Amazon S3账户的命令行工具，最适合于不同的计算机之间同步文件与备份。
 *  Gatekeeper：一个Servlet可以作为访问Amazon S3账户的中介，其它没有S3账户的客户端可以利用这个Servlet实现上传，下载，删除等操作。
 *  CockpitLite：Cockpit的简约版本，它通过中介Gatekeeper服务实现所有操作。
 *  Uploader：一个GUI应用程序，提供一个通过Gatekeeper服务实现文件上传的简单向导。

这5个应用程序都是基于JetS3t工具箱开发，展示了如何利用该工具箱做进一步的开发。JetS3t采用Apache License，Version 2.0开源协议。

# 2. 代码示例 #

本节主要介绍有关于JetS3t的简单实例代码。JetS3t依赖以下类库：

<table style="color:rgb(51,51,51); font-family:Arial; font-size:14px; line-height:26px; border:2px solid rgb(204,204,204); border-collapse:collapse; margin:5px 0px 10px"> 
 <tbody> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> Library</td> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> URL</td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> HttpClient 3.1</td> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> <a href="http://jakarta.apache.org/commons/httpclient/" style="color:rgb(41,112,166); text-decoration:none" rel="nofollow">http://jakarta.apache.org/commons/httpclient/</a></td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> Log4J</td> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> <a href="http://logging.apache.org/log4j/docs/" style="color:rgb(41,112,166); text-decoration:none" rel="nofollow">http://logging.apache.org/log4j/docs/</a></td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> Bare Bones Browser Launcher</td> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> <a href="http://www.centerkey.com/java/browser/" style="color:rgb(41,112,166); text-decoration:none" rel="nofollow">http://www.centerkey.com/java/browser/</a></td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> Nuvola Icon Library</td> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> <a href="http://icon-king.com/" style="color:rgb(41,112,166); text-decoration:none" rel="nofollow">http://icon-king.com/</a></td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> Java Uuid Generator (JUG)</td> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> <a href="http://jug.safehaus.org/Home" style="color:rgb(41,112,166); text-decoration:none" rel="nofollow">http://jug.safehaus.org/Home</a></td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> Apache Axis 1.4</td> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> <a href="http://ws.apache.org/axis/" style="color:rgb(41,112,166); text-decoration:none" rel="nofollow">http://ws.apache.org/axis/</a></td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> Bouncy Castle Crypto APIs</td> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> <a href="http://www.bouncycastle.org/" style="color:rgb(41,112,166); text-decoration:none" rel="nofollow">http://www.bouncycastle.org/</a></td> 
 </tr> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> Java XMLBuilder</td> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> <a href="http://code.google.com/p/java-xmlbuilder/" style="color:rgb(41,112,166); text-decoration:none" rel="nofollow">http://code.google.com/p/java-xmlbuilder/</a></td> 
 </tr> 
 </tbody> 
</table>

## 2.1 基本操作 ##

### 2.1.1 Connecting to S3 ###

使用JetS3t对S3进行任何操作都需要提供S3账户的awsAccessKey和awsSecretKey。有关于这两个Keys的获取如下图所示：

由于S3只有两种存储结构，Bucket和Object。相对应JetS3t中的对象为：

*  S3Bucket：S3中的Object都存在某个Bucket之中，每个Bucket在S3中都有唯一的名字。
 *  S3Object：S3的Bucket中的存储数据类型，每个Object都有一个key值。

连接到S3的实例代码如下：

为了与S3交互，需要创建一个S3Service的对象。这里采用的REST/HTTP协议，这也是JetS3t提供的最可靠的协议。

### 2.1.2 Create a Bucket ###

为了将Object存储到S3中，首先需要创建一个bucket，即创建object的容器。

因为bucket的名字是S3全局唯一的，因此这里的“test-bucket”需要换成一个与其它buckets不重复的名字。在创建bucket时可以设置location参数，用来表示希望将该bucket存储在哪个地区的数据中心，例如下面的例子就是将bucket存储在Amazon设在欧洲的数据中心。

这里可选的location有：US, US\_STANDARD, US\_WEST, 和EUROPE。

### 2.1.3 Uploading Data/Files ###

JetS3t将S3中的object封装成S3Object，因此在将数据上传到S3之前，我们需要创建一个S3Object（并用key/name标识），并通过S3Service上传到相应的bucket中。下面的代码创建了一个S3Object对象，并将上传前和上传后的对象信息打印出来。上传之后的对象会增加一些额外的信息，例如文件的最后修改时间等。

上面的代码创建了一个名为“object”的空对象。当然，如果知道数据的Content/Mime类型（例如text/plain），也可以设置object相应的数据内容。S3Object不支持从输入流直接获取数据信息，但是JetS3t提供了两类方法用来获取文件或字符串数据信息。相应的构造方法会自动的设置object的Content-Type和Content-Length的信息。

如果上传的数据既不是文件也不是字符串，那么可以通过输入流来实现数据上传，但是需要手工设置Content-Length信息。

为了确保在传输过程中不出现异常问题，我们需要检查S3接收到的数据的哈希值与本地原始文件的哈希值是否匹配。实现该机制的一个简单的方法就是在上传数据之前，设置object的Content-MD5值。当你使用File-或String-based的S3Object构造方法时，JetS3t将会自动设置Content-MD5的值。

当你使用的不是这类构造方法时，那么需要手工设置Content-MD5值。JetS3t提供相应的方法来计算一个输入流或者字节流的相应的哈希值。

### 2.1.4 Downloading Objects ###

如果只是希望了解S3账户中某个文件的一些信息（即HEAD信息），那么不需要下载整个object。这里的HEAD信息包括object的大小，时间，Content Type等等。

如果希望获取object的内容信息，可以通过下列代码实现：

同上传数据相同，如果需要判断下载过程中是否出现异常，通过检查object的哈希值即可。

### 2.1.5 Listing Your Buckets/Objects ###

通过上面的代码，我们S3的账户中现在已经有了一个bucket，并且包含了一些objects。我们可以罗列出所有bucket和object的信息。需要说明的是，罗列出的object信息要少于方法getObject和getObjectDetails返回的object信息。

当用户希望获取一个bucket中某一类对象的信息时，这种方法非常适用，因为它不需要下载所有object的内容。

### 2.1.6 Deleting Buckets/Objects ###

Object可以很容易被删除，而Bucket只有其为空时才可被删除。

### 2.1.7 Copying Objects ###

可以在Bucket内部以及不同的bucket之间实现object的拷贝。

也可以在拷贝对象的同时更新相应的metadata信息。

### 2.1.8 Moving and Renaming Objects ###

可以在同一地区的数据中心中将object从一个bucket移动到另外一个bucket中。一个文件移动操作由拷贝和删除操作组成。若拷贝操作失败，那么这个object不会被删除。但是如果最终的删除操作失效，那么这个object将会在源bucket和目的bucket中都出现。

### 2.1.9 Bucket Versioning ###

S3的bucket提供versioning特性，允许object在被更新或删除的时候保存之前的版本。这个特性也使得用户不用去担心一些重要的数据因为意外的覆盖或删除操作而丢失。在默认设置中，S3并没有开启versioning功能，需要用户手工开启该功能。而一旦开启该功能，用户可以通过唯一的版本标识来访问管理某一版本的object数据。

<table style="color:rgb(51,51,51); font-family:Arial; font-size:14px; line-height:26px; border:2px solid rgb(204,204,204); border-collapse:collapse; margin:5px 0px 10px"> 
 <tbody> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> // Create a bucket to test versioning S3Bucket versioningBucket = s3Service.getOrCreateBucket(“test-versioning”); String vBucketName = versioningBucket.getName(); // Check bucket versioning status for the bucket S3BucketVersioningStatus versioningStatus = s3Service.getBucketVersioningStatus(vBucketName); System.out.println(“Versioning enabled ? ” + versioningStatus.isVersioningEnabled()); // Suspend (disable) versioning for a bucket — will have no effect if bucket versioning is not yet // enabled. This will not delete any existing object versions. s3Service.suspendBucketVersioning(vBucketName); // Enable versioning for a bucket. s3Service.enableBucketVersioning(vBucketName); // Once versioning is enabled you can GET, PUT, copy and delete objects as normal. Every change to // an object will cause a new version to be created. // Store and update and delete an object in the versioning bucket S3Object versionedObject = new S3Object(“versioned-object”, “Initial version”); s3Service.putObject(vBucketName, versionedObject); versionedObject = new S3Object(“versioned-object”, “Second version”); s3Service.putObject(vBucketName, versionedObject); versionedObject = new S3Object(“versioned-object”, “Final version”); s3Service.putObject(vBucketName, versionedObject); </td> 
 </tr> 
 </tbody> 
</table>

如果通过普通的方法来获取一个开启了versioning功能的object，那么S3将反馈该object的最新版本的数据信息，并且用户可以查看该数据的版本ID。

如果将一个versioned的object删除，那么上面介绍的一些普通的方法将不再可用。

这时候就需要使用一些versioning-aware的方法，通过指定相应的版本ID来获取该object之前版本的信息。

列出一个bucket中所有的对象版本信息，每个结果都是一个S3Version或者S3DeleteMarker对象。

指定了前缀：

JetS3t提供了一个便利的方法来罗列某一个object的版本信息。

所有的S3操作都有相应的versioning-aware方法。

删除操作：

### 2.1.10 Multi-Factor Authenticated Delete ###

S3提供了一些额外的数据保护策略，通过multi-factor认证（MFA）实现。下面的例子就是通过MFA认证来删除object版本信息。

如果开启了MFA，那么用户必须提供相应的序列号以及认证码才能够删除object的版本信息。

如果开启了MFA，那么必须提供multi-factor相关认证信息来关闭MFA。

如果开启了MFA，那么必须提供multi-factor认证信息才能够暂停S3的versioning功能。

## 2.2 多线程操作 ##

JetS3t工具箱提供了一些工具（S3ServiceMulti和S3ServiceSimpleMulti），使得用户可以同时操作多个对象。在带宽条件允许下，这些工具可以使得用户更快的完成相应的操作。这些操作可以兼容S3Service提供的任何线程安全的操作，例如JetS3t提供的一些HTTP/REST和SOAP方法。

S3ServiceMutli专为一些有着更高需求的开发人员提供。开发人员可以在图形界面中使用S3ServiceMulti，并且它采用的是事件通知（event-notification）的交互方式，而非传统的方法调用。这也意味着用户在使用S3上传一个大文件时，可以实时监控上传的进度（Cockpit中就使用了该功能）。但是，这些功能会使得整个API变得更复杂。S3ServiceSimpleMulti提供了一个简化的接口，开发人员可以直接使用多线程，而无需额外的操作。下面的例子将描述如何使用S3ServiceSimpleMulti。

### 2.2.1 Multiple Uploads ###

首先是创建一个S3ServiceSimpleMulti对象。

为了演示多线程的上传功能，这里创建了一个bucket并将一些对象上传到其中。

<table style="color:rgb(51,51,51); font-family:Arial; font-size:14px; line-height:26px; border:2px solid rgb(204,204,204); border-collapse:collapse; margin:5px 0px 10px"> 
 <tbody> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> // First, create a bucket. S3Bucket bucket = new S3Bucket(awsAccessKey + “.TestMulti”); bucket = s3Service.createBucket(bucket); // Create an array of data objects to upload. S3Object[] objects = new S3Object[5]; objects[0] = new S3Object(bucket, “object1.txt”, “Hello from object 1″); objects[1] = new S3Object(bucket, “object2.txt”, “Hello from object 2″); objects[2] = new S3Object(bucket, “object3.txt”, “Hello from object 3″); objects[3] = new S3Object(bucket, “object4.txt”, “Hello from object 4″); objects[4] = new S3Object(bucket, “object5.txt”, “Hello from object 5″); // Upload multiple objects. S3Object[] createdObjects = simpleMulti.putObjects(bucket, objects); System.out.println(“Uploaded ” + createdObjects.length + ” objects”); // Perform a Details/HEAD query for multiple objects. S3Object[] objectsWithHeadDetails = simpleMulti.getObjectsHeads(bucket, objects); // Print out details about all the objects. System.out.println(“Objects with HEAD Details…”); for (int i = 0; i &lt; objectsWithHeadDetails.length; i++) { System.out.println(objectsWithHeadDetails[i]); } </td> 
 </tr> 
 </tbody> 
</table>

### 2.2.2 Multiple Downloads ###

JetS3t也提供了多线程的下载服务，但是在使用该功能之前，用户需要准备好这些object存放的位置。

### 2.2.3 Multiple Deletes ###

多线程的删除。

## 2.3 高级操作 ##

### 2.3.1 Managing Metadata ###

S3Object可以包含一些name/value对的metadata信息。这些metadata信息都存储在S3之中，并且可以通过getObject或getObjectDetails来查看这些信息。如果用户希望为object添加一些metadata，那么在上传object之前就应该这些好这些信息。需要注意的是这些metadata的name不能有空格。

### 2.3.2 Securing Your AWS Credentials ###

用户应该保管好自己的AWS账户信息，这些信息都是用来登录以及管理S3账户。JetS3t将这些信息保存在AWSCredentials对象中，AWSCredentials提供了一些方法将这些账户信息加密之后保存在文件中。

### 2.3.3 Access Control ###

S3使用Access Control Lists来管理buckets和objects的访问信息。在默认配置中，用户创建的任何bucket或object都属于该用户本人，也只有该用户才有权限访问。但是，用户可以通过一些设置使得一些buckets或objects能够被其他人访问。有关于这些权限可以参考Amazon的ACL协议。下列的代码展示了使用ACL协议来管理bucket或object访问权限的方法。

### 2.3.4 Temporary Public URLs ###

用户可以通过某个URL地址来访问S3中的某个object，这个URL地址是有时效的。

### 2.3.5 S3 POST Forms ###

当创建一个S3的POST form时，那么通过浏览器访问该网页的其它用户都可以上传文件到S3账户中，不需要安装任何S3的客户端软件。更多信息请参照S3 POST\[4\]相关文档。

在这里我们将创建一个不涉及任何policy的POST form，这也意味着这个form不会失效，也不会有其它的限制条件。当且仅当目标bucket开放了写权限，这个窗口才可以工作。

为了使用这个form，那么将它保存成UTF-8编码的html文件，然后通过浏览器打开即可。接下来我们将创建一系列带有约束条件的POST form，允许用户上传图像文件到一个受保护的bucket之中。上传成功后，将用户转到另外一个页面上。

需要说明的是所有的POST请求都会被强制的加上bucket和key的值。除了这两个强制的值之外，我们还可以加上一个field用来控制上传文件的大小。

<table style="color:rgb(51,51,51); font-family:Arial; font-size:14px; line-height:26px; border:2px solid rgb(204,204,204); border-collapse:collapse; margin:5px 0px 10px"> 
 <tbody> 
 <tr> 
 <td style="border:1px solid rgb(204,204,204); padding:3px 10px; vertical-align:top"> String[] conditions = { S3Service.generatePostPolicyCondition_Equality(“bucket”, bucketName), S3Service.generatePostPolicyCondition_Equality(“key”, key), S3Service.generatePostPolicyCondition_Range(10240, 204800), // Conditions to allow the additional fields specified above S3Service.generatePostPolicyCondition_Equality(“acl”, “public-read”), S3Service.generatePostPolicyCondition_Equality(“Content-Type”, “image/jpeg”), S3Service.generatePostPolicyCondition_Equality(“success_action_redirect”, “http://localhost/post_upload”) }; // Form will expire in 24 hours cal = Calendar.getInstance(); cal.add(Calendar.HOUR, 24); Date expiration = cal.getTime(); // Generate the form. String restrictedForm = S3Service.buildPostForm( bucketName, key, awsCredentials, expiration, conditions, inputFields, null, true); </td> 
 </tr> 
 </tbody> 
</table>

### 2.3.6 Activate Requester Pays for a bucket ###

在S3的默认配置中，一个bucket的所有上传下载等操作产生的费用都由这个bucket所属的用户来支付。S3的Requester Pays特性允许用户将自己的bucket配置成请求者支付模式，即请求和传输的费用由每个requester来承担。需要说明的是，只有S3的REST API支持Requester Pays，因此在编写代码时必须使用RestS3Service，而不是SoapS3Service。

### 2.3.7 Access a Requester Pays bucket ###

当一个bucket设置成Requester Pays模式时，AWS的其它用户在满足以下两个条件后就可以上传/下载该bucket中的文件：有ACL的相应权限；愿意承担相关操作的费用。通过设置标签位RequesterPaysEnabled来使用Requester Pays相关的操作。JetS3t的默认配置设置RequesterPaysEnabled为false：httpclient.requester-pays-buckets-enabled=false。

用户在操作一个Requester Pays的bucket时可以生成一个URL地址，允许第三方用户访问该bucket中的一些对象。

### 2.3.8 Amazon DevPay S3 Accounts ###

Amazon的DevPay服务允许一些代理出售user-pays的S3账户。为了访问DevPay产品中的S3账户，JetS3t需要添加一些额外的账户信息，包括DevPay User Token和DevPay Product Token。

一旦设置好这些信息，那么用户就可以直接操作DevPay账户。

同样也可以为DevPay S3账户创建一些URL地址。

--------------------

\[1\]   [http://jets3t.s3.amazonaws.com/index.html][http_jets3t.s3.amazonaws.com_index.html]

\[2\] [http://www.amazon.com/s3][http_www.amazon.com_s3]

\[3\] [http://www.amazon.com/cloudfront][http_www.amazon.com_cloudfront]

\[4\] [http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingHTTPPOST.html][http_docs.amazonwebservices.com_AmazonS3_2006-03-01_UsingHTTPPOST.html]

[http_ywskycn.com_cloud-computing_jets3t-use.html]: http://ywskycn.com/cloud-computing/jets3t-use.html
[download]: http://ywskycn.com/wp-content/uploads/2010/05/jets3t%E8%AF%B4%E6%98%8E.pdf
[http_jets3t.s3.amazonaws.com_index.html]: http://jets3t.s3.amazonaws.com/index.html
[http_www.amazon.com_s3]: http://www.amazon.com/s3
[http_www.amazon.com_cloudfront]: http://www.amazon.com/cloudfront
[http_docs.amazonwebservices.com_AmazonS3_2006-03-01_UsingHTTPPOST.html]: http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingHTTPPOST.html