Getting Started Guidance

This document provides recommendations and guidance to accelerate the development of Aure client libraries for Java. On top of this document, there is considerably more guidance available at the following three places:

• Java Guidelines
• Azure SDK for Java Wiki
• Azure SDK for Java Contributing.md

Environment Setup

IDEs

The preferred IDE is IntelliJ IDEA. The free 'community' edition is more than adequate for our use cases.

Environment setup

Java

Currently our libraries are built and tested against JDK 8, JDK 11, JDK 17 and JDK 21. Therefore, it is encouraged to install the latest LTS JDK version (Java 21) on your development machine so that you may do local builds to validate your code.

If you do not have JDK installed on your development machine, consider downloading it from one of the following links (select the version that is appropriate for your OS and machine architecture):

• OpenJDK 8
• OpenJDK 11
• OpenJDK 17
• OpenJDK 21

Once Java is installed, add a JAVA_HOME environment variable to point to JDK installation location. Once this is done, you should be able to run java -version from your terminal and see a Java version printed out. If this fails, you will need to add JAVA_HOME to your PATH, by appending the following: %JAVA_HOME%\bin.

Maven

1. Download Maven zip file.
2. Unzip it to a folder.
3. Add MAVEN_HOME environment variable
4. Add MAVEN_HOME to your PATH by appending the following %MAVEN_HOME%\bin

You can now verify installation by running mvn -version from the terminal.

If you're using Windows Dev Drive you should also configure the environment variable MAVEN_OPTS to direct Maven to use a path on your Dev Drive as the Maven cache location. For example, if your D: drive is your Dev Drive you can configure MAVEN_OPTS to use D:\maven as your Maven cache location with MAVEN_OPTS: -Dmaven.repo.local=D:\maven. maven.repo.local is the MAVEN_OPTS configuration that specifies the Maven local cache location. Using this configuration will also configure other tools that leverage Maven, such as IntelliJ, to use this cache location as well.

Git

Because some of the filenames in our repo are long, if you are using Windows you should enable paths longer than 260 characters:

1. On Windows 10 using regedit go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem and set LongPathsEnabled to 1 (should be 0 by default)
2. In an administrator-privileged command prompt, run the following two commands:
   1. REG ADD HKLM\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1
   2. git config --global core.longpaths true

Adding a new module

The wiki has a document that details how to add a new module into the azure-sdk-for-java repo.

Building

There is good documentation about building the azure-sdk-for-java in the wiki, as well as in the contributing.md file.

Working with Autorest

AutoRest is the name of the tool we use to generate the communication layer that lies beneath the API we expose to our users. AutoRest saves us from having to write a lot of network communication code, and instead we can direct our focus towards building a great user experience on top of this generated code. Our goal should be to expose as little, and ideally none, of the generated code to the user.

AutoRest usage instructions for Java are documented on the wiki.

Testing

Mock tests

Mock test guidance is provided in the wiki.

Recorded / Playback tests

Test parallelization

Test parallelization guidance is provided in the wiki.

Performance Testing

Performance test instructions are documented on the wiki.

Release checklist

Before Beta 1

• Validate against the Java Design Guidelines
• Ensure User-Agent header is correctly formed based on the design guidelines.
• Ensure x-ms-azsdk-telemetry telemetry header is correctly formed for all service client calls.
• Ensure package name is correct with group and service name.
• Validate Maven pom file:
  • Ensure Maven group ID and artifact ID are correct and approved.
  • Ensure version string is correct (i.e. 'x.y.z-beta.1').
  • Any allowed dependencies are architect approved.
• Ensure a module-info.java file is present that exports the appropriate packages.
• Ensure all non-public API is in an 'implementation' package.
• Ensure all service client builder classes have all expected builder APIs for configuring pipelines, etc.
• Do ensure all sync APIs have 'withResponse' 'overloads' that accept a Context, and all async APIs translate from the Reactor Context to the Azure SDK Context.
• Do ensure all APIs appropriately support tracing, and that the tracing is correctly formatted.

After Beta 1

• Validate that user-agent header information is being correctly received into the telemetry dashboard.
• Validate that the x-ms-azsdk-telemetry telemetry header is being correctly received into the telemetry dashboard.

Before Beta 2

• Ensure all annotations are applied (@ServiceClient, @ServiceMethod, @Fluent, @ServiceClientBuilder, etc)
• Ensure all APIs are appropriately logging in terms of content and log level.

Before Beta 3

• Ensure a complete set of performance benchmarks have been developed and are integrated into the repo.

Before GA

• Validate JavaDoc completeness by generating HTML and reviewing all documentation. Ensure samples are included in all relevant places (client builders and client service methods).
• Validate that all CheckStyle, SpotBugs, Revapi, etc checks pass with only allowed suppressions / exclusions. All suppressions / exclusions must be identified and discussed prior to GA.
• Validate Maven pom file again (as per before beta 1).
• Ensure test coverage is sufficiently high and that any overrides that prevent build failure (due to test coverage being too low) are communicated and reviewed.