### Logging Output Example

Source: https://github.com/actions/setup-java/blob/main/_autodocs/action-interface.md

An example of the logging output produced during the Java installation process, showing details like distribution, version, and installation path.

```text
Java configuration:
  Distribution: temurin
  Version: 17.0.5
  Path: /opt/hostedtoolcache/Java/temurin/17.0.5/x64
```

--------------------------------

### Example Usage of setupJava

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-installer.md

Demonstrates how to use the setupJava method to install a specific Java version and handle potential errors. Ensure the Java distribution is correctly obtained before calling setupJava.

```typescript
import {getJavaDistribution} from './distributions/distribution-factory';

const distribution = getJavaDistribution('temurin', {
  version: '17',
  architecture: 'x64',
  packageType: 'jdk',
  checkLatest: false
});

if (distribution) {
  try {
    const result = await distribution.setupJava();
    console.log(`Installed: ${result.version} at ${result.path}`);
    // JAVA_HOME is now set and PATH updated
  } catch (error) {
    console.error('Failed to set up Java:', error);
  }
}
```

--------------------------------

### Example JavaInstallerResults

Source: https://github.com/actions/setup-java/blob/main/_autodocs/types.md

An example of the JavaInstallerResults object. This shows a successfully installed Java version and its corresponding filesystem path.

```typescript
const result: JavaInstallerResults = {
  version: '17.0.5',
  path: '/opt/hostedtoolcache/Java/temurin/17.0.5/x64'
};
```

--------------------------------

### Shell Command Example

Source: https://github.com/actions/setup-java/blob/main/_autodocs/README.md

Example of a shell command, typically used for package installation or script execution.

```bash
# Shell commands
npm install
```

--------------------------------

### Execute Java Installation

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-models.md

Installs the Java Development Kit and returns the installation results, including the version and the installation path.

```typescript
const result: JavaInstallerResults = await distribution.setupJava();
// {
//   version: '17.0.5+8',
//   path: '/opt/hostedtoolcache/Java/...' 
// }
```

--------------------------------

### Example JavaInstallerOptions

Source: https://github.com/actions/setup-java/blob/main/_autodocs/types.md

An example of how to instantiate the JavaInstallerOptions interface. This configuration specifies Java version 17.0.3, x64 architecture, JDK package type, and disables checking for the latest version.

```typescript
const options: JavaInstallerOptions = {
  version: '17.0.3',
  architecture: 'x64',
  packageType: 'jdk',
  checkLatest: false
};
```

--------------------------------

### Base Installer Methods

Source: https://github.com/actions/setup-java/blob/main/_autodocs/SUMMARY.txt

Details the JavaBase abstract class and its methods for orchestrating Java setup, version resolution, and caching.

```APIDOC
## JavaBase Abstract Class

### Description
An abstract class providing core logic for Java installation and environment setup.

### Methods
- **setupJava()**: Orchestrates the Java installation process.
- **resolveVersion()**: Resolves the specified Java version.
- **cacheJava()**: Manages Java caching mechanisms.
- **createError()**: Creates and formats error objects.
- **setupEnvironment()**: Configures the execution environment for Java.
```

--------------------------------

### Example Usage of getJavaDistribution

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/distribution-factory.md

Demonstrates how to use the getJavaDistribution function to create a Temurin distribution installer and then use it to set up Java. Ensure necessary imports are included.

```typescript
import {getJavaDistribution} from './distributions/distribution-factory';
import {JavaInstallerOptions} from './distributions/base-models';

// Create a Temurin distribution installer
const installerOptions: JavaInstallerOptions = {
  version: '17.0.0',
  architecture: 'x64',
  packageType: 'jdk',
  checkLatest: false
};

const distribution = getJavaDistribution('temurin', installerOptions);

if (distribution) {
  // Use the distribution installer
  const result = await distribution.setupJava();
  console.log(`Installed Java ${result.version} at ${result.path}`);
} else {
  console.error('Distribution not supported');
}

```

--------------------------------

### Setup Java with Check Latest Enabled

Source: https://github.com/actions/setup-java/blob/main/README.md

Installs a specific Java version (25) using the Temurin distribution and enables the `check-latest` flag to ensure the most up-to-date version is used. This may lead to slower setup times due to potential downloads.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '25'
    check-latest: true
- run: java HelloWorldApp.java
```

--------------------------------

### Usage of Setup Java Action Outputs

Source: https://github.com/actions/setup-java/blob/main/_autodocs/action-interface.md

Demonstrates how to use the outputs from the setup-java action in subsequent steps of a GitHub Actions workflow.

```yaml
- uses: actions/setup-java@v5
  id: setup
  with:
    distribution: 'temurin'
    java-version: '17'

- run: |
    echo "Version: ${{ steps.setup.outputs.version }}"
    echo "Path: ${{ steps.setup.outputs.path }}"
