Protocol Methods Evolving

Protocol Methods - Envolving

Difference between protocol methods and traditional high level methods

The protocol methods AutoRest-Java generates look like this:

Response<ResponseContent> methodCallWithResponse(String param1, String param2, RequestContent body, RequestOptions options, Context context);

Mono<Response<ResponseContent>> methodCallWithResponse(String param1, String param2, RequestContent body, RequestOptions options);

Compared to the high level methods, here are some of the advantages protocol methods have against breaking changes:

1. Only required parameters are generated on the method signature - additions or removals of optional parameters will not affect protocol methods
2. There are no models or enums in protocol method parameters - users are expected to provide their own String valued enum (with assistance from Javadocs) and build their own JSON request body. The breaking changes in these areas won't affect protocol methods
3. There are no models or errors in protocol method responses - users are expected to decide on the error status and parse the response JSON themselves. The breaking changes in response models, and response status code definitions won't affect protocol methods

Evolution

Service Driven Evolution

New Operations

When the service adds a new operation, we generate a method for it. This operation will have a new name and so it will be generated as a new method on the SDK, so there is no impact to existing methods.

Changes to Response

Protocol methods do not inspect the body or the status code of a response and so any changes made by the service team have no impact on the SDK itself.

Changes to the Request Body

Protocol methods do not inspect the body of a request so any changes the service team makes to the shape of the body of a request do not have any impact on the SDK itself.

Adding New Optional Parameters

Optional parameters are provided on RequestOptions through addQueryParam() and addHeader() methods. Therefore any changes made by the service have no impact on the SDK itself.

Developer Driven Evolution

When convenience methods are added, we expect our clients to contain both convenience methods and the protocol methods:

Foo methodCall(String param1, String param2, Bar body);
Foo methodCall(String param1, String param2, Bar body, String optionalParam1, int operationParam2);
Response<Foo> methodCallWithResponse(String param1, String param2, Bar body, String optionalParam1, int operationParam2, Context context);
Response<BinaryData> methodCallWithResponse(String param1, String param2, RequestContent body, RequestOptions options, Context context);

Mono<Foo> methodCall(String param1, String param2, Bar body);
Mono<Foo> methodCall(String param1, String param2, Bar body, String optionalParam1, int operationParam2);
Mono<Response<Foo>> methodCallWithResponse(String param1, String param2, Bar body, String optionalParam1, int operationParam2);
Mono<Response<BinaryData>> methodCallWithResponse(String param1, String param2, RequestContent body, RequestOptions options);

The convenience methods call the protocol methods underneath, assemble the RequestOptions object as needed, and handle the serialization / deserialization work. The hand crafted methods must be defined before all the protocol methods - leaving the protocol methods at the bottom of the file. This is to simplify code generation as explained below.

Generate code in files with hand-written code

When developers add hand-written convenience code to the files, generation becomes difficult in order not to erase the hand written code. To re-generate the protocol methods, the current flag to use is --low-level-client. The files specified in the --output-folder will be analyzed to identity which methods were auto-generated and which were not - and only overwrite the ones that were auto-generated.

The specific details of how this works is still pending codegen design. In the short term, if existing code is detected, AutoRest-Java will only overwrite the methods starting from an agreed comment message:

// GENERATED CODE BELOW - MODIFICATIONS WILL BE LOST

If such comment is not detected, AutoRest-Java will add all the protocol methods to the bottom of the class after all the existing methods.