HBASE-16742 Add chapter for devs on how we do protobufs going forward; ADDENDUM -- put all notes on CPEPs together in the CPEP section
Project: http://git-wip-us.apache.org/repos/asf/hbase/repo Commit: http://git-wip-us.apache.org/repos/asf/hbase/commit/b30b6dff Tree: http://git-wip-us.apache.org/repos/asf/hbase/tree/b30b6dff Diff: http://git-wip-us.apache.org/repos/asf/hbase/diff/b30b6dff Branch: refs/heads/hbase-12439 Commit: b30b6dffe177fb06f33401efd2c22007026a044e Parents: b952e64 Author: stack <st...@apache.org> Authored: Tue Oct 4 08:44:46 2016 -0700 Committer: stack <st...@apache.org> Committed: Tue Oct 4 08:44:46 2016 -0700 ---------------------------------------------------------------------- src/main/asciidoc/_chapters/cp.adoc | 16 +++++++++++++++- src/main/asciidoc/_chapters/protobuf.adoc | 17 ----------------- 2 files changed, 15 insertions(+), 18 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/hbase/blob/b30b6dff/src/main/asciidoc/_chapters/cp.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/_chapters/cp.adoc b/src/main/asciidoc/_chapters/cp.adoc index a9620d3..1817dd3 100644 --- a/src/main/asciidoc/_chapters/cp.adoc +++ b/src/main/asciidoc/_chapters/cp.adoc @@ -184,13 +184,15 @@ WalObserver:: <<cp_example,Examples>> provides working examples of observer coprocessors. + +[[cpeps]] === Endpoint Coprocessor Endpoint processors allow you to perform computation at the location of the data. See <<cp_analogies, Coprocessor Analogy>>. An example is the need to calculate a running average or summation for an entire table which spans hundreds of regions. -In contract to observer coprocessors, where your code is run transparently, endpoint +In contrast to observer coprocessors, where your code is run transparently, endpoint coprocessors must be explicitly invoked using the link:https://hbase.apache.org/devapidocs/org/apache/hadoop/hbase/client/Table.html#coprocessorService%28java.lang.Class,%20byte%5B%5D,%20byte%5B%5D,%20org.apache.hadoop.hbase.client.coprocessor.Batch.Call%29[CoprocessorService()] method available in @@ -208,6 +210,18 @@ link:https://issues.apache.org/jira/browse/HBASE-5448[HBASE-5448]). To upgrade y HBase cluster from 0.94 or earlier to 0.96 or later, you need to reimplement your coprocessor. +Coprocessor Endpoints should make no use of HBase internals and +only avail of public APIs; ideally a CPEP should depend on Interfaces +and data structures only. This is not always possible but beware +that doing so makes the Endpoint brittle, liable to breakage as HBase +internals evolve. HBase internal APIs annotated as private or evolving +do not have to respect semantic versioning rules or general java rules on +deprecation before removal. While generated protobuf files are +absent the hbase audience annotations -- they are created by the +protobuf protoc tool which knows nothing of how HBase works -- +they should be consided `@InterfaceAudience.Private` so are liable to +change. + <<cp_example,Examples>> provides working examples of endpoint coprocessors. [[cp_loading]] http://git-wip-us.apache.org/repos/asf/hbase/blob/b30b6dff/src/main/asciidoc/_chapters/protobuf.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/_chapters/protobuf.adoc b/src/main/asciidoc/_chapters/protobuf.adoc index 4181878..fa63127 100644 --- a/src/main/asciidoc/_chapters/protobuf.adoc +++ b/src/main/asciidoc/_chapters/protobuf.adoc @@ -73,23 +73,6 @@ CPEP Service. Going forward, after the release of hbase-2.0.0, this practice needs to whither. We'll make plain why in the later xref:shaded.protobuf[hbase-2.0.0] section. -[[cpeps]] -=== Coprocessor Endpoints (CPEPs) -xref:cp:[Coprocessor Endpoints] are custom API a developer can -add to HBase. Protobufs are used to describe the methods and arguments -that comprise the new Service. -Coprocessor Endpoints should make no use of HBase internals and -only avail of public APIs; ideally a CPEP should depend on Interfaces -and data structures only. This is not always possible but beware -that doing so makes the Endpoint brittle, liable to breakage as HBase -internals evolve. HBase internal APIs annotated as private or evolving -do not have to respect semantic versioning rules or general java rules on -deprecation before removal. While generated protobuf files are -absent the hbase audience annotations -- they are created by the -protobuf protoc tool which knows nothing of how HBase works -- -they should be consided `@InterfaceAudience.Private` so are liable to -change. - [[shaded.protobuf]] === hbase-2.0.0 and the shading of protobufs (HBASE-15638)
