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<BinaryData> methodCallWithResponse(String param1, String param2, BinaryData body, RequestOptions options);

Mono<Response<BinaryData>> methodCallWithResponse(String param1, String param2, BinaryData 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

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, BinaryData body, RequestOptions options);

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, BinaryData 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

See Partial Update.