Getting Started（Google Cloud Storage Client Library）

在运行下面的步骤之前，请确保：

1.你的项目已经激活了Google Cloud Storage和App Engine，包括已经创建了至少一个Cloud Storage bucket。

2.你已经下载了client库并解压了。

3.你已经安装并配置了最新的App Engine Java SDK。

运行LocalExample.java例子

LocalExample.java是一个非部署的例子，有助于快速测试和调查Cloud Storage的功能。除了Eclipse控制台输出它没有UI组件。（Cloud Storage client library deployable samples有UI也是可以获取的）

在Eclipse中运行LocalExample.java

1.开始Eclipse

2.在Eclipse中，单击Windows->Preferneces->Google->App Engine然后单击Add。

3.跟随提示，提供App Engine SDK的安装路径，然后单击OK。

4.在Files菜单中，单击Files->New->Java Project，创建一个名称为LocalExample的项目，并使用包名称com.google.appengine.demos。

5.在Package Explorer中选择这个项目，单击Files->New->Class并给这个类命名LocalExample，并使用包名称com.google.appengine.demos。

6.拷贝 LocalExampleJava source 的内容到这个类文件中。

7.在Package Explorer中再次选择这个项目，并右击，单击Properties->Java Build Path.

8.在Libraries tab，单击Add External Jars。必须追加下面的JARs:

● appengine-gcs-client.jar 来自你安装的Cloud Storage client库

● guava-15.0.jar 来自你安装的Cloud Storage client库

● joda-time-2.3.jar来自你安装的Cloud Storage client库

● appengine-testing.jar 来自App Engine 安装的子目录 /lib/testing

● appengine-api.jar 来自App Engine 安装的子目录 /lib/impl

● appengine-api-stubs.jar 来自App Engine 安装的子目录 /lib/impl

9.编译，运行Run as-> Java Application

10.在Eclipse Console中看到如下输出：

调查LocalExample.java例子

LocalExample.java在下面做了详细描述，说明了Cloud Storage client库的使用。

Imports

有一些使用的imports你可能不需要，或者本地测试会用到。下面列出了例子的imports。

import com.google.appengine.tools.cloudstorage.GcsFileOptions;
import com.google.appengine.tools.cloudstorage.GcsFilename;
import com.google.appengine.tools.cloudstorage.GcsInputChannel;
import com.google.appengine.tools.cloudstorage.GcsOutputChannel;
import com.google.appengine.tools.cloudstorage.GcsService;
import com.google.appengine.tools.cloudstorage.GcsServiceFactory;
import com.google.appengine.tools.cloudstorage.RetryParams;
import com.google.appengine.tools.development.testing.LocalBlobstoreServiceTestConfig;
import com.google.appengine.tools.development.testing.LocalDatastoreServiceTestConfig;
import com.google.appengine.tools.development.testing.LocalServiceTestHelper;

import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.nio.ByteBuffer;
import java.nio.channels.Channels;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

下面简要介绍了这些imports：

com.google.appengine.tools.cloudstorage.*使我们可以使用Cloud Storage client库。

com.google.appengine.tools.development.testing.* 仅在做某些App Engine特性的本地单元测试时需要。

java.io.ObjectInputStream 和java.io.ObjectOutputStream 用来读写对象。

java.nio.ByteBuffer用于非缓冲的读写

java.io.IOException 错误处理时需要（尽管没有列出）

java.nio.channels.Channels 用于将输入输出通道转换为流

java.nio.channels.ReadableByteChannel 用于从Cloud Storage中读取数据

创建一个GcsService来发送请求

通过库发送和接受请求到Cloud Storage，你需要一个GcsService实例：

private final GcsService gcsService =
    GcsServiceFactory.createGcsService(RetryParams.getDefaultInstance());

在这个片段中，注意在createGcsService中RetryParams的使用。如上所示，createGcsService(RetryParams.getDefaultInstance()),这设置了默认的重试配置，当访问Cloud Storage时，发生超时或者意想不到的错误时会进行重试。为了指定不同的值，比如重试的最大次数，你使用RetryParams.Builder 在一个新的 RetryParams对象中改变配置，并且在创建GcsService时提供它。注意一旦这个GcsService对象被创建了，它的重试参数不能被改变。

你可以创建任意多的GcsService实例。每一个实例是独立的，不可变的（因此是线程安全的），可重复使用的。比如，一个可以使用某个参数设置来写文件，同时另一个可以使用不同的重试参数来读不同的文件。

一个推荐的实践是在你的每个I/O类中使用独立的实例。这将帮助保持你的类的独立，以及少的开销。

向Cloud Storage写数据

下面的例子展示了如何向Cloud Storage的文件中写数据。独立的片段提供了写可序列化对象数据和字节数组。

Cloud Storage文件不会完全创建好直到close被调用

在下面的片段中，在finally块中没有出现close，就像Java中经常做的。所以有异常时，任何被写的部分都会自动地被清除。

向Cloud Storage写对象