```

--------------------------------

### Example JavaInstallerOptions Usage

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-models.md

Demonstrates how to create and use a JavaInstallerOptions object to instantiate a Java distribution. Ensure necessary imports are included.

```typescript
import {JavaInstallerOptions} from './distributions/base-models';

const options: JavaInstallerOptions = {
  version: '17.0.3',
  architecture: 'x64',
  packageType: 'jdk',
  checkLatest: false
};

// Passed to installer constructor:
const distribution = new TemurinDistribution(options);
```

--------------------------------

### Abstract Method to Download and Install Java Package

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-installer.md

Subclasses must implement this method to handle the download, extraction, and installation of a Java package. It returns a promise with the installed version and its path.

```typescript
protected abstract downloadTool(
  javaRelease: JavaDownloadRelease
): Promise<JavaInstallerResults>
```

--------------------------------

### Install Multiple JDKs with Toolchains

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

Installs multiple JDK versions by calling setup-java sequentially. Subsequent calls extend the toolchains declaration, making all specified Java versions available.

```yaml
steps:
- uses: actions/setup-java@v5
  with:
    distribution: '<distribution>'
    java-version: |
      8
      11

- uses: actions/setup-java@v5
  with:
    distribution: '<distribution>'
    java-version: '15'
```

--------------------------------

### Install Java from a local file

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

Use the 'jdkfile' distribution type to install a manually downloaded JDK package. Ensure the file path is accessible to the runner.

```yaml
steps:
- run: |
    download_url="https://github.com/AdoptOpenJDK/openjdk11-binaries/releases/download/jdk-11.0.10%2B9/OpenJDK11U-jdk_x64_linux_hotspot_11.0.10_9.tar.gz"
    wget -O $RUNNER_TEMP/java_package.tar.gz $download_url
- uses: actions/setup-java@v5
  with:
    distribution: 'jdkfile'
    jdkFile: ${{ runner.temp }}/java_package.tar.gz
    java-version: '11.0.0'
    architecture: x64
    
- run: java -cp java HelloWorldApp
```

--------------------------------

### XML Example

Source: https://github.com/actions/setup-java/blob/main/_autodocs/README.md

Example of generated XML content, such as settings.xml or toolchains.xml files.

```xml
<!-- Generated XML files (settings.xml, toolchains.xml) -->
<settings></settings>
```

--------------------------------

### Simple Java Setup

Source: https://github.com/actions/setup-java/blob/main/_autodocs/configuration.md

Basic configuration for setting up a specific Java distribution and version. Use this for straightforward Java project builds.

```yaml
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '17'
```

--------------------------------

### Generated Maven settings.xml Files

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

Examples of the settings.xml files generated by the setup-java action for different deployment targets.

```xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>github</id>
      <username>${env.GITHUB_ACTOR}</username>
      <password>${env.GITHUB_TOKEN}</password>
    </server>
    <server>
      <id>gpg.passphrase</id>
      <passphrase>${env.GPG_PASSPHRASE}</passphrase>
    </server>
  </servers>
</settings>
```

```xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>maven</id>
      <username>${env.MAVEN_USERNAME}</username>
      <password>${env.MAVEN_CENTRAL_TOKEN}</password>
    </server>
    <server>
      <id>gpg.passphrase</id>
      <passphrase>${env.MAVEN_GPG_PASSPHRASE}</passphrase>
    </server>
  </servers>
</settings>
```

--------------------------------

### Basic Java 17 Setup

Source: https://github.com/actions/setup-java/blob/main/_autodocs/README.md

Sets up Java 17 with Temurin distribution and caches Maven dependencies.

```yaml
name: Test with Java 17

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v5
        with:
          distribution: 'temurin'
          java-version: '17'
          cache: 'maven'
```

--------------------------------

### setupJava Method Signature

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-installer.md

The main entry point for setting up a Java environment. It returns a promise that resolves to the installed Java version and its path.

```typescript
public async setupJava(): Promise<JavaInstallerResults>
```

--------------------------------

### Environment Variables Example Output

Source: https://github.com/actions/setup-java/blob/main/_autodocs/configuration.md

Illustrates the environment variables set by the setup-java action, including JAVA_HOME, version-specific JAVA_HOME, and PATH modifications.

```bash
JAVA_HOME=/opt/hostedtoolcache/Java/temurin/17.0.5/x64
JAVA_HOME_17_X64=/opt/hostedtoolcache/Java/temurin/17.0.5/x64
PATH=/opt/hostedtoolcache/Java/temurin/17.0.5/x64/bin:...
```

--------------------------------

### Install Custom JDK with Toolchains

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

Installs a custom JDK from a provided URL and adds it to the toolchains. This generates a Toolchains entry with specified version, vendor, and ID.

```yaml
- run: |
    download_url="https://example.com/java/jdk/6u45-b06/jdk-6u45-linux-x64.tar.gz"
    wget -O $RUNNER_TEMP/java_package.tar.gz $download_url
