src/main/asciidoc/_chapters/protobuf.adoc

   1 ////
   2 /**
   3  *
   4  * Licensed to the Apache Software Foundation (ASF) under one
   5  * or more contributor license agreements.  See the NOTICE file
   6  * distributed with this work for additional information
   7  * regarding copyright ownership.  The ASF licenses this file
   8  * to you under the Apache License, Version 2.0 (the
   9  * "License"); you may not use this file except in compliance
  10  * with the License.  You may obtain a copy of the License at
  11  *
  12  *     http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  */
  20 ////
  21
  22 [[protobuf]]
  23 = Protobuf in HBase
  24 :doctype: book
  25 :numbered:
  26 :toc: left
  27 :icons: font
  28 :experimental:
  29
  30
  31 == Protobuf
  32 HBase uses Google's link:https://developers.google.com/protocol-buffers/[protobufs] wherever
  33 it persists metadata -- in the tail of hfiles or Cells written by
  34 HBase into the system hbase:meta table or when HBase writes znodes
  35 to zookeeper, etc. -- and when it passes objects over the wire making
  36 xref:hbase.rpc[RPCs]. HBase uses protobufs to describe the RPC
  37 Interfaces (Services) we expose to clients, for example the `Admin` and `Client`
  38 Interfaces that the RegionServer fields,
  39 or specifying the arbitrary extensions added by developers via our
  40 xref:cp[Coprocessor Endpoint] mechanism.
  41
  42 In this chapter we go into detail for  developers who are looking to
  43 understand better how it all works. This chapter is of particular
  44 use to those who would amend or extend HBase functionality.
  45
  46 With protobuf, you describe serializations and services in a `.protos` file.
  47 You then feed these descriptors to a protobuf tool, the `protoc` binary,
  48 to generate classes that can marshall and unmarshall the described serializations
  49 and field the specified Services.
  50
  51 See the `README.txt` in the HBase sub-modules for details on how
  52 to run the class generation on a per-module basis;
  53 e.g. see `hbase-protocol/README.txt` for how to generate protobuf classes
  54 in the hbase-protocol module.
  55
  56 In HBase, `.proto` files are either in the `hbase-protocol` module; a module
  57 dedicated to hosting the common proto files and the protoc generated classes
  58 that HBase uses internally serializing metadata. For extensions to hbase
  59 such as REST or Coprocessor Endpoints that need their own descriptors; their
  60 protos are located inside the function's hosting module: e.g. `hbase-rest`
  61 is home to the REST proto files and the `hbase-rsgroup` table grouping
  62 Coprocessor Endpoint has all protos that have to do with table grouping.
  63
  64 Protos are hosted by the module that makes use of them. While
  65 this makes it so generation of protobuf classes is distributed, done
  66 per module, we do it this way so modules encapsulate all to do with
  67 the functionality they bring to hbase.
  68
  69 Extensions whether REST or Coprocessor Endpoints will make use
  70 of core HBase protos found back in the hbase-protocol module. They'll
  71 use these core protos when they want to serialize a Cell or a Put or
  72 refer to a particular node via ServerName, etc., as part of providing the
  73 CPEP Service. Going forward, after the release of hbase-2.0.0, this
  74 practice needs to whither. We'll explain why in the later
  75 xref:shaded.protobuf[hbase-2.0.0] section.
  76
  77 [[shaded.protobuf]]
  78 === hbase-2.0.0 and the shading of protobufs (HBASE-15638)
  79
  80 As of hbase-2.0.0, our protobuf usage gets a little more involved. HBase
  81 core protobuf references are offset so as to refer to a private,
  82 bundled protobuf. Core stops referring to protobuf
  83 classes at com.google.protobuf.* and instead references protobuf at
  84 the HBase-specific offset
  85 org.apache.hadoop.hbase.shaded.com.google.protobuf.*.  We do this indirection
  86 so hbase core can evolve its protobuf version independent of whatever our
  87 dependencies rely on. For instance, HDFS serializes using protobuf.
  88 HDFS is on our CLASSPATH. Without the above described indirection, our
  89 protobuf versions would have to align. HBase would be stuck
  90 on the HDFS protobuf version until HDFS decided to upgrade. HBase
  91 and HDFS versions would be tied.
  92
  93 We had to move on from protobuf-2.5.0 because we need facilities
  94 added in protobuf-3.1.0; in particular being able to save on
  95 copies and avoiding bringing protobufs onheap for
  96 serialization/deserialization.
  97
  98 In hbase-2.0.0, we introduced a new module, `hbase-protocol-shaded`
  99 inside which we contained all to do with protobuf and its subsequent
 100 relocation/shading. This module is in essence a copy of much of the old
 101 `hbase-protocol` but with an extra shading/relocation step.
 102 Core was moved to depend on this new module.
 103
 104 That said, a complication arises around Coprocessor Endpoints (CPEPs).
 105 CPEPs depend on public HBase APIs that reference protobuf classes at
 106 `com.google.protobuf.*` explicitly. For example, in our Table Interface
 107 we have the below as the means by which you obtain a CPEP Service
 108 to make invocations against:
 109
 110 [source,java]
 111 ----
 112 ...
 113   <T extends com.google.protobuf.Service,R> Map<byte[],R> coprocessorService(
 114    Class<T> service, byte[] startKey, byte[] endKey,
 115      org.apache.hadoop.hbase.client.coprocessor.Batch.Call<T,R> callable)
 116   throws com.google.protobuf.ServiceException, Throwable
 117 ----
 118
 119 Existing CPEPs will have made reference to core HBase protobufs
 120 specifying ServerNames or carrying Mutations.
 121 So as to continue being able to service CPEPs and their references
 122 to `com.google.protobuf.*` across the upgrade to hbase-2.0.0 and beyond,
 123 HBase needs to be able to deal with both
 124 `com.google.protobuf.*` references and its internal offset
 125 `org.apache.hadoop.hbase.shaded.com.google.protobuf.*` protobufs.
 126
 127 The `hbase-protocol-shaded` module hosts all
 128 protobufs used by HBase core.
 129
 130 But for the vestigial CPEP references to the (non-shaded) content of
 131 `hbase-protocol`, we keep around most of this  module going forward
 132 just so it is available to CPEPs.  Retaining the most of `hbase-protocol`
 133 makes for overlapping, 'duplicated' proto instances where some exist as
 134 non-shaded/non-relocated here in their old module
 135 location but also in the new location, shaded under
 136 `hbase-protocol-shaded`. In other words, there is an instance
 137 of the generated protobuf class
 138 `org.apache.hadoop.hbase.protobuf.generated.ServerName`
 139 in hbase-protocol and another generated instance that is the same in all
 140 regards except its protobuf references are to the internal shaded
 141 version at `org.apache.hadoop.hbase.shaded.protobuf.generated.ServerName`
 142 (note the 'shaded' addition in the middle of the package name).
 143
 144 If you extend a proto in `hbase-protocol-shaded` for  internal use,
 145 consider extending it also in
 146 `hbase-protocol` (and regenerating).
 147
 148 Going forward, we will provide a new module of common types for use
 149 by CPEPs that will have the same guarantees against change as does our
 150 public API. TODO.
 151
 152 === protobuf changes for hbase-3.0.0 (HBASE-23797)
 153 Since hadoop(start from 3.3.x) also shades protobuf and bumps the version to
 154 3.x, there is no reason for us to stay on protobuf 2.5.0 any more.
 155
 156 In HBase 3.0.0, the hbase-protocol module has been purged, the CPEP
 157 implementation should use the protos in hbase-protocol-shaded module, and also
 158 make use of the shaded protobuf in hbase-thirdparty. In general, we will keep
 159 the protobuf version compatible for a whole major release, unless there are
 160 critical problems, for example, a critical CVE on protobuf.
 161
 162 Add this dependency to your pom:
 163 [source,xml]
 164 ----
 165 <dependency>
 166   <groupId>org.apache.hbase.thirdparty</groupId>
 167   <artifactId>hbase-shaded-protobuf</artifactId>
 168   <!-- use the version that your target hbase cluster uses -->
 169   <version>${hbase-thirdparty.version}</version>
 170   <scope>provided</scope>
 171 </dependency>
 172 ----
 173
 174 And typically you also need to add this plugin to your pom to make your
 175 generated protobuf code also use the shaded and relocated protobuf version
 176 in hbase-thirdparty.
 177 [source,xml]
 178 ----
 179 <plugin>
 180   <groupId>com.google.code.maven-replacer-plugin</groupId>
 181   <artifactId>replacer</artifactId>
 182   <version>1.5.3</version>
 183   <executions>
 184     <execution>
 185       <phase>process-sources</phase>
 186       <goals>
 187         <goal>replace</goal>
 188       </goals>
 189     </execution>
 190   </executions>
 191   <configuration>
 192     <basedir>${basedir}/target/generated-sources/</basedir>
 193       <includes>
 194         <include>**/*.java</include>
 195       </includes>
 196       <!-- Ignore errors when missing files, because it means this build
 197            was run with -Dprotoc.skip and there is no -Dreplacer.skip -->
 198       <ignoreErrors>true</ignoreErrors>
 199       <replacements>
 200         <replacement>
 201           <token>([^\.])com.google.protobuf</token>
 202           <value>$1org.apache.hbase.thirdparty.com.google.protobuf</value>
 203         </replacement>
 204         <replacement>
 205           <token>(public)(\W+static)?(\W+final)?(\W+class)</token>
 206           <value>@javax.annotation.Generated("proto") $1$2$3$4</value>
 207         </replacement>
 208         <!-- replacer doesn't support anchoring or negative lookbehind -->
 209         <replacement>
 210           <token>(@javax.annotation.Generated\("proto"\) ){2}</token>
 211           <value>$1</value>
 212         </replacement>
 213       </replacements>
 214   </configuration>
 215 </plugin>
 216 ----
 217
 218 In hbase-examples module, we have some examples under the
 219 `org.apache.hadoop.hbase.coprocessor.example` package. You can see
 220 `BulkDeleteEndpoint` and `BulkDelete.proto` for more details, and you can also
 221 check the `pom.xml` of hbase-examples module to see how to make use of the above
 222 plugin.