[Java] Collection types and their usage

[Laird Nelson]

I'm new to gRPC's Java implementation.

I've generated the gRPC API for Helm's server-side component, Tiller, in Java.  You can see the Javadocs here: https://microbean.github.io/microbean-helm/apidocs/index.html  The packages under the hapi.* prefix are generated off of Helm's .proto files (https://github.com/kubernetes/helm/tree/master/_proto).

My question is around some of the collection types and methods that gRPC Java generates.  I'll pick an arbitrary example.  

Here is a Chart: https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.html

Here is its builder: https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.Builder.html

As you can see, logically a Chart can have "dependencies", which are other Charts (subcharts).  

Here is a "getter" on the Chart: https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.html#getDependenciesList--  Now, that getter I understand.  It returns a List.  (Is the list mutable? The documentation doesn't say, nor does the gRPC Java page have anything about the code it generates.)

But when I'm building this Chart, I don't understand the various "setters" in the builder.  For example, here's one that adds a Chart.Builder as a dependency: https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.Builder.html#addDependencies-hapi.chart.ChartOuterClass.Chart.Builder-  If I add a dependency this way, by adding another builder, must I call build() on this sub-builder, or will a build() on the top-level builder cascade down?

Then here's one that adds a Chart: https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.Builder.html#addDependencies-hapi.chart.ChartOuterClass.Chart-  Is that a better way to do it?  If so, then why the addDependencies() method that takes a Chart.Builder?

Then there's a method called addAllDependencies(): https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.Builder.html#addAllDependencies-java.lang.Iterable-

I've noticed that if I call this a couple times, the toString() representation, at any rate, of the top-level Chart seems to contain a JSON-like structure for each time I've called the method.  Is it intended that this method should only be called once?

Finally, there are various getters that seem to indicate that perhaps all these things are unrelated.  For example, I see https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.Builder.html#getDependenciesBuilderList--, which would seem to imply that subcharts added as builders are distinct from subcharts added as true Chart instances.

Thanks for any pointers.

Best,

Laird

[Carl Mastrangelo]

Responses inline

One other thing:  Proto fields are typically named singular (dependency rather than dependencies) because the generated code is awkward.  Java turns this into getDependencyList(), which reads better then getDependenciesList().

On Tuesday, July 11, 2017 at 9:27:08 AM UTC-7, Laird Nelson wrote:

I'm new to gRPC's Java implementation.

I've generated the gRPC API for Helm's server-side component, Tiller, in Java.  You can see the Javadocs here: https://microbean.github.io/microbean-helm/apidocs/index.html  The packages under the hapi.* prefix are generated off of Helm's .proto files (https://github.com/kubernetes/helm/tree/master/_proto).

My question is around some of the collection types and methods that gRPC Java generates.  I'll pick an arbitrary example.  

Here is a Chart: https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.html

Here is its builder: https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.Builder.html

As you can see, logically a Chart can have "dependencies", which are other Charts (subcharts).  

Here is a "getter" on the Chart: https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.html#getDependenciesList--  Now, that getter I understand.  It returns a List.  (Is the list mutable? The documentation doesn't say, nor does the gRPC Java page have anything about the code it generates.)

Builder lists are mutable.  If you call the method twice, you'll get the same one.

 

But when I'm building this Chart, I don't understand the various "setters" in the builder.  For example, here's one that adds a Chart.Builder as a dependency: https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.Builder.html#addDependencies-hapi.chart.ChartOuterClass.Chart.Builder-  If I add a dependency this way, by adding another builder, must I call build() on this sub-builder, or will a build() on the top-level builder cascade down?

You don't need to call build on any of the intermediate builders.  (There is one special exception to this for extensions, but those are mostly gone in Proto3.  It would be very surprising to run into this corner case).  

 

Then here's one that adds a Chart: https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.Builder.html#addDependencies-hapi.chart.ChartOuterClass.Chart-  Is that a better way to do it?  If so, then why the addDependencies() method that takes a Chart.Builder?

None of the ways are really better.  They exist to be as easily chainable as possible, but don't feel obliged to do it one one or another. 

 

Then there's a method called addAllDependencies(): https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.Builder.html#addAllDependencies-java.lang.Iterable-

I've noticed that if I call this a couple times, the toString() representation, at any rate, of the top-level Chart seems to contain a JSON-like structure for each time I've called the method.  Is it intended that this method should only be called once?

It's not actually JSON, but a text formatted Proto used for debugging.  DO NOT USE IT.  It is not wireformat stable, and breaks badly as the proto evolves.  If you want a JSon formatted version, use the JsonFormat class in the `util` directory.  

The toString() is meant for debugging.  

 

Finally, there are various getters that seem to indicate that perhaps all these things are unrelated.  For example, I see https://microbean.github.io/microbean-helm/apidocs/hapi/chart/ChartOuterClass.Chart.Builder.html#getDependenciesBuilderList--, which would seem to imply that subcharts added as builders are distinct from subcharts added as true Chart instances.

Again, these are just convenience methods.  They are all builders throughout the tree until you call build().