- uses: actions/setup-java@v5
  with:
    distribution: 'jdkfile'
    jdkFile: ${{ runner.temp }}/java_package.tar.gz
    java-version: '1.6'
    architecture: x64
```

--------------------------------

### Example Cache Key Value

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/cache.md

A concrete example of a cache key, showing the expected values for each component.

```text
setup-java-Linux-x64-maven-1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
```

--------------------------------

### Java Version Format Examples

Source: https://github.com/actions/setup-java/blob/main/_autodocs/types.md

Examples illustrating the Java versioning format, which follows semantic versioning with optional build metadata. Internally normalized to SemVer format with '+' for build metadata.

```plaintext
17
17.0
17.0.3
17.0.3+5
17.0.3-ea
17.0.3-ea.5
```

```plaintext
17.0.3-ea.5
17.0.3-ea
```

--------------------------------

### Auto-download and install latest JDK

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

Dynamically fetch the latest JDK release and semver version at runtime before installing with setup-java. Requires 'jq' to parse API responses.

```yaml
   steps:
      - name: fetch latest temurin JDK
        id: fetch_latest_jdk
        run: |
          major_version={{ env.JAVA_VERSION }} # Example 16 or 21 or 22
          cd $RUNNER_TEMP
          response=$(curl -s "https://api.github.com/repos/adoptium/temurin${major_version}-binaries/releases")
          latest_jdk_download_url=$(echo "$response" | jq -r '.[0].assets[] | select(.name | contains("jdk_x64_alpine-linux") and endswith(".tar.gz")) | .browser_download_url')
          curl -Ls "$latest_jdk_download_url" -o java_package.tar.gz
          latest_jdk_json_url=$(jdk_download_url "$response" | jq -r '.[0].assets[] | select(.name | contains("jdk_x64_alpine-linux") and endswith(".tar.gz.json")) | .browser_download_url')
          latest_semver_version=$(curl -sL $latest_jdk_json_url | jq -r 'version.semver')
          echo "java_version=$latest_semver_version" >> "$GITHUB_OUTPUT"

      - uses: actions/setup-java@v5
        with:
          distribution: 'jdkfile'
          jdkFile: ${{ runner.temp }}/java_package.tar.gz
          java-version: {{ steps.fetch_latest_jdk.outputs.java_version }}
          architecture: x64
       - run: java -cp java HelloWorldApp
```

--------------------------------

### Parse Installer Options

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-models.md

Parses input from the action to create JavaInstallerOptions. Ensure 'version' is a valid SemVer range.

```typescript
const installerOptions: JavaInstallerOptions = {
  architecture: core.getInput('architecture'),
  packageType: core.getInput('java-package'),
  checkLatest: getBooleanInput('check-latest', false),
  version: '17.0.3'
};
```

--------------------------------

### Main Action Function Signature

Source: https://github.com/actions/setup-java/blob/main/_autodocs/action-interface.md

The main entry point for the setup-java action, responsible for orchestrating the Java installation process.

```typescript
async function run(): void
```

--------------------------------

### Install Specific Java Version with setup-java

Source: https://github.com/actions/setup-java/blob/main/_autodocs/errors.md

Use this snippet to install a specific Java version required by your project. Ensure the `java-version` input matches the version specified in your `pom.xml`.

```yaml
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '17'  # Must match pom.xml requirement
```

--------------------------------

### GitHub Actions Workflow YAML Example

Source: https://github.com/actions/setup-java/blob/main/_autodocs/README.md

Example of a GitHub Actions workflow YAML snippet, demonstrating the use of an action.

```yaml
# GitHub Actions workflow YAML
- uses: actions/setup-java@v5
```

--------------------------------

### Supported Java Version Formats

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

Examples of valid version strings for the java-version input.

```text
major versions: 8, 11, 16, 17, 21
more specific versions: 8.0.282+8, 8.0.232, 11.0, 11.0.4, 17.0
early access (EA) versions: 15-ea, 15.0.0-ea
versions with specified distribution: openjdk64-11.0.2
LTS versions : temurin-21.0.5+11.0.LTS
```

--------------------------------

### Build Main Action with NCC

Source: https://github.com/actions/setup-java/blob/main/_autodocs/action-interface.md

Compiles the main setup action using @vercel/ncc, bundling TypeScript into a single JavaScript file.

```bash
npm run build

ncc build -o dist/setup src/setup-java.ts
```

--------------------------------

### Install custom Java distribution from local file

Source: https://github.com/actions/setup-java/blob/main/docs/switching-to-v2.md

Use the jdkfile distribution type to install a Java package from a local file path on the runner.

```yaml
steps:
- run: |
    download_url="https://github.com/AdoptOpenJDK/openjdk11-binaries/releases/download/jdk-11.0.10%2B9/OpenJDK11U-jdk_x64_linux_hotspot_11.0.10_9.tar.gz"
    wget -O $RUNNER_TEMP/java_package.tar.gz $download_url
