hbase/hbase-protocol-shaded/README.txt

54 lines
2.2 KiB
Plaintext
Raw Normal View History

HBASE-15638 Shade protobuf Which includes HBASE-16742 Add chapter for devs on how we do protobufs going forward HBASE-16741 Amend the generate protobufs out-of-band build step to include shade, pulling in protobuf source and a hook for patching protobuf Removed ByteStringer from hbase-protocol-shaded. Use the protobuf-3.1.0 trick directly instead. Makes stuff cleaner. All under 'shaded' dir is now generated. HBASE-16567 Upgrade to protobuf-3.1.x Regenerate all protos in this module with protoc3. Redo ByteStringer to use new pb3.1.0 unsafebytesutil instead of HBaseZeroCopyByteString HBASE-16264 Figure how to deal with endpoints and shaded pb Shade our protobufs. Do it in a manner that makes it so we can still have in our API references to com.google.protobuf (and in REST). The c.g.p in API is for Coprocessor Endpoints (CPEP) This patch is Tactic #4 from Shading Doc attached to the referenced issue. Figuring an appoach took a while because we have Coprocessor Endpoints mixed in with the core of HBase that are tough to untangle (FIX). Tactic #4 (the fourth attempt at addressing this issue) is COPY all but the CPEP .proto files currently in hbase-protocol to a new module named hbase-protocol-shaded. Generate .protos again in the new location and then relocate/shade the generated files. Let CPEPs keep on with the old references at com.google.protobuf.* and org.apache.hadoop.hbase.protobuf.* but change the hbase core so all instead refer to the relocated files in their new location at org.apache.hadoop.hbase.shaded.com.google.protobuf.*. Let the new module also shade protobufs themselves and change hbase core to pick up this shaded protobuf rather than directly reference com.google.protobuf. This approach allows us to explicitly refer to either the shaded or non-shaded version of a protobuf class in any particular context (though usually context dictates one or the other). Core runs on shaded protobuf. CPEPs continue to use whatever is on the classpath with com.google.protobuf.* which is pb2.5.0 for the near future at least. See above cited doc for follow-ons and downsides. In short, IDEs will complain about not being able to find the shaded protobufs since shading happens at package time; will fix by checking in all generated classes and relocated protobuf in a follow-on. Also, CPEPs currently suffer an extra-copy as marshalled from non-shaded to shaded. To fix. Finally, our .protos are duplicated; once shaded, and once not. Pain, but how else to reveal our protos to CPEPs or C++ client that wants to talk with HBase AND shade protobuf. Details: Add a new hbase-protocol-shaded module. It is a copy of hbase-protocol i with all relocated offset from o.a.h.h. to o.a.h.h.shaded. The new module also includes the relocated pb. It does not include CPEPs. They stay in their old location. Add another module hbase-endpoint which has in it all the endpoints that ship as part of hbase -- at least the ones that are not entangled with core such as AccessControl and Auth. Move all protos for these CPEPs here as well as their unit tests (mostly moving a bunch of stuff out of hbase-server module) Much of the change looks like this: -import org.apache.hadoop.hbase.protobuf.ProtobufUtil; -import org.apache.hadoop.hbase.protobuf.generated.ClusterIdProtos; +import org.apache.hadoop.hbase.protobuf.shaded.ProtobufUtil; +import org.apache.hadoop.hbase.shaded.protobuf.generated.ClusterIdProtos; In HTable and in HBaseAdmin, regularize the way Callables are used and also hide protobuf usage as much as possible moving it up into Callable super classes or out to utility classes. Still TODO is adding in of retries, etc., but can wait on procedure which will redo all this. Also in HTable and HBaseAdmin as well as in HRegionServer and Server, be explicit when using non-shaded protobuf. Do the full-path so it is clear. This is around endpoint coprocessors registration of services and execution of CPEP methods. Shrunk ProtobufUtil by moving methods used by one CPEP only back to the CPEP either into Client class or as new Util class; e.g. AccessControlUtil. There are actually two versions of ProtobufUtil now; a shaded one and a subset that is used by CPEPs doing non-shaded work. Made it so hbase-common no longer depends on hbase-protocol (with Matteo's help) R*Converter classes got moved down under shaded package -- they are for internal use only. There are no non-shaded versions of these classes. D hbase-client/src/main/java/org/apache/hadoop/hbase/client/AbstractRegionServerCallable D RetryingCallableBase Not used anymore and we have too many tiers of Callables so removed/cleaned-up. A ClientServicecallable Had to add this one. RegionServerCallable was made generic so it could be used for a few Interfaces (Client and Admin). Then added ClientServiceCallable to implement RegionServerCallable with the Client Interface.
2016-10-04 00:37:32 -04:00
Please read carefully as the 'menu options' have changed.
What you do in here is not what you do elsewhere to generate
proto java files.
HBASE-15638 Shade protobuf Which includes HBASE-16742 Add chapter for devs on how we do protobufs going forward HBASE-16741 Amend the generate protobufs out-of-band build step to include shade, pulling in protobuf source and a hook for patching protobuf Removed ByteStringer from hbase-protocol-shaded. Use the protobuf-3.1.0 trick directly instead. Makes stuff cleaner. All under 'shaded' dir is now generated. HBASE-16567 Upgrade to protobuf-3.1.x Regenerate all protos in this module with protoc3. Redo ByteStringer to use new pb3.1.0 unsafebytesutil instead of HBaseZeroCopyByteString HBASE-16264 Figure how to deal with endpoints and shaded pb Shade our protobufs. Do it in a manner that makes it so we can still have in our API references to com.google.protobuf (and in REST). The c.g.p in API is for Coprocessor Endpoints (CPEP) This patch is Tactic #4 from Shading Doc attached to the referenced issue. Figuring an appoach took a while because we have Coprocessor Endpoints mixed in with the core of HBase that are tough to untangle (FIX). Tactic #4 (the fourth attempt at addressing this issue) is COPY all but the CPEP .proto files currently in hbase-protocol to a new module named hbase-protocol-shaded. Generate .protos again in the new location and then relocate/shade the generated files. Let CPEPs keep on with the old references at com.google.protobuf.* and org.apache.hadoop.hbase.protobuf.* but change the hbase core so all instead refer to the relocated files in their new location at org.apache.hadoop.hbase.shaded.com.google.protobuf.*. Let the new module also shade protobufs themselves and change hbase core to pick up this shaded protobuf rather than directly reference com.google.protobuf. This approach allows us to explicitly refer to either the shaded or non-shaded version of a protobuf class in any particular context (though usually context dictates one or the other). Core runs on shaded protobuf. CPEPs continue to use whatever is on the classpath with com.google.protobuf.* which is pb2.5.0 for the near future at least. See above cited doc for follow-ons and downsides. In short, IDEs will complain about not being able to find the shaded protobufs since shading happens at package time; will fix by checking in all generated classes and relocated protobuf in a follow-on. Also, CPEPs currently suffer an extra-copy as marshalled from non-shaded to shaded. To fix. Finally, our .protos are duplicated; once shaded, and once not. Pain, but how else to reveal our protos to CPEPs or C++ client that wants to talk with HBase AND shade protobuf. Details: Add a new hbase-protocol-shaded module. It is a copy of hbase-protocol i with all relocated offset from o.a.h.h. to o.a.h.h.shaded. The new module also includes the relocated pb. It does not include CPEPs. They stay in their old location. Add another module hbase-endpoint which has in it all the endpoints that ship as part of hbase -- at least the ones that are not entangled with core such as AccessControl and Auth. Move all protos for these CPEPs here as well as their unit tests (mostly moving a bunch of stuff out of hbase-server module) Much of the change looks like this: -import org.apache.hadoop.hbase.protobuf.ProtobufUtil; -import org.apache.hadoop.hbase.protobuf.generated.ClusterIdProtos; +import org.apache.hadoop.hbase.protobuf.shaded.ProtobufUtil; +import org.apache.hadoop.hbase.shaded.protobuf.generated.ClusterIdProtos; In HTable and in HBaseAdmin, regularize the way Callables are used and also hide protobuf usage as much as possible moving it up into Callable super classes or out to utility classes. Still TODO is adding in of retries, etc., but can wait on procedure which will redo all this. Also in HTable and HBaseAdmin as well as in HRegionServer and Server, be explicit when using non-shaded protobuf. Do the full-path so it is clear. This is around endpoint coprocessors registration of services and execution of CPEP methods. Shrunk ProtobufUtil by moving methods used by one CPEP only back to the CPEP either into Client class or as new Util class; e.g. AccessControlUtil. There are actually two versions of ProtobufUtil now; a shaded one and a subset that is used by CPEPs doing non-shaded work. Made it so hbase-common no longer depends on hbase-protocol (with Matteo's help) R*Converter classes got moved down under shaded package -- they are for internal use only. There are no non-shaded versions of these classes. D hbase-client/src/main/java/org/apache/hadoop/hbase/client/AbstractRegionServerCallable D RetryingCallableBase Not used anymore and we have too many tiers of Callables so removed/cleaned-up. A ClientServicecallable Had to add this one. RegionServerCallable was made generic so it could be used for a few Interfaces (Client and Admin). Then added ClientServiceCallable to implement RegionServerCallable with the Client Interface.
2016-10-04 00:37:32 -04:00
This module has proto files used by core. These protos
overlap with protos that are used by coprocessor endpoints
(CPEP) in the module hbase-protocol. So the core versions have
a different name, the generated classes are relocated
-- i.e. shaded -- to a new location; they are moved from
org.apache.hadoop.hbase.* to org.apache.hadoop.hbase.shaded.
This module also includes the protobuf that hbase core depends
on again relocated to live at an offset of
org.apache.hadoop.hbase.shaded so as to avoid clashes with other
versions of protobuf resident on our CLASSPATH included,
transitively or otherwise, by dependencies: i.e. the shaded
protobuf Message class is at
org.apache.hadoop.hbase.shaded.com.google.protobuf.Message
rather than at com.google.protobuf.Message.
Finally, this module also includes patches applied on top of
protobuf to add functionality not yet in protobuf that we
need now.
If you make changes to protos, to the protobuf version or to
the patches you want to apply to protobuf, you must rerun the
below step and then check in what it generated:
HBASE-15638 Shade protobuf Which includes HBASE-16742 Add chapter for devs on how we do protobufs going forward HBASE-16741 Amend the generate protobufs out-of-band build step to include shade, pulling in protobuf source and a hook for patching protobuf Removed ByteStringer from hbase-protocol-shaded. Use the protobuf-3.1.0 trick directly instead. Makes stuff cleaner. All under 'shaded' dir is now generated. HBASE-16567 Upgrade to protobuf-3.1.x Regenerate all protos in this module with protoc3. Redo ByteStringer to use new pb3.1.0 unsafebytesutil instead of HBaseZeroCopyByteString HBASE-16264 Figure how to deal with endpoints and shaded pb Shade our protobufs. Do it in a manner that makes it so we can still have in our API references to com.google.protobuf (and in REST). The c.g.p in API is for Coprocessor Endpoints (CPEP) This patch is Tactic #4 from Shading Doc attached to the referenced issue. Figuring an appoach took a while because we have Coprocessor Endpoints mixed in with the core of HBase that are tough to untangle (FIX). Tactic #4 (the fourth attempt at addressing this issue) is COPY all but the CPEP .proto files currently in hbase-protocol to a new module named hbase-protocol-shaded. Generate .protos again in the new location and then relocate/shade the generated files. Let CPEPs keep on with the old references at com.google.protobuf.* and org.apache.hadoop.hbase.protobuf.* but change the hbase core so all instead refer to the relocated files in their new location at org.apache.hadoop.hbase.shaded.com.google.protobuf.*. Let the new module also shade protobufs themselves and change hbase core to pick up this shaded protobuf rather than directly reference com.google.protobuf. This approach allows us to explicitly refer to either the shaded or non-shaded version of a protobuf class in any particular context (though usually context dictates one or the other). Core runs on shaded protobuf. CPEPs continue to use whatever is on the classpath with com.google.protobuf.* which is pb2.5.0 for the near future at least. See above cited doc for follow-ons and downsides. In short, IDEs will complain about not being able to find the shaded protobufs since shading happens at package time; will fix by checking in all generated classes and relocated protobuf in a follow-on. Also, CPEPs currently suffer an extra-copy as marshalled from non-shaded to shaded. To fix. Finally, our .protos are duplicated; once shaded, and once not. Pain, but how else to reveal our protos to CPEPs or C++ client that wants to talk with HBase AND shade protobuf. Details: Add a new hbase-protocol-shaded module. It is a copy of hbase-protocol i with all relocated offset from o.a.h.h. to o.a.h.h.shaded. The new module also includes the relocated pb. It does not include CPEPs. They stay in their old location. Add another module hbase-endpoint which has in it all the endpoints that ship as part of hbase -- at least the ones that are not entangled with core such as AccessControl and Auth. Move all protos for these CPEPs here as well as their unit tests (mostly moving a bunch of stuff out of hbase-server module) Much of the change looks like this: -import org.apache.hadoop.hbase.protobuf.ProtobufUtil; -import org.apache.hadoop.hbase.protobuf.generated.ClusterIdProtos; +import org.apache.hadoop.hbase.protobuf.shaded.ProtobufUtil; +import org.apache.hadoop.hbase.shaded.protobuf.generated.ClusterIdProtos; In HTable and in HBaseAdmin, regularize the way Callables are used and also hide protobuf usage as much as possible moving it up into Callable super classes or out to utility classes. Still TODO is adding in of retries, etc., but can wait on procedure which will redo all this. Also in HTable and HBaseAdmin as well as in HRegionServer and Server, be explicit when using non-shaded protobuf. Do the full-path so it is clear. This is around endpoint coprocessors registration of services and execution of CPEP methods. Shrunk ProtobufUtil by moving methods used by one CPEP only back to the CPEP either into Client class or as new Util class; e.g. AccessControlUtil. There are actually two versions of ProtobufUtil now; a shaded one and a subset that is used by CPEPs doing non-shaded work. Made it so hbase-common no longer depends on hbase-protocol (with Matteo's help) R*Converter classes got moved down under shaded package -- they are for internal use only. There are no non-shaded versions of these classes. D hbase-client/src/main/java/org/apache/hadoop/hbase/client/AbstractRegionServerCallable D RetryingCallableBase Not used anymore and we have too many tiers of Callables so removed/cleaned-up. A ClientServicecallable Had to add this one. RegionServerCallable was made generic so it could be used for a few Interfaces (Client and Admin). Then added ClientServiceCallable to implement RegionServerCallable with the Client Interface.
2016-10-04 00:37:32 -04:00
$ mvn install -Dcompile-protobuf
HBASE-15638 Shade protobuf Which includes HBASE-16742 Add chapter for devs on how we do protobufs going forward HBASE-16741 Amend the generate protobufs out-of-band build step to include shade, pulling in protobuf source and a hook for patching protobuf Removed ByteStringer from hbase-protocol-shaded. Use the protobuf-3.1.0 trick directly instead. Makes stuff cleaner. All under 'shaded' dir is now generated. HBASE-16567 Upgrade to protobuf-3.1.x Regenerate all protos in this module with protoc3. Redo ByteStringer to use new pb3.1.0 unsafebytesutil instead of HBaseZeroCopyByteString HBASE-16264 Figure how to deal with endpoints and shaded pb Shade our protobufs. Do it in a manner that makes it so we can still have in our API references to com.google.protobuf (and in REST). The c.g.p in API is for Coprocessor Endpoints (CPEP) This patch is Tactic #4 from Shading Doc attached to the referenced issue. Figuring an appoach took a while because we have Coprocessor Endpoints mixed in with the core of HBase that are tough to untangle (FIX). Tactic #4 (the fourth attempt at addressing this issue) is COPY all but the CPEP .proto files currently in hbase-protocol to a new module named hbase-protocol-shaded. Generate .protos again in the new location and then relocate/shade the generated files. Let CPEPs keep on with the old references at com.google.protobuf.* and org.apache.hadoop.hbase.protobuf.* but change the hbase core so all instead refer to the relocated files in their new location at org.apache.hadoop.hbase.shaded.com.google.protobuf.*. Let the new module also shade protobufs themselves and change hbase core to pick up this shaded protobuf rather than directly reference com.google.protobuf. This approach allows us to explicitly refer to either the shaded or non-shaded version of a protobuf class in any particular context (though usually context dictates one or the other). Core runs on shaded protobuf. CPEPs continue to use whatever is on the classpath with com.google.protobuf.* which is pb2.5.0 for the near future at least. See above cited doc for follow-ons and downsides. In short, IDEs will complain about not being able to find the shaded protobufs since shading happens at package time; will fix by checking in all generated classes and relocated protobuf in a follow-on. Also, CPEPs currently suffer an extra-copy as marshalled from non-shaded to shaded. To fix. Finally, our .protos are duplicated; once shaded, and once not. Pain, but how else to reveal our protos to CPEPs or C++ client that wants to talk with HBase AND shade protobuf. Details: Add a new hbase-protocol-shaded module. It is a copy of hbase-protocol i with all relocated offset from o.a.h.h. to o.a.h.h.shaded. The new module also includes the relocated pb. It does not include CPEPs. They stay in their old location. Add another module hbase-endpoint which has in it all the endpoints that ship as part of hbase -- at least the ones that are not entangled with core such as AccessControl and Auth. Move all protos for these CPEPs here as well as their unit tests (mostly moving a bunch of stuff out of hbase-server module) Much of the change looks like this: -import org.apache.hadoop.hbase.protobuf.ProtobufUtil; -import org.apache.hadoop.hbase.protobuf.generated.ClusterIdProtos; +import org.apache.hadoop.hbase.protobuf.shaded.ProtobufUtil; +import org.apache.hadoop.hbase.shaded.protobuf.generated.ClusterIdProtos; In HTable and in HBaseAdmin, regularize the way Callables are used and also hide protobuf usage as much as possible moving it up into Callable super classes or out to utility classes. Still TODO is adding in of retries, etc., but can wait on procedure which will redo all this. Also in HTable and HBaseAdmin as well as in HRegionServer and Server, be explicit when using non-shaded protobuf. Do the full-path so it is clear. This is around endpoint coprocessors registration of services and execution of CPEP methods. Shrunk ProtobufUtil by moving methods used by one CPEP only back to the CPEP either into Client class or as new Util class; e.g. AccessControlUtil. There are actually two versions of ProtobufUtil now; a shaded one and a subset that is used by CPEPs doing non-shaded work. Made it so hbase-common no longer depends on hbase-protocol (with Matteo's help) R*Converter classes got moved down under shaded package -- they are for internal use only. There are no non-shaded versions of these classes. D hbase-client/src/main/java/org/apache/hadoop/hbase/client/AbstractRegionServerCallable D RetryingCallableBase Not used anymore and we have too many tiers of Callables so removed/cleaned-up. A ClientServicecallable Had to add this one. RegionServerCallable was made generic so it could be used for a few Interfaces (Client and Admin). Then added ClientServiceCallable to implement RegionServerCallable with the Client Interface.
2016-10-04 00:37:32 -04:00
or
$ mvn install -Pcompile-protobuf
HBASE-15638 Shade protobuf Which includes HBASE-16742 Add chapter for devs on how we do protobufs going forward HBASE-16741 Amend the generate protobufs out-of-band build step to include shade, pulling in protobuf source and a hook for patching protobuf Removed ByteStringer from hbase-protocol-shaded. Use the protobuf-3.1.0 trick directly instead. Makes stuff cleaner. All under 'shaded' dir is now generated. HBASE-16567 Upgrade to protobuf-3.1.x Regenerate all protos in this module with protoc3. Redo ByteStringer to use new pb3.1.0 unsafebytesutil instead of HBaseZeroCopyByteString HBASE-16264 Figure how to deal with endpoints and shaded pb Shade our protobufs. Do it in a manner that makes it so we can still have in our API references to com.google.protobuf (and in REST). The c.g.p in API is for Coprocessor Endpoints (CPEP) This patch is Tactic #4 from Shading Doc attached to the referenced issue. Figuring an appoach took a while because we have Coprocessor Endpoints mixed in with the core of HBase that are tough to untangle (FIX). Tactic #4 (the fourth attempt at addressing this issue) is COPY all but the CPEP .proto files currently in hbase-protocol to a new module named hbase-protocol-shaded. Generate .protos again in the new location and then relocate/shade the generated files. Let CPEPs keep on with the old references at com.google.protobuf.* and org.apache.hadoop.hbase.protobuf.* but change the hbase core so all instead refer to the relocated files in their new location at org.apache.hadoop.hbase.shaded.com.google.protobuf.*. Let the new module also shade protobufs themselves and change hbase core to pick up this shaded protobuf rather than directly reference com.google.protobuf. This approach allows us to explicitly refer to either the shaded or non-shaded version of a protobuf class in any particular context (though usually context dictates one or the other). Core runs on shaded protobuf. CPEPs continue to use whatever is on the classpath with com.google.protobuf.* which is pb2.5.0 for the near future at least. See above cited doc for follow-ons and downsides. In short, IDEs will complain about not being able to find the shaded protobufs since shading happens at package time; will fix by checking in all generated classes and relocated protobuf in a follow-on. Also, CPEPs currently suffer an extra-copy as marshalled from non-shaded to shaded. To fix. Finally, our .protos are duplicated; once shaded, and once not. Pain, but how else to reveal our protos to CPEPs or C++ client that wants to talk with HBase AND shade protobuf. Details: Add a new hbase-protocol-shaded module. It is a copy of hbase-protocol i with all relocated offset from o.a.h.h. to o.a.h.h.shaded. The new module also includes the relocated pb. It does not include CPEPs. They stay in their old location. Add another module hbase-endpoint which has in it all the endpoints that ship as part of hbase -- at least the ones that are not entangled with core such as AccessControl and Auth. Move all protos for these CPEPs here as well as their unit tests (mostly moving a bunch of stuff out of hbase-server module) Much of the change looks like this: -import org.apache.hadoop.hbase.protobuf.ProtobufUtil; -import org.apache.hadoop.hbase.protobuf.generated.ClusterIdProtos; +import org.apache.hadoop.hbase.protobuf.shaded.ProtobufUtil; +import org.apache.hadoop.hbase.shaded.protobuf.generated.ClusterIdProtos; In HTable and in HBaseAdmin, regularize the way Callables are used and also hide protobuf usage as much as possible moving it up into Callable super classes or out to utility classes. Still TODO is adding in of retries, etc., but can wait on procedure which will redo all this. Also in HTable and HBaseAdmin as well as in HRegionServer and Server, be explicit when using non-shaded protobuf. Do the full-path so it is clear. This is around endpoint coprocessors registration of services and execution of CPEP methods. Shrunk ProtobufUtil by moving methods used by one CPEP only back to the CPEP either into Client class or as new Util class; e.g. AccessControlUtil. There are actually two versions of ProtobufUtil now; a shaded one and a subset that is used by CPEPs doing non-shaded work. Made it so hbase-common no longer depends on hbase-protocol (with Matteo's help) R*Converter classes got moved down under shaded package -- they are for internal use only. There are no non-shaded versions of these classes. D hbase-client/src/main/java/org/apache/hadoop/hbase/client/AbstractRegionServerCallable D RetryingCallableBase Not used anymore and we have too many tiers of Callables so removed/cleaned-up. A ClientServicecallable Had to add this one. RegionServerCallable was made generic so it could be used for a few Interfaces (Client and Admin). Then added ClientServiceCallable to implement RegionServerCallable with the Client Interface.
2016-10-04 00:37:32 -04:00
NOTE: 'install' above whereas other proto generation only needs 'compile'
NOTE: Unlike elsehwere the above command does NOT install this modules jar
into the repo., intentionally. The jar made by the above is a scratch jar
that is part of the process that gets us to a set of files to check in;
it is not for consumption. Run mvn install without the '-Pcompile-protobuf'
option to get this modules' artifact installed in your repo!
When finished, the content of src/main/java/org/apache/hadoop/hbase/shaded
will have been updated. Make sure all builds and then carefully
check in the changes. Files may have been added or removed
by the steps above.
The protobuf version used internally by hbase differs from what
is used over in the CPEP hbase-protocol module but mvn takes care
of ensuring we have the right protobuf in place so you don't have to.
If you have patches for the protobuf, add them to
src/main/patches directory. They will be applied after
protobuf is shaded and unbundled into src/main/java.