Extensive (is) option

[dmdashenkov]

This PR introduces an improvement to the message marker interface declaration. This PR fixes core-java/#911.

Summary

Previously, the only possibility to mark a message with a marker interface was to generate the interface with the help of protoc itself.

From now on, it is possible for marker interfaces to be handcrafted, instead of generated.

Handcrafted Interfaces

In order to declare that a message Java class should implement an interface, the user should annotate it with (is) option as follows:

message Student {
    option (is).java_type = "org.example.customer.FreemiumCustomer";

    string institution_name = 1;
    // ...
}

message OpenSourceCustomer {
    option (is).java_type = "org.example.customer.FreemiumCustomer";

    string company_name = 1;
    // ...
}

Now, in Java, declare org.example.customer.FreemiumCustomer interface:

package org.example.customer;

public interface FreemiumCustomer {

    default String getInstitutionOrCompanyName() {
        // Use Java or Protobuf reflection to obtain the value.
    }
}

The interface may have any methods and/or extend any other interfaces as long as it does not introduce new abstract methods to the message class. If the method is already present in the end class or has a default implementation, it is allowed.

Generated Interfaces

In order to generate the marker interface, the (is).generate option field should be set to true (the default value is false):

message Rgb {
    option (is) = {java_type: "Color", generate: true};

   // ...
}

message Cmyk {
    option (is).java_type = "Color";

   // ...
}

Note that it is sufficient to specify generate = true only once. This detail may be omitted on further message declarations. However, it is OK to specify to generate the interface on all the messages.

(every_is) Option

The (every_is) option is a "brother" of the (is) option targeting an entiere file instead of a single message type. The API of (every_is) is the same as the API of (is).

[codecov]

Codecov Report

Merging #248 into master will increase coverage by 0.03%.
The diff coverage is 91.3%.

@@             Coverage Diff              @@
##             master     #248      +/-   ##
============================================
+ Coverage     64.55%   64.59%   +0.03%     
- Complexity      575      579       +4     
============================================
  Files           309      309              
  Lines          8098     8106       +8     
  Branches        557      559       +2     
============================================
+ Hits           5228     5236       +8     
  Misses         2758     2758              
  Partials        112      112

[dmdashenkov]

@armiol, PTAL.

[armiol]

@dmdashenkov LGTM. Let's revert the changes to Gradle binaries in the root. And address a comment before merging.

[armiol]

This sentence seems to be a new paragraph, as it's about how to reference a type.