- uses: actions/setup-java@v2
  with:
    distribution: 'jdkfile'
    jdkFile: ${{ runner.temp }}/java_package.tar.gz
    java-version: '11.0.0'
    architecture: x64
```

--------------------------------

### Example JavaDownloadRelease

Source: https://github.com/actions/setup-java/blob/main/_autodocs/types.md

An example of the JavaDownloadRelease interface, representing metadata for a specific Java package. This includes the canonical version string and the direct download URL.

```typescript
const release: JavaDownloadRelease = {
  version: '17.0.5',
  url: 'https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.5%2B8/OpenJDK17U-jdk_x64_linux_hotspot_17.0.5_8.tar.gz'
};
```

--------------------------------

### Example Cache Key Format

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/cache.md

Illustrates the format of a generated cache key, which includes platform, architecture, package manager ID, and a hash of dependency files.

```text
setup-java-<RUNNER_OS>-<arch>-<id>-<fileHash>
```

--------------------------------

### Example Version Not Found Error Message

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-installer.md

An example of the error message generated by createVersionNotFoundError, showing details about the requested version, distribution, and available versions.

```text
No matching version found for SemVer '17.0.999'.
Distribution: temurin
Package type: jdk
Architecture: x64
Available versions: 17.0.1, 17.0.2, 17.0.3, 17.0.4, 17.0.5, ... (showing first 50 of 100+ versions, enable debug mode to see all)
```

--------------------------------

### Correct Distribution Input for setup-java

Source: https://github.com/actions/setup-java/blob/main/_autodocs/errors.md

Use a supported distribution name when setting the 'distribution' input. This example shows the correct usage for 'temurin'.

```yaml
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'  # Correct
    java-version: '17'
```

--------------------------------

### Verify Java Installation Path

Source: https://github.com/actions/setup-java/blob/main/_autodocs/errors.md

Use these commands to check if the `JAVA_HOME` environment variable is set correctly and to list the contents of the Java installation directory. This helps diagnose 'jdk home must exist or be set' errors.

```bash
echo $JAVA_HOME
ls -la $JAVA_HOME
```

--------------------------------

### Generated XML for New Toolchains File

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/toolchains.md

Example of the XML structure generated when creating a new toolchains.xml file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd">
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>17.0.5</version>
      <vendor>temurin</vendor>
      <id>temurin_17.0.5</id>
    </provides>
    <configuration>
      <jdkHome>/opt/hostedtoolcache/Java/17.0.5/x64</jdkHome>
    </configuration>
  </toolchain>
</toolchains>
```

--------------------------------

### Provide Java Version or Version File Input

Source: https://github.com/actions/setup-java/blob/main/_autodocs/errors.md

Ensure either 'java-version' or 'java-version-file' input is provided. This specifies the Java version to be installed.

```yaml
# Option 1: Explicit version
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '17'

# Option 2: Version file
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version-file: '.java-version'
```

--------------------------------

### JavaInstallerOptions Interface

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-models.md

Defines the configuration options for initializing a Java distribution installer. Specify version, architecture, package type, and whether to check for the latest version.

```typescript
export interface JavaInstallerOptions {
  version: string;
  architecture: string;
  packageType: string;
  checkLatest: boolean;
}
```

--------------------------------

### downloadTool

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-installer.md

Abstract method for downloading and installing a Java package. Subclasses must implement this to handle the download, extraction, and caching process.

```APIDOC
## downloadTool

### Description
Abstract method that subclasses must implement to download and install the Java package.

### Method Signature
```typescript
protected abstract downloadTool(javaRelease: JavaDownloadRelease): Promise<JavaInstallerResults>
```

### Parameters
#### Path Parameters
- **javaRelease** (JavaDownloadRelease) - Required - Object with `version` and `url` of the Java package to download.

### Return Type
`Promise<JavaInstallerResults>`

```typescript
{
  version: string;  // The installed version
  path: string;     // Path to the installed Java root
}
```
```

--------------------------------

### Instantiate Java Distribution

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-models.md

Selects and instantiates a Java distribution based on provided options. The 'jdkFile' parameter is used for local file installations.

```typescript
const distribution = getJavaDistribution(
  'temurin',           // distribution name
  installerOptions,    // contains all config
  undefined            // jdkFile (local file only)
);
```

--------------------------------

### Example of Renaming Windows Archive

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/util.md

Shows how to use renameWinArchive to append a .zip extension to a file path, which also renames the file on disk.

```typescript
let archive = '/tmp/OpenJDK17';
archive = renameWinArchive(archive);
// Returns: '/tmp/OpenJDK17.zip'
// And the file is physically renamed on disk
```

--------------------------------

### Setup Java Action Outputs Schema

Source: https://github.com/actions/setup-java/blob/main/_autodocs/action-interface.md

Defines the schema for outputs available from the setup-java action, including distribution, version, path, and cache-hit status.

