In the past couple months we've made through most of the vanilla features in AutoRest.Java v4. At this point, we are planning for the next phase of work. We want to make a few changes in the AutoRest.Java structure according to
- The changes in Track 2 azure-core & azure-core-mgmt structure
- The long-term ownership changes
The goal is to define clear ownership in the long term and easy integration with azure-core, azure-core-mgmt, etc.
The AutoRest Java in master branch is designed in 3 levels
| Generator | Argument | Runtime | Usage |
|---|---|---|---|
| Vanilla | --java |
client-runtime | None, for community |
| Azure | --azure-arm |
azure-client-runtime | Track 1 data plane |
| Fluent | --fluent--generate-interfaces |
azure-client-runtime azure-arm-client-runtime |
Track 1 fluent premium Track 1 fluent lite |
Vanilla supports the basic operations defined in Swagger 2.0 spec. Azure overrides some behaviors to support Azure paging, HEAD operations, etc. It also has Azure ARM specific logic to support ARM LRO and to figure out what models should inherit from ARM base classes ( Resource, ProxyResource, or SubResource).
Fluent changes the name of these resources, and responses to XxxInner (which gives the best name Xxx to fluent premium and lite to be built on top).
Fluent lite then generates a simple form of the fluent convenience layer.
- Split the features in Azure gen to Vanilla gen and fluent gen - management library specific features will be moved to Fluent, for example, ARM specific LRO, base Resource classes; common features used also by data plane team will be moved vanilla, for example, paging, polling.
- Inner renaming can be moved to the front as an optional pre processing step.
The proposed structure looks like the following
| Plugin | Argument | Runtime | Usage |
|---|---|---|---|
| javanamer | --java (or a new arg) |
N/A | Java specific renamings & tweaks |
| fluentnamer | --fluent (or a new arg) |
N/A | Fluent specific renamings & tweaks |
| javagen (Vanilla) | --java |
azure-core | Track 2 data plane |
| fluentgen (Fluent) | --fluent--generate-interfaces |
azure-core-mgmt | Track 2 fluent premium Track 2 fluent lite |
The namers are a pre-processing step before the vanilla generator to pre-process the names. If --fluent is turned on, Inner will be appended to Resource types and response types. Also, types that should inherit from Resource/ProxyResource/SubResource but don't have the inheritance should also be fixed here.
For Vanilla, it will look similar to v2:
For Fluent, the vanilla generator no longer contains the code to add "Inner" or change the inheritance to Resource/ProxyResource/SubResource on models. The vanilla generator will only take care of the core generation. In order to add "Inner" and add inheritance, we will add a pre-processing step to feed the vanilla generator with a "fluent code model" with all the renamings and hierachies completed.
And finally for fluent lite, we generate the same interface as v2:
In the long term, the ADP-Java team will own the vanilla generator, responsible for the core features in code generation. This will ensure the data plane libraries are getting all the scenarios/protocols supported. The management library team will own the pre-processing transformer and the fluent generator, with contributions welcome to the vanilla generator. This will allow the management libraries team to own more management specific features. This structure also better aligns with the azure-core and azure-core-mgmt structure.
For ADP team, the next tasks are
- Finish supporting all vanilla tests in test server
- Support model flattening, payload flattening and grouping
- Start building data plane SDKs with the new generator
- Help management libraries team to set up the new structure
- Help management libraries team with azure-core-mgmt readiness
For management libraries team, the next tasks are
- Finish management specific features in azure-core-mgmt (maybe also merge in the fluent lite base classes?)
- Build corresponding code generation in fluent generator (e.g. ARM specific LRO)
- Build pre-processing transformer to add Inner suffixes and resource inheritance
- Start building management SDKs with the new generator