Apache/hbase
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

HBASE-16742 Add chapter for devs on how we do protobufs going forward; ADDENDUM -- put all notes on CPEPs together in the CPEP section

Browse Source
This commit is contained in:
stack 2016-10-04 08:44:46 -07:00
parent b952e64751
commit b30b6dffe1
2 changed files with 15 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
src/main/asciidoc/_chapters/cp.adoc
View File

@ -184,13 +184,15 @@ WalObserver::
<<cp_example,Examples>> provides working examples of observer coprocessors. <<cp_example,Examples>> provides working examples of observer coprocessors.
[[cpeps]]
=== Endpoint Coprocessor === Endpoint Coprocessor
Endpoint processors allow you to perform computation at the location of the data. 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 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. 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 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()] 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 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 HBase cluster from 0.94 or earlier to 0.96 or later, you need to reimplement your
coprocessor. 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_example,Examples>> provides working examples of endpoint coprocessors.
[[cp_loading]] [[cp_loading]]

17
src/main/asciidoc/_chapters/protobuf.adoc
View File

@ -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 practice needs to whither. We'll make plain why in the later
xref:shaded.protobuf[hbase-2.0.0] section. 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]] [[shaded.protobuf]]
=== hbase-2.0.0 and the shading of protobufs (HBASE-15638) === hbase-2.0.0 and the shading of protobufs (HBASE-15638)