```yaml
outputs:
  distribution:
    description: 'Distribution of Java that has been installed'
  
  version:
    description: 'Actual version of Java environment that has been installed'
  
  path:
    description: 'Path to where Java environment has been installed'
  
  cache-hit:
    description: 'Boolean value to indicate exact cache match'
```

--------------------------------

### Setup-java Directory Structure for Distributions

Source: https://github.com/actions/setup-java/blob/main/docs/adrs/0000-v2-setup-java.md

Illustrates the proposed directory structure for separating distribution-specific logic in setup-java v2. New distributions can be added under the 'distributions/' directory.

```yaml
 ∟ src/
    installer.ts # core installer logic
    distributions/
        ∟ adoptium/ # adoptium (formerly AdoptOpenJDK) specific logic
        ∟ zulu/ # zulu specific logic
        ∟ # future distributions will be added here 
```

--------------------------------

### Helper Function Signature: installVersion

Source: https://github.com/actions/setup-java/blob/main/_autodocs/action-interface.md

The signature for the `installVersion` helper function, which handles the installation of a specific Java version and Maven toolchain configuration.

```typescript
async function installVersion(
  version: string,
  options: installerInputsOptions,
  toolchainId = 0
): Promise<void>
```

--------------------------------

### setupJava()

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-installer.md

The main entry point for setting up a Java environment. This method orchestrates the process of finding, downloading, extracting, and caching a Java version, as well as setting up the necessary environment variables.

```APIDOC
## setupJava()

### Description
Main entry point for setting up a Java environment. Orchestrates finding the Java version (from cache or remote), downloading if necessary, extracting, caching in the toolcache, and setting environment variables.

### Method Signature
```typescript
public async setupJava(): Promise<JavaInstallerResults>
```

### Return Type
`Promise<JavaInstallerResults>`

Returns a promise that resolves to an object with the following structure:

```typescript
{
  version: string;  // The actual installed Java version (e.g., '17.0.3')
  path: string;     // Absolute path to the Java installation root
}
```

### Behavior
1. Checks for the requested version in the GitHub Actions toolcache.
2. Uses the cached version if found and `checkLatest` is `false`.
3. Attempts to fetch the latest available version from the remote distribution server if not found or `checkLatest` is `true`.
4. Implements automatic retry logic with exponential backoff (up to 4 attempts, 2-second delay).
5. Handles retryable network errors (timeouts, connection resets, DNS failures, HTTP 429/502/503/504).
6. Saves newly downloaded versions to the toolcache.
7. Appends `Contents/Home` postfix on macOS if present.
8. Sets `JAVA_HOME` environment variable and updates `PATH`.
9. Exports version-specific and architecture-specific environment variables (e.g., `JAVA_HOME_17_X64`).
10. Sets action outputs: `distribution`, `version`, `path`.

### Throws
- `Error` with message `'Failed to resolve Java version'` when no version can be found.
- Network/HTTP errors when download fails after all retries.

### Error Handling Details
- HTTP 403: Logs "Permission denied or access restricted".
- HTTP 429: Logs rate limit exceeded warning and retries.
- HTTP 502/503/504: Retryable.
- Network timeouts (ETIMEDOUT, ECONNRESET, ENOTFOUND, ECONNREFUSED): Retryable.
- Aggregate errors from Node.js (e.g., DNS lookup failures): Parsed and logged with endpoint/port information.

### Example Usage
```typescript
import {getJavaDistribution} from './distributions/distribution-factory';

const distribution = getJavaDistribution('temurin', {
  version: '17',
  architecture: 'x64',
  packageType: 'jdk',
  checkLatest: false
});

if (distribution) {
  try {
    const result = await distribution.setupJava();
    console.log(`Installed: ${result.version} at ${result.path}`);
    // JAVA_HOME is now set and PATH updated
  } catch (error) {
    console.error('Failed to set up Java:', error);
  }
}
```
```

--------------------------------

### Toolcache Search Example

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-installer.md

Illustrates how the findInToolcache method might match different version requests to cached Java installations, considering stability filters.

```typescript
// If user requests '17.0.3', this might find 'Java_temurin_jdk/17.0.3-1/x64'
// If user requests '17', this might find 'Java_temurin_jdk/17.0.5-3/x64'
// If user requests '17-ea', this only finds early-access versions
```

--------------------------------

### Recommended Permissions for Setup-Java Action

Source: https://github.com/actions/setup-java/blob/main/README.md

This snippet shows the recommended permissions to grant the setup-java action. It allows the action to read repository contents for checking out code and installing dependencies.

```yaml
permissions:
  contents: read # access to check out code and install dependencies
```

--------------------------------

### Restore Cache in Setup Phase

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/cache.md

This TypeScript code snippet demonstrates calling the 'restore' function from the cache module during the setup phase of the Java action. It's executed after Java is installed and before user build commands, aiming to restore Maven dependencies, Gradle caches, or sbt libraries.

