HBASE-18052 Add document for async admin
Project: http://git-wip-us.apache.org/repos/asf/hbase/repo Commit: http://git-wip-us.apache.org/repos/asf/hbase/commit/2d5a0fbd Tree: http://git-wip-us.apache.org/repos/asf/hbase/tree/2d5a0fbd Diff: http://git-wip-us.apache.org/repos/asf/hbase/diff/2d5a0fbd Branch: refs/heads/HBASE-18147 Commit: 2d5a0fbd16ddd9d46ab3f72cabd06a853df4916b Parents: a9352fe Author: Guanghao Zhang <zg...@apache.org> Authored: Sun Jul 16 16:00:35 2017 +0800 Committer: Guanghao Zhang <zg...@apache.org> Committed: Sun Jul 16 16:46:33 2017 +0800 ---------------------------------------------------------------------- src/main/asciidoc/_chapters/architecture.adoc | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/hbase/blob/2d5a0fbd/src/main/asciidoc/_chapters/architecture.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/_chapters/architecture.adoc b/src/main/asciidoc/_chapters/architecture.adoc index 8d11efb..ebb0677 100644 --- a/src/main/asciidoc/_chapters/architecture.adoc +++ b/src/main/asciidoc/_chapters/architecture.adoc @@ -265,11 +265,18 @@ For `AsyncTable`, you need to provide a thread pool when getting it. The callbac For `RawAsyncTable`, all the callbacks are executed inside the framework thread so it is not allowed to do time consuming works in the callbacks otherwise you may block the framework thread and cause very bad performance impact. It is designed for advanced users who want to write high performance code. You can see the `org.apache.hadoop.hbase.client.example.HttpProxyExample` to see how to write fully asynchronous code with `RawAsyncTable`. And coprocessor related methods are only in `RawAsyncTable`. -.On `AsyncAdmin` -[WARNING] -==== -`AsyncAdmin` is still under development and marked as IA.Private. Use it with caution as we may change the API without any announcement. -==== +[[async.admin]] +=== Asynchronous Admin === + +You can obtain an `AsyncConnection` from `ConnectionFactory`, and then get a `AsyncAdmin` instance from it to access HBase. Notice that there are two `getAdmin` methods to get a `AsyncAdmin` instance. One method has one extra thread pool parameter which is used to execute callbacks. It is designed for normal users. Another method doesn't need a thread pool and all the callbacks are executed inside the framework thread so it is not allowed to do time consuming works in the callbacks. It is designed for advanced users. + +The default `getAdmin` methods will return a `AsyncAdmin` instance which use default configs. If you want to customize some configs, you can use `getAdminBuilder` methods to get a `AsyncAdminBuilder` for creating `AsyncAdmin` instance. Users are free to only set the configs they care about to create a new `AsyncAdmin` instance. + +For the `AsyncAdmin` interface, most methods have the same meaning with the old `Admin` interface, expect that the return value is wrapped with a CompletableFuture usually. + +For most admin operations, when the returned CompletableFuture is done, it means the admin operation has also been done. But for compact operation, it only means the compact request was sent to HBase and may need some time to finish the compact operation. For `rollWALWriter` method, it only means the rollWALWriter request was sent to the region server and may need some time to finish the `rollWALWriter` operation. + +For region name, we only accept `byte[]` as the parameter type and it may be a full region name or a encoded region name. For server name, we only accept `ServerName` as the parameter type. For table name, we only accept `TableName` as the parameter type. For `list*` operations, we only accept `Pattern` as the parameter type if you want to do regex matching. [[client.external]] === External Clients
