Developer Guide

AutoRest Java

AutoRest Java is the Java language generator for AutoRest.

As npm package, it is defined by the package.json located in project root, and the package.json in preprocessor, javagen, postprocessor, fluentnamer, fluentgen, androidgen.

As AutoRest plugin, it is defined by the YAML section in readme.md, located in the same folders of package.json.

Build and Unit Test

Build

Build is configured via Maven.

There is several build profiles:

• local profile. It is required to be enabled. It uses maven-assembly-plugin to combine project output to a single jar.
• testVanilla profile. It enables the integrated vanilla tests, which is the common ground for all modules.
• testAzure profile. It enables the integrated Azure tests, which tests handling of some advanced AutoRest Extensions for OpenAPI 2.0.
• testFluent profile. It enables the integrated Fluent tests, which tests generation of Fluent management SDKs for ARM.

Unit Test

Because the input of AutoRest Java is a complicated code model of the OpenAPI, it is relatively difficult to add unit tests.

There is unit tests under fluentgen. It depends on recorded YAML output of fluentnamer, and a mocked FluentGen.

Integrated Test

Vanilla tests and Azure tests both depends on AutoRest Test Server, which provides OpenAPI 2.0 swaggers and NodeJS test server which implements the swaggers.

The generated code is checked-in to the repository. generate or generate.bat script in project root will re-generate the code. CI will start the NodeJS test server and run the tests, which communicate with the test server.

Test server can be installed and ran locally.

npm install
npm run testserver-run

Fluent tests is different. It depends on the real OpenAPI 2.0 swaggers for ARM services.

The generated code is not checked-in. Instead, code is generated on-the-fly during the test, via prepare-tests.bat script.

CompilationTests relies on Java compiler to pin-down certain features of the generated code, while RuntimeTests executes the generated code and verify the result.

Use local AutoRest Java

Use --use option of the AutoRest to load the local AutoRest Java build (instead of the one downloaded from pre-release).

The name of @autorest/java in package.json makes sure that it is loaded when --java option is provided.

Pre-release

1. Update version in root package.json.
2. Run "Pre-release autorest.java" in GitHub Actions. Provide the same release version.
3. Update Release notes in GitHub Releases.

Logging

DO NOT log to stdout. AutoRest uses stdin and stdout as RPC channel for plugins.

For formal logging, use PluginLogger in pattern Logger logger = new PluginLogger(<PluginEntry>.getPluginInstance(), <Class>.class).

AutoRest

• AutoRest in the narrow sense is the command line tool (CLI) for the pipeline.
• AutoRest Core is the core functionality of the AutoRest pipeline. Its code is at core.
• AutoRest Modeler Four is the modeler extension. Its code is at modelerfour. AutoRest Java connects to the output of the modeler.

It is easy to get confused about AutoRest and AutoRest Core. If one run autorest --info, one might see below:

AutoRest code generation utility [cli version: 3.3.2; node: v12.16.1]
(C) 2018 Microsoft Corporation.
https://aka.ms/autorest

Showing All Installed Extensions

 Type       Extension Name                           Version      Location
 core       @autorest/core                           3.4.5        C:\Users\<user>\.autorest\@[email protected]
 core       @autorest/core                           3.5.1        C:\Users\<user>\.autorest\@[email protected]
 extension  @autorest/java                           4.0.30       C:\Users\<user>\.autorest\@[email protected]
 extension  @autorest/modelerfour                    4.18.1       C:\Users\<user>\.autorest\@[email protected]
 extension  @autorest/modelerfour                    4.19.3       C:\Users\<user>\.autorest\@[email protected]

The current installed AutoRest version is 3.3.2, while downloaded AutoRest Core version is 3.4.5 and 3.5.1. And downloaded Modeler Four version is 4.18.1 and 4.19.3, AutoRest Java version is 4.0.30.

Design on AutoRest Java

See Design.

Debug AutoRest Java

To enable debugging, first configure a remote JVM debugger. In IntelliJ, you can do this by going to Run -> Edit Configuration. On the configuration window, click on Add New Configuration -> Remote JVM Debug and configure the remote debugger. Set the debugger mode to "Attach to remote JVM", Transport to "Socket", Host to "localhost" and Port to "5005". Set the command line arguments to "-agentlib:jdwp=transport=dt_socket,server=y, suspend=n,address=*:5005".

After the remote debugger is configured, run autorest with this additional argument --java.debugger. The AutoRest process will block until the JVM debugger is attached, so, after the AutoRest process pauses, start the debugger which will connect to the remote debugger and this will hit the breakpoints set in the "Javagen" plugin. If you want to set up a breakpoint in a different plugin like preprocessor or postprocessor, you can change the argument to --preprocessor.debugger or postprocessor.debugger respectively.

Interactive UI to trace AutoRest pipeline

Running autorest with --interactive mode on will pop up a browser window to show an interactive UI of the AutoRest pipeline. This generally helps in identifying all the plugins that are executed, their order of execution, their inputs and outputs.