```typescript
if (cache && isCacheFeatureAvailable()) {
  await restore(cache, cacheDependencyPath);
}
```

--------------------------------

### Set up Java and Publish with Gradle

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

Configures Java 11 and publishes packages using Gradle. Ensure USERNAME and PASSWORD environment variables match your build.gradle configuration.

```yaml
jobs:

  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6

    - name: Set up JDK 11
      uses: actions/setup-java@v5
      with:
        distribution: '<distribution>'
        java-version: '11'

    - name: Build with Gradle
      run: gradle build

    - name: Publish to GitHub Packages
      run: gradle publish
      env:
        USERNAME: ${{ github.actor }}
        PASSWORD: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Version-Specific Java Environment Variables

Source: https://github.com/actions/setup-java/blob/main/_autodocs/action-interface.md

Illustrates environment variables for multi-JDK setups, where JAVA_HOME is defined for specific versions (e.g., JAVA_HOME_17_X64), enabling easy switching between different Java installations.

```bash
JAVA_HOME_17_X64=/opt/hostedtoolcache/Java/temurin/17.0.5/x64
JAVA_HOME_11_X64=/opt/hostedtoolcache/Java/11.0.15/x64
```

--------------------------------

### Get Java Distribution Factory Function Signature

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/distribution-factory.md

This is the signature for the getJavaDistribution factory function. It takes the distribution name, installer options, and an optional local JDK file path as input.

```typescript
export function getJavaDistribution(
  distributionName: string,
  installerOptions: JavaInstallerOptions,
  jdkFile?: string
): JavaBase | null

```

--------------------------------

### Configure Java and Maven Deployment Workflow

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

A complete YAML workflow example for setting up Java, building with Maven, and deploying to GitHub Packages and Maven Central.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6
    - name: Set up JDK 11
      uses: actions/setup-java@v5
      with:
        distribution: '<distribution>'
        java-version: '11'

    - name: Build with Maven
      run: mvn -B package --file pom.xml

    - name: Publish to GitHub Packages Apache Maven
      run: mvn deploy
      env:
        GITHUB_TOKEN: ${{ github.token }} # GITHUB_TOKEN is the default env for the password

    - name: Set up Apache Maven Central
      uses: actions/setup-java@v5
      with: # running setup-java again overwrites the settings.xml
        distribution: 'temurin'
        java-version: '11'
        server-id: maven # Value of the distributionManagement/repository/id field of the pom.xml
        server-username: MAVEN_USERNAME # env variable for username in deploy
        server-password: MAVEN_CENTRAL_TOKEN # env variable for token in deploy
        gpg-private-key: ${{ secrets.MAVEN_GPG_PRIVATE_KEY }} # Value of the GPG private key to import
        gpg-passphrase: MAVEN_GPG_PASSPHRASE # env variable for GPG private key passphrase

    - name: Publish to Apache Maven Central
      run: mvn deploy
      env:
        MAVEN_USERNAME: maven_username123
        MAVEN_CENTRAL_TOKEN: ${{ secrets.MAVEN_CENTRAL_TOKEN }}
        MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
```

--------------------------------

### Java Installer Results Structure

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-installer.md

Defines the structure of the JavaInstallerResults object, containing the installed version and the root path to the installed Java.

```typescript
{
  version: string;
  path: string;
}
```

--------------------------------

### Accessing Setup-Java Action Outputs

Source: https://github.com/actions/setup-java/blob/main/_autodocs/action-interface.md

Demonstrates how to use the `id` attribute to reference outputs from the setup-java action in subsequent workflow steps. Outputs like version, path, and cache status can be accessed using the `steps.<id>.outputs.<output_name>` syntax.

```yaml
- uses: actions/setup-java@v5
  id: setup-java  # Add ID to reference outputs
  with:
    distribution: 'temurin'
    java-version: '17'

- run: |
    echo "Installed version: ${{ steps.setup-java.outputs.version }}"
    echo "Installation path: ${{ steps.setup-java.outputs.path }}"
    echo "Cache hit: ${{ steps.setup-java.outputs.cache-hit }}"
```

--------------------------------

### Configure Multi-JDK Build with setup-java

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/toolchains.md

Use a multiline input for `java-version` to set up multiple JDKs. The action generates a `toolchains.xml` file with entries for each specified version.

```yaml
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: |
      11
      17
      21
```

--------------------------------

### Install Custom Java Architecture

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

Specifies a custom architecture for the Java installation.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
  with:
    distribution: '<distribution>'
    java-version: '11'
    architecture: x86 # optional - default value derived from the runner machine
- run: java -cp java HelloWorldApp
```

--------------------------------

### Specify Java Version via File

Source: https://github.com/actions/setup-java/blob/main/_autodocs/configuration.md

Sets up Java by referencing a version defined in a file (e.g., .java-version, .tool-versions, .sdkmanrc). This is useful for maintaining consistency across different environments.

```yaml
uses: actions/checkout@v4