这儿是说明如何序列化对象到Cloud Storage 文件。首先，获取一个可写的字节通道：

GcsOutputChannel outputChannel =
    gcsService.createOrReplace(fileName, GcsFileOptions.getDefaultInstance());

在这个片段中GcsService.createOrReplace 被调用了，GcsFilename 作为第一个参数。这个对象包含了要使用的bucket的名称以及对象的名称。如果在bucket已经有了一个同名的对象，并且你的应用有写的权限，这个调用会覆盖存在的文件（Cloud Storage不支持附加）。如果没有那个名字的文件，这个调用的结果就是创建了一个新文件。

第二个参数是GcsFileOptions。要使用默认的选项，使用GcsFileOptions.getDefaultInstance。要使用自己的设置，使用GcsFileOptions.Builder来设置选项并创建一个GcsFileOptions作为第二个参数。

这个文件选项被传递给Cloud Storage告诉它文件的文本类型，在头部你想传递的用户元数据，文件访问管理ACL等等。如果你不提供一个文本类型（mimeType）,这个文件将会被Cloud Storage以默认的MIME类型提供（serve），目前使用的是binary/octet-stream。如果你不指定一个ACL，分配的对象访问权限是当前默认的对象ACL。

注意所有的文件选项信息都可以在一个Close之后，通过调用GcsService.getMetadata(fileName)从一个对象中获取，而不需要它自己下载这个对象。

关于更多的配置信息，浏览Cloud Storage文档的ACLs和file options。

现在使用一个输出流来写数据

@SuppressWarnings("resource")
ObjectOutputStream oout =
    new ObjectOutputStream(Channels.newOutputStream(outputChannel));
oout.writeObject(content);
oout.close();

向Cloud Storage文件中写字节数组

这儿说明如何向Cloud Storage文件中写字节数组。

@SuppressWarnings("resource")
GcsOutputChannel outputChannel =
    gcsService.createOrReplace(fileName, GcsFileOptions.getDefaultInstance());
outputChannel.write(ByteBuffer.wrap(content));
outputChannel.close();

在createOrReplace调用中使用的参数的说明，参见Writing an Object to Cloud Storage下的说明。

从Cloud Storage中读取数据

下面的例子说明如何从存储在Cloud Storage中的文件读取数据。分开的片段提供了读Cloud Storage文件到对象（序列化）和字节数组。

将Cloud Storage读到一个对象

这个方法对于读大文件到一个缓冲中是有用的。

GcsInputChannel readChannel = gcsService.openPrefetchingReadChannel(fileName, 0, 1024 * 1024);

这个调用 GcsService.openPrefetchingReadChannel 有一个 GcsFilename，它包含了要读取的bucket的名字和要被读的对象。第二个参数是文件开始读的字节，0表示从文件的开头开始读。如果你提供了文件中其他的开始位置，比如字节300，这个读操作从字节300开始到文件的末尾，或直到你停止读。（预读缓冲会先读，它将包含超过你要停止的位置的字节）

预读对大部分应用而言是一个主要的优势，因为当更多的数据正在后台被下载的时候，允许并行地处理文件的一部分。

第三个参数就是预读的缓冲的尺寸，在这个例子中设置为1MB。

现在，从通道中读文件：

try (ObjectInputStream oin = new ObjectInputStream(Channels.newInputStream(readChannel))) {
  return oin.readObject();
}

读数据到字节数组

对于小文件，你可以一次读取所有的文件到字节数组中：

int fileSize = (int) gcsService.getMetadata(fileName).getLength();
ByteBuffer result = ByteBuffer.allocate(fileSize);
try (GcsInputChannel readChannel = gcsService.openReadChannel(fileName, 0)) {
  readChannel.read(result);
}

在上面的片段中，注意java.nio.ByteBuffer的使用，特别是缓冲的尺寸的设置等于要从通道中读取的文件的尺寸。

注意，对于大多数应用，更喜欢的方法是读（stream）文件(读数据到对象中)，因为这不需要在内存中一次就保存所有的数据。

有UI的可部署的Cloud Storage Client库的例子

对于有UI的可部署例子，浏览代码：

● GcsExampleServlet.java从Cloud Storage中上传下载文件

● PortOfFilesAPIGuestbookServlet.java是例子程序的端口（port），之前使用现已过时的Files API。更多关于迁移的信息，参见Migrating from the Files API。

在development server上运行以及部署之前需要编译这个例子。

编译这个例子：

1.从终端中Checkout代码

svn checkout http://appengine-gcs-client.googlecode.com/svn/trunk/ appengine-gcs-client-read-only

2.切换目录到ppengine-gcs-client-read-only/java

3.调用ant compile_example，这会用目录中的build.xml来编译例子。更多的关于使用Apache Ant的信息，参见 Using Apache Ant.

4.调用下面命令，运行dev server：

/path/to/AppEngSDK/dev_appserver.sh  /path/to/example/war

5.在你的浏览其中浏览 localhost:8080。看到下图：