[GitHub] [hadoop-ozone] iamabug commented on a change in pull request #489: HDDS-2747. interface/JavaApi.md

[GitBox <gi...@apache.org>]

iamabug commented on a change in pull request #489: HDDS-2747. interface/JavaApi.md
URL: https://github.com/apache/hadoop-ozone/pull/489#discussion_r371595817
 
 

 ##########
 File path: hadoop-hdds/docs/content/interface/JavaApi.zh.md
 ##########
 @@ -21,4 +21,132 @@ summary: Ozone has a set of Native RPC based APIs. This is the lowest level API'
   limitations under the License.
 -->
 
-测试页面
+Ozone 自带了支持 RPC 的客户端库，对于一般的应用场景也可以使用兼容 S3 的 REST 接口替代 Ozone 客户端 API。
+
+
+## 创建 Ozone 客户端
+
+ozone 客户端由客户端工厂创建，我们可以通过如下调用获得一个 RPC 客户端对象：
+
+{{< highlight java >}}
+OzoneClient ozClient = OzoneClientFactory.getRpcClient();
+{{< /highlight >}}
+
+如果用户想要创建指定配置的客户端，可以这样调用：
+
+{{< highlight java >}}
+OzoneClient ozClient = OzoneClientFactory.getClient();
+{{< /highlight >}}
+
+这样就会返回一个合适的客户端对象。
+
+## 使用 Ozone 客户端写数据
+
+ozone 中的数据层次为卷、桶和键。卷是桶的集合，桶是键的集合，如果要向 ozone 写数据，你需要依次获得卷、桶和键。
+
+### 创建卷
+
+有了客户端对象之后，我们需要获取 ObjectStore 的引用，获取方法为：
+
+{{< highlight java >}}
+ObjectStore objectStore = ozClient.getObjectStore();
+{{< /highlight >}}
+
+ObjectStore 对象表示了客户端连接的集群。
+
+{{< highlight java >}}
+// 我们创建一个卷来存储数据
+// 使用默认参数来创建 assets 卷
+objectStore.createVolume("assets");
+
+// 验证 assets 卷是否已创建
+OzoneVolume assets = objectStore.getVolume("assets");
+{{< /highlight >}}
+
+
+createVolume 方法也支持接收一个数组来指定卷的创建参数。
+
+### 创建桶
+
+有了卷之后，你就可以在卷中创建桶。
+
+{{< highlight java >}}
+// 创建一个名为 videos 的桶
+assets.createBucket("videos");
+OzoneBucket video = assets.getBucket("videos");
+{{< /highlight >}}
+
+此时我们有了一个可用的卷和一个桶，卷名为 _assets_ ，桶名为 _videos_ 。
+
+接下来我们创建一个键。
+
+### 键的读写
+
+通过桶对象可以进行键的读写，下面的代码从本地磁盘读取名为 intro.mp4 的视频文件，并把它存储到我们刚刚创建的 _video_ 桶中。
+
+{{< highlight java >}}
+// 从文件读取数据，需要由用户提供读取函数
+byte [] videoData = readFile("intro.mp4");
+
+// 创建一个输出流并写数据
+OzoneOutputStream videoStream = video.createKey("intro.mp4", 1048576);
+videoStream.write(videoData);
+
+// 写操作完成之后关闭输出流
+videoStream.close();
+
+
+// 我们可以使用同一个桶，通过创建输入流来读取刚刚写入的文件
+// 先创建一个用来存储视频的字节数组
+byte[] data = new byte[(int)1048576];
+OzoneInputStream introStream = video.readKey("intro.mp4");
+// 读取 intro.mp4 到缓冲区中
+introStream.read(data);
+introStream.close();
+{{< /highlight >}}
+
+
+下面是一个完整的代码示例，请注意代码中 close 函数的调用。
+
+{{< highlight java >}}
+// 创建客户端对象
+OzoneClient ozClient = OzoneClientFactory.getClient();
+
+// 通过客户端对象获取 ObjectStore 的引用
+ObjectStore objectStore = ozClient.getObjectStore();
+
+// 创建用于存储数据的 assets 卷
+// 此处创建的卷采用默认参数
 
 Review comment:
   does we need to translate `assets` here, because it was translated in two occurances above ?

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

---------------------------------------------------------------------
To unsubscribe, e-mail: ozone-issues-unsubscribe@hadoop.apache.org
For additional commands, e-mail: ozone-issues-help@hadoop.apache.org