uses: actions/setup-java@v5
with:
  distribution: 'temurin'
  java-version-file: '.java-version'
```

--------------------------------

### JavaInstallerResults Type

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-installer.md

Defines the structure of the results returned by the setupJava method, including the installed version and its installation path.

```typescript
{
  version: string;  // The actual installed Java version (e.g., '17.0.3')
  path: string;     // Absolute path to the Java installation root
}
```

--------------------------------

### TypeScript Source Code Example

Source: https://github.com/actions/setup-java/blob/main/_autodocs/README.md

Example of TypeScript source code, often used for defining interfaces or types.

```typescript
// TypeScript source code
export interface Example {}
```

--------------------------------

### Ensure Repository Checkout Before Setup-Java

Source: https://github.com/actions/setup-java/blob/main/_autodocs/errors.md

The `actions/checkout` action must run before `actions/setup-java` to ensure that dependency files are available for cache key computation.

```yaml
- uses: actions/checkout@v4

- uses: actions/setup-java@v5
  with:
    cache: 'maven'
```

--------------------------------

### Set up Java and Build with Maven

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

Configures Java 11 and builds a project using Maven. Use 'settings-path' to specify a unique location for the settings.xml file when using self-hosted runners with multiple shared runners.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6
    - name: Set up JDK 11 for Shared Runner
      uses: actions/setup-java@v5
      with:
        distribution: '<distribution>'
        java-version: '11'
        server-id: github # Value of the distributionManagement/repository/id field of the pom.xml
        settings-path: ${{ github.workspace }} # location for the settings.xml file

    - name: Build with Maven
      run: mvn -B package --file pom.xml

    - name: Publish to GitHub Packages Apache Maven
      run: mvn deploy -s $GITHUB_WORKSPACE/settings.xml
      env:
        GITHUB_TOKEN: ${{ github.token }}
```

--------------------------------

### JavaInstallerResults Interface

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/base-models.md

Represents the outcome of a Java installation, including the exact version installed and its filesystem path. This path is used for setting JAVA_HOME.

```typescript
export interface JavaInstallerResults {
  version: string;
  path: string;
}
```

--------------------------------

### Download and Use Local JDK File

Source: https://github.com/actions/setup-java/blob/main/_autodocs/errors.md

If the local JDK file is not present, download it first using 'actions/download-artifact' and then specify its path in 'setup-java'.

```yaml
- uses: actions/download-artifact@v3
  with:
    name: jdk-artifact

- uses: actions/setup-java@v5
  with:
    distribution: 'jdkfile'
    jdkFile: './jdk-artifact/jdk.tar.gz'
    java-version: '17'
```

--------------------------------

### Specify Java Distribution in setup-java

Source: https://github.com/actions/setup-java/blob/main/docs/adrs/0000-v2-setup-java.md

Use the 'distribution' input to select the desired OpenJDK distribution. This is a required input in v2.

```yaml
  with:
    java-version: '11'
    distribution: adoptium
```

--------------------------------

### Example Java Compilation Error

Source: https://github.com/actions/setup-java/blob/main/_autodocs/action-interface.md

An example of a Java compilation error that the problem matcher is designed to parse. This format allows GitHub to surface the error effectively.

```bash
src/Main.java:10: error: cannot find symbol
```

--------------------------------

### Install GnuPG on Different Operating Systems

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/gpg.md

Provides package manager commands to install GnuPG on Ubuntu/Debian, macOS, and Windows. This is necessary if GPG is not pre-installed on a custom GitHub Actions runner.

```bash
# Ubuntu/Debian
apt-get install gnupg
```

```bash
# macOS
brew install gnupg
```

```bash
# Windows (via Chocolatey)
choco install gnupg
```

--------------------------------

### Import GPG Private Key in Setup Phase

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/gpg.md

Imports a private GPG key using the gpg utility and saves its fingerprint to action state. This is used after Maven settings.xml is configured if a GPG private key is provided.

```typescript
if (gpgPrivateKey) {
  core.info('Importing private gpg key');
  const keyFingerprint = (await gpg.importKey(gpgPrivateKey)) || '';
  core.saveState(constants.STATE_GPG_PRIVATE_KEY_FINGERPRINT, keyFingerprint);
}
```

--------------------------------

### getJavaDistribution()

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/distribution-factory.md

Factory function that instantiates the appropriate Java distribution installer based on the distribution name and installer options. It returns an instance of a class extending JavaBase or null if the distribution is not supported.

```APIDOC
## getJavaDistribution()

### Description
Factory function that instantiates the appropriate Java distribution installer. It returns an instance of a class extending `JavaBase` that implements the installer for the specified distribution, or `null` if the distribution name is not recognized or supported.

### Method Signature
```typescript
getJavaDistribution(distributionName: string, installerOptions: JavaInstallerOptions, jdkFile?: string): JavaBase | null
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Function Parameters
- **distributionName** (`string`) - Required - The name of the distribution to instantiate. Must match one of the `JavaDistribution` enum values (e.g. 'temurin', 'zulu', 'adopt-hotspot'). Case-sensitive.
- **installerOptions** (`JavaInstallerOptions`) - Required - Configuration object containing version, architecture, package type, and check-latest flag. See [JavaInstallerOptions](./base-models.md#javainstalleroptions).
- **jdkFile** (`string`) - Optional - Path to a local JDK archive file. Required only when `distributionName` is 'jdkfile'.

### Return Type
`JavaBase | null`

Returns an instance of a class extending `JavaBase` that implements the installer for the specified distribution. Returns `null` if the distribution name is not recognized or supported.

### Supported Distribution Mappings
| Input String | Returns |
|---|---|
| 'jdkfile' | `LocalDistribution` |
| 'adopt' or 'adopt-hotspot' | `AdoptDistribution` with Hotspot |
| 'adopt-openj9' | `AdoptDistribution` with OpenJ9 |
| 'temurin' | `TemurinDistribution` with Hotspot |
| 'zulu' | `ZuluDistribution` |
| 'liberica' | `LibericaDistributions` |
| 'microsoft' | `MicrosoftDistributions` |
| 'semeru' | `SemeruDistribution` |
| 'corretto' | `CorrettoDistribution` |
| 'oracle' | `OracleDistribution` |
| 'dragonwell' | `DragonwellDistribution` |
| 'sapmachine' | `SapMachineDistribution` |
| 'graalvm' | `GraalVMDistribution` |
| 'jetbrains' | `JetBrainsDistribution` |
| Any other string | `null` |

### Example Usage
```typescript
import {getJavaDistribution} from './distributions/distribution-factory';
import {JavaInstallerOptions} from './distributions/base-models';

// Create a Temurin distribution installer
const installerOptions: JavaInstallerOptions = {
  version: '17.0.0',
  architecture: 'x64',
  packageType: 'jdk',
  checkLatest: false
};

const distribution = getJavaDistribution('temurin', installerOptions);

if (distribution) {
  // Use the distribution installer
  const result = await distribution.setupJava();
  console.log(`Installed Java ${result.version} at ${result.path}`);
} else {
  console.error('Distribution not supported');
}
```
```

--------------------------------

### Install Multiple Java Versions

Source: https://github.com/actions/setup-java/blob/main/_autodocs/README.md

Installs multiple Java Development Kits (JDKs) and caches Maven dependencies. The build process can then use toolchains to select the appropriate JDK per plugin.

```yaml
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: |
      11
      17
      21
    cache: 'maven'

- run: mvn verify  # Uses toolchains to select JDK per plugin
```

--------------------------------

### Sign and Publish with GPG Workflow

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/auth.md

This workflow shows how to sign and publish artifacts using GPG with setup-java. It configures Maven with GPG passphrase and imports the private key.

```yaml
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '17'
    server-id: 'github'
    server-username: 'GITHUB_ACTOR'
    server-password: 'GITHUB_TOKEN'
    gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
    gpg-passphrase: 'GPG_PASSPHRASE'

- run: mvn deploy
  env:
    GITHUB_ACTOR: ${{ github.actor }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
```

--------------------------------

### Install Multiple JDKs

Source: https://github.com/actions/setup-java/blob/main/README.md

Installs multiple Java Development Kits (JDKs) within a single job. All configured versions are added to the PATH, with the last one set as the default. Other versions can be accessed via JAVA_HOME environment variables.

```yaml
steps:
  - uses: actions/setup-java@v5
    with:
      distribution: '<distribution>'
      java-version: |
        8
        11
        15
```

--------------------------------

### Install Custom Java Package Type

Source: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md

Configures a custom Java package type using the java-package parameter.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
  with:
    distribution: '<distribution>'
    java-version: '11'
    java-package: jdk # optional (jdk or jre) - defaults to jdk
- run: java -cp java HelloWorldApp
```

--------------------------------

### Publish to GitHub Packages Workflow

Source: https://github.com/actions/setup-java/blob/main/_autodocs/api-reference/auth.md

This workflow demonstrates how to publish artifacts to GitHub Packages using setup-java. It configures Maven with credentials from environment variables.

```yaml
- uses: actions/checkout@v4

- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '17'
    server-id: 'github'
    server-username: 'GITHUB_ACTOR'
    server-password: 'GITHUB_TOKEN'

- run: mvn deploy
  env:
    GITHUB_ACTOR: ${{ github.actor }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Cache Maven Dependencies

Source: https://github.com/actions/setup-java/blob/main/README.md

This example demonstrates how to cache Maven dependencies. The `cache-dependency-path` can be specified for specific pom.xml files.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '25'
    cache: 'maven'
    cache-dependency-path: 'sub-project/pom.xml'
- name: Build with Maven
  run: mvn -B package --file pom.xml
```