### Example: Download and install Java

Source: https://www.ekotov.pro/rJavaEnv/reference/java_install.html

Demonstrates downloading and installing a specific Java version using a temporary directory.

```R
if (FALSE) { # \dontrun{

# set cache dir to temporary directory
options(rJavaEnv.cache_path = tempdir())
# download, install and autoset environmnet variables for Java 17
java_17_distrib <- java_download(version = "17")
java_install(java_distrib_path = java_17_distrib, project_path = tempdir())
} # }
```

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

### Configuring Java Build Environment Example

Source: https://www.ekotov.pro/rJavaEnv/reference/java_build_env_set.html

Example workflow for downloading, installing, and configuring the environment to build rJava from source.

```R
# \donttest{
# Download and install Java 17
java_17_distrib <- java_download(version = "17", temp_dir = TRUE)
#> Detected platform: linux
#> Detected architecture: x64
#> You can change the platform and architecture by specifying the `platform` and
#> `arch` arguments.
#> Downloading Corretto Java 17...
#> Verifying sha256 checksum...
#> Checksum verified.
java_home_path <- java_install(
  java_distrib_path = java_17_distrib,
  project_path = tempdir(),
  autoset_java_env = FALSE # Manually set env
)
#> Java NA (amazon-corretto-17.0.20.8.1-linux-x64.tar.gz) for linux x64 installed
#> at /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17 and
#> symlinked to /tmp/Rtmp0PoKzI/rjavaenv/linux/x64/Corretto/native/NA

# Set up the build environment in the current session
java_build_env_set(java_home = java_home_path)
#> ✔ Build environment variables set for the current R session.
#> ℹ The environment is now set up to build Java-dependent packages from source.
#>   You can now run: `install.packages("rJava", type = "source")`
#> ! Please ensure your repository points to a source package repository (e.g.,
#>   https://cloud.r-project.org). Some repositories may serve pre-built binaries
#>   even when `type = "source"` is specified.
#> Warning: System dependencies required for building rJava from source on Linux.
#> ℹ On Debian/Ubuntu, you may need to install: libpcre2-dev, libdeflate-dev,
#>   libzstd-dev, liblzma-dev, libbz2-dev, zlib1g-dev, and libicu-dev.
#> ℹ Example installation command for Debian/Ubuntu:
#>   `sudo apt-get update && sudo apt-get install -y --no-install-recommends
#>   libpcre2-dev libdeflate-dev libzstd-dev liblzma-dev libbz2-dev zlib1g-dev
#>   libicu-dev && sudo rm -rf /var/lib/apt/lists/*`

# Now, install rJava from source
install.packages("rJava", type = "source", repos = "https://cloud.r-project.org")
#> Installing package into ‘/home/runner/work/_temp/Library’
#> (as ‘lib’ is unspecified)
# }
```

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

### Create Setup Helper Function

Source: https://www.ekotov.pro/rJavaEnv/articles/for-developers.html

Export a setup function to interactively guide users through Java installation and configuration.

```R
#' Install and Configure Java
#' @export
setup_java <- function() {
  # Interactive check and install
  rJavaEnv::java_ensure(version = 21, type = "min", install = TRUE)
  
  message("Java setup complete. Please RESTART your R session for changes to take effect.")
}
```

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

### Example of listing installed Java versions

Source: https://www.ekotov.pro/rJavaEnv/reference/java_list_installed.html

Demonstrates the default behavior of listing cached Java installations.

```R
# List the contents
java_list_installed()
#>                                                                    path
#> 1 /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17
#>   platform arch distribution backend version
#> 1    linux  x64     Corretto  native      17
```

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

### Quick Setup Functions

Source: https://www.ekotov.pro/rJavaEnv/reference/index.html

Functions for quickly installing and configuring Java in the current project or R session.

```APIDOC
## java_quick_install()

### Description
Download, install, and set Java in the current working or project directory.

## use_java()

### Description
Install a specified Java version and set the JAVA_HOME and PATH environment variables in the current R session.

## java_list_available()

### Description
List available Java versions.

## java_find_system()

### Description
Discover system-wide Java installations.

## java_valid_versions()

### Description
Retrieve valid Java versions.
```

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

### Examples of java_find_system

Source: https://www.ekotov.pro/rJavaEnv/reference/java_find_system.html

Demonstrates listing all system Java installations and using the cache for performance.

```R
# \donttest{
# List all system Java installations
java_find_system()
#>                            java_home version is_default
#> 1   /usr/lib/jvm/temurin-8-jdk-amd64       8      FALSE
#> 2  /usr/lib/jvm/temurin-11-jdk-amd64      11      FALSE
#> 3  /usr/lib/jvm/temurin-17-jdk-amd64      17      FALSE
#> 4 /usr/lib/jvm/java-21-openjdk-amd64      21      FALSE
#> 5  /usr/lib/jvm/temurin-21-jdk-amd64      21      FALSE
#> 6  /usr/lib/jvm/temurin-25-jdk-amd64      25      FALSE

# Use cache for faster repeated calls if you are using it in your R package
java_find_system(.use_cache = TRUE)
#>                            java_home version is_default
#> 1   /usr/lib/jvm/temurin-8-jdk-amd64       8      FALSE
#> 2  /usr/lib/jvm/temurin-11-jdk-amd64      11      FALSE
#> 3  /usr/lib/jvm/temurin-17-jdk-amd64      17      FALSE
#> 4 /usr/lib/jvm/java-21-openjdk-amd64      21      FALSE
#> 5  /usr/lib/jvm/temurin-21-jdk-amd64      21      FALSE
#> 6  /usr/lib/jvm/temurin-25-jdk-amd64      25      FALSE
# }
```

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

### Resolve Java 21 path example

Source: https://www.ekotov.pro/rJavaEnv/reference/java_resolve.html

Demonstrates retrieving the path to Java 21, triggering an installation if it is not already present.

```R
# \donttest{
# Get path to Java 21 (installing if necessary)
path <- java_resolve(version = 21, install = TRUE)
#> ℹ Checking system for existing Java installations...
#> ✔ Found valid system Java 21 at /usr/lib/jvm/java-21-openjdk-amd64
# }
```

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

### Execute a quick Java installation

Source: https://www.ekotov.pro/rJavaEnv/reference/java_quick_install.html

Demonstrates a basic installation call for Java 17, saving the files in a temporary directory.

```R
# \donttest{

# quick download, unpack, install and set in current working directory default Java version (21)
java_quick_install(17, temp_dir = TRUE)
# > Detected platform: linux
# > Detected architecture: x64
# > You can change the platform and architecture by specifying the `platform` and
# > `arch` arguments.
# > File already cached: amazon-corretto-17.0.20.8.1-linux-x64.tar.gz
# > Java distribution amazon-corretto-17.0.20.8.1-linux-x64.tar.gz already unpacked
# > at /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17
# > ℹ You have rJava loaded in the current session. rJava gets locked to the Java version that was active when it was first initialized.rJava is initialized when you: (1) call `library(rJava)`, (2) load a package that imports rJava, (3) use IDE autocomplete with `rJava::`, or (4) call any rJava function.This path-locking is a limitation of rJava itself. See: https://github.com/s-u/rJava/issues/25, https://github.com/s-u/rJava/issues/249, and https://github.com/s-u/rJava/issues/334Unless you restart the R session or run your code in a new R subprocess (using targets or callr), the new `JAVA_HOME` and `PATH` will not take effect.
# > ✔ Current R Session: JAVA_HOME and PATH set to /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17
# > ✔ Current R Project/Working Directory: JAVA_HOME and PATH set to '/home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17' in .Rprofile at '/tmp/Rtmp0PoKzI/rJavaEnv_project'
# > ℹ On Linux, for rJava to work correctly, `libjvm.so` was dynamically loaded in
# >   the current session.
# >   To make this change permanent for installing rJava-dependent packages from
# >   source, you may need to reconfigure Java.
# >   See <https://solutions.posit.co/envs-pkgs/using-rjava/#reconfigure-r> for
# >   details.
# >   If you have admin rights, run the following in your terminal:
# >   `R CMD javareconf
# >   JAVA_HOME=/home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17`
# >   If you do not have admin rights, run:
# >   `R CMD javareconf
# >   JAVA_HOME=/home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17
# >   -e`
# > Java NA (amazon-corretto-17.0.20.8.1-linux-x64.tar.gz) for linux x64 installed
# > at /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17 and
# > symlinked to
# > /tmp/Rtmp0PoKzI/rJavaEnv_project/rjavaenv/linux/x64/Corretto/native/NA
# }
```

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

### Download Java distribution examples

Source: https://www.ekotov.pro/rJavaEnv/reference/java_download.html

Examples demonstrating how to download specific versions, use default settings, and switch to the SDKMAN backend.

```R
# download distribution of Java version 17
java_download(version = "17", temp_dir = TRUE)

# download default Java distribution (version 21)
java_download(temp_dir = TRUE)

# download using SDKMAN backend
java_download(version = "21", backend = "sdkman", temp_dir = TRUE)
```

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

### Unpack Java Distribution Example

Source: https://www.ekotov.pro/rJavaEnv/reference/java_unpack.html

Example demonstrating downloading and unpacking a Java 17 distribution into a temporary cache directory.

```R
if (FALSE) { # \dontrun{

# set cache dir to temporary directory
options(rJavaEnv.cache_path = tempdir())

# download Java 17 distrib and unpack it into cache dir
java_17_distrib <- java_download(version = "17")
java_home <- java_unpack(java_distrib_path = java_17_distrib)

# set the JAVA_HOME environment variable in the current session
# to the cache dir without touching any files in the current project directory
java_env_set(where = "session", java_home = java_home)
} # }
```

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

### View cache path output examples

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv-step-by-step.qmd

Example outputs for the cache path on different operating systems.

```text
"C:\\Users\\user_name\\AppData\\Local/R/cache/R/rJavaEnv"
```

```text
"/Users/user_name/Library/Caches/org.R-project.R/R/rJavaEnv"
```

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

### Install Java Distribution

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv-step-by-step.qmd

Installs a Java distribution and optionally configures the environment automatically.

```R
java_install(
  java_distrib_path = java_8_distr,
  autoset_java_env = TRUE
)
```

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

### java_quick_install()

Source: https://www.ekotov.pro/rJavaEnv/index.html

Downloads, installs, and sets the Java environment in the current working or project directory.

```APIDOC
## java_quick_install()

### Description
Downloads, installs, and sets Java environment in the current working/project directory, all in one line of code.
```

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

### Install Linux System Dependencies

Source: https://www.ekotov.pro/rJavaEnv/articles/install-rjava-from-source.html

Installs required system libraries for building rJava on Debian/Ubuntu systems.

```bash
sudo apt-get update && sudo apt-get install -y --no-install-recommends libpcre2-dev libdeflate-dev libzstd-dev liblzma-dev libbz2-dev zlib1g-dev libicu-dev && sudo rm -rf /var/lib/apt/lists/*
```

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

### Install rJavaEnv

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv.qmd

Installation commands for the rJavaEnv package from CRAN or R-universe.

```R
install.packages("rJavaEnv")
```

```R
install.packages(
  'rJavaEnv',
  repos = c('https://e-kotov.r-universe.dev', 'https://cloud.r-project.org')
)
```

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

### Install Java

Source: https://www.ekotov.pro/rJavaEnv/articles/install-rjava-from-source.html

Installs a specific version of Java into the current project directory.

```R
java_quick_install(version = 21)
```

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

### Install rJavaEnv from GitHub

Source: https://www.ekotov.pro/rJavaEnv/index.html

Installation method for the development version directly from the GitHub repository using the remotes package.

```R
if (!requireNamespace("remotes", quietly = TRUE)) {
  install.packages("remotes")
}

remotes::install_github("e-kotov/rJavaEnv", force = TRUE)
```

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

### Quick Install Java JDK

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv.qmd

Downloads and installs the specified Java JDK version and configures the environment for the current project.

```R
library(rJavaEnv)
java_quick_install(version = 21)
```

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

### Install rJava from Source

Source: https://www.ekotov.pro/rJavaEnv/articles/install-rjava-from-source.html

Installs the rJava package from source, optionally forcing the CRAN repository.

```R
install.packages("rJava", type = "source")
```

```R
install.packages("rJava", type = "source", repos = "https://cloud.r-project.org")
```

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

### Configure Java installation parameters

Source: https://www.ekotov.pro/rJavaEnv/reference/java_quick_install.html

Defines the function signature for installing Java with specific version, distribution, and backend settings.

```R
java_quick_install(
  version = 21,
  distribution = "Corretto",
  backend = getOption("rJavaEnv.backend", "native"),
  project_path = NULL,
  platform = platform_detect()$os,
  arch = platform_detect()$arch,
  quiet = FALSE,
  temp_dir = FALSE
)
```

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

### Install rJavaEnv from R-multiverse

Source: https://www.ekotov.pro/rJavaEnv/index.html

Installation method for the latest development release using the R-multiverse repository.

```R
install.packages('rJavaEnv',
 repos = c('https://community.r-multiverse.org', 'https://cloud.r-project.org')
)
```

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

### Download, Install, and Configure Java Environment

Source: https://www.ekotov.pro/rJavaEnv/reference/java_env_set.html

Downloads Java 17, installs it to a temporary directory, and updates the current R session's environment variables. Note that rJava may lock to the initial Java version, requiring a session restart for changes to take effect.

```R
# \donttest{
# download, install Java 17
java_17_distrib <- java_download(version = "17", temp_dir = TRUE)
#> Detected platform: linux
#> Detected architecture: x64
#> You can change the platform and architecture by specifying the `platform` and
#> `arch` arguments.
#> File already cached: amazon-corretto-17.0.20.8.1-linux-x64.tar.gz
java_home <- java_install(
  java_distrib_path = java_17_distrib,
  project_path = tempdir(),
  autoset_java_env = FALSE
)
#> Java distribution amazon-corretto-17.0.20.8.1-linux-x64.tar.gz already unpacked
#> at /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17
#> Java NA (amazon-corretto-17.0.20.8.1-linux-x64.tar.gz) for linux x64 installed
#> at /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17 and
#> symlinked to /tmp/Rtmp0PoKzI/rjavaenv/linux/x64/Corretto/native/NA

# now manually set the JAVA_HOME and PATH environment variables in current session
java_env_set(
  where = "session",
  java_home = java_home
)
#> ℹ You have rJava loaded in the current session. rJava gets locked to the Java version that was active when it was first initialized.rJava is initialized when you: (1) call `library(rJava)`, (2) load a package that imports rJava, (3) use IDE autocomplete with `rJava::`, or (4) call any rJava function.This path-locking is a limitation of rJava itself. See: https://github.com/s-u/rJava/issues/25, https://github.com/s-u/rJava/issues/249, and https://github.com/s-u/rJava/issues/334Unless you restart the R session or run your code in a new R subprocess (using targets or callr), the new `JAVA_HOME` and `PATH` will not take effect.
#> ✔ Current R Session: JAVA_HOME and PATH set to /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17
#> ℹ On Linux, for rJava to work correctly, `libjvm.so` was dynamically loaded in
#>   the current session.
#>   To make this change permanent for installing rJava-dependent packages from
#>   source, you may need to reconfigure Java.
#>   See <https://solutions.posit.co/envs-pkgs/using-rjava/#reconfigure-r> for
#>   details.
#>   If you have admin rights, run the following in your terminal:
#>   `R CMD javareconf
#>   JAVA_HOME=/home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17`
#>   If you do not have admin rights, run:
#>   `R CMD javareconf
#>   JAVA_HOME=/home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17
#>   -e`
```

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

### Example Usage

Source: https://www.ekotov.pro/rJavaEnv/reference/java_check_version_cmd.html

Demonstrates calling the function to retrieve the major Java version.

```R
# \donttest{
java_check_version_cmd()
#> JAVA_HOME:
#> /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17
#> Java path:
#> /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17/bin/java
#> Java version: "openjdk version \"17.0.20\" 2026-07-21 LTS OpenJDK Runtime
#> Environment Corretto-17.0.20.8.1 (build 17.0.20+8-LTS) OpenJDK 64-Bit Server VM
#> Corretto-17.0.20.8.1 (build 17.0.20+8-LTS, mixed mode, sharing)"
#> [1] "17"
# }
```

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

### Provide Consent Example

Source: https://www.ekotov.pro/rJavaEnv/reference/rje_consent.html

Example of providing consent to prevent interruption by other functions.

```R
# \donttest{

# to provide consent and prevent other functions from interrupting to get the consent
rje_consent(provided = TRUE)
#> Consent for using rJavaEnv has already been provided.
# }
```

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

### Example of java_list_project

Source: https://www.ekotov.pro/rJavaEnv/reference/java_list_project.html

Demonstrates calling the function to list Java versions in the current project.

```R
# \donttest{
java_list_project()
#> ✖ No Java has been installed in the project.
# }
```

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

### java_quick_install(version, distribution, backend, project_path, platform, arch, quiet, temp_dir)

Source: https://www.ekotov.pro/rJavaEnv/reference/java_quick_install.html

Downloads, installs, and configures a Java environment for the current working or project directory.

```APIDOC
## java_quick_install

### Description
Downloads and installs a specified Java distribution and configures the environment for the current working or project directory.

### Usage
```r
java_quick_install(
  version = 21,
  distribution = "Corretto",
  backend = getOption("rJavaEnv.backend", "native"),
  project_path = NULL,
  platform = platform_detect()$os,
  arch = platform_detect()$arch,
  quiet = FALSE,
  temp_dir = FALSE
)
```

### Arguments
- **version** (string/numeric) - Optional - Java version specification (Major version, specific version, or SDKMAN identifier).
- **distribution** (string) - Optional - The Java distribution to download ("Corretto", "Temurin", or "Zulu"). Defaults to "Corretto".
- **backend** (string) - Optional - Download backend to use ("native" or "sdkman").
- **project_path** (string) - Optional - The project directory where Java should be installed. Defaults to current working directory.
- **platform** (string) - Optional - The platform for which to download the Java distribution.
- **arch** (string) - Optional - The architecture for which to download the Java distribution.
- **quiet** (logical) - Optional - Whether to suppress messages.
- **temp_dir** (logical) - Optional - Whether the file should be saved in a temporary directory.

### Value
Invisibly returns the path to the Java home directory.
```

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

### Install macOS Xcode Tools

Source: https://www.ekotov.pro/rJavaEnv/articles/install-rjava-from-source.html

Installs the Xcode Command Line Tools required for building on macOS.

```bash
xcode-select --install
```

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

### java_list_available()

Source: https://www.ekotov.pro/rJavaEnv/index.html

Lists all installable Java versions from supported backends.

```APIDOC
## java_list_available()

### Description
Lists all installable Java versions from supported backends (native vendor APIs or SDKMAN). Supports filtering by platform and architecture.
```

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

### java_install()

Source: https://www.ekotov.pro/rJavaEnv/index.html

Installs a Java distribution file into the current or user-specified project directory.

```APIDOC
## java_install()

### Description
Installs a Java distribution file into current (or user-specified) project directory.
```

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

### Example usage of local_java_env

Source: https://www.ekotov.pro/rJavaEnv/reference/local_java_env.html

Demonstrates how to use local_java_env with system2 and processx, including caching for repeated calls.

```R
if (FALSE) { # \dontrun{
# Using system2
my_tool_wrapper <- function() {
  rJavaEnv::local_java_env(version = 21)
  system2("java", "-version")
} # Environment restored automatically here

# Using processx
# run_java_jar <- function(jar_path, args) {
#  rJavaEnv::local_java_env(version = 21)
#  processx::run("java", c("-jar", jar_path, args))
# }

# With caching for repeated calls
# process_files <- function(files) {
#  for (f in files) {
#    rJavaEnv::local_java_env(version = 21, .use_cache = TRUE)
#   processx::run("java", c("-jar", "processor.jar", f))
#  }
# }
} # }
```

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

### Examples of java_list usage

Source: https://www.ekotov.pro/rJavaEnv/reference/java_list.html

Demonstrates listing different types of Java caches and project configurations.

```R
java_list("project")
#> ✖ No Java has been installed in the project.
java_list("installed")
#>                                                                    path
#> 1 /home/runner/.cache/R/rJavaEnv/installed/linux/x64/Corretto/native/17
#>   platform arch distribution backend version
#> 1    linux  x64     Corretto  native      17
java_list("distrib")
#> ✖ No Java distributions have been downloaded.
#> character(0)
```

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

### Install specific Java distribution

Source: https://www.ekotov.pro/rJavaEnv/index.html

Installs a specific version and distribution of Java instead of the default.

```R
rJavaEnv::java_quick_install(version = 17, distribution = "Temurin")
```

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

### Examples of use_java Usage

Source: https://www.ekotov.pro/rJavaEnv/reference/use_java.html

Demonstrates setting the cache directory, configuring Java for rJava packages, and switching versions for command-line tools. Note that rJava initialization must occur after calling use_java.

```R
if (FALSE) { # \dontrun{

# set cache directory for Java to be in temporary directory
options(rJavaEnv.cache_path = tempdir())

# For end users: Install and set Java BEFORE loading rJava packages
use_java(21)
# library(myRJavaPackage)  # Now uses Java 21

# For command-line Java tools (no rJava involved):
# Can switch versions between system calls
use_java(8)
system2("java", "-version")  # Shows Java 8
use_java(17)
system2("java", "-version")  # Shows Java 17

# WARNING: Do NOT do this with rJava packages:
# library(rJava)          # Initializes with system Java
# use_java(21)            # Too late! rJava is already locked
# rJava still uses the Java version from before use_java() call

} # }
```

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

### java_list_available(backend = "sdkman", platform = "all", arch = "all")

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv.qmd

Lists available Java versions for installation.

```APIDOC
## java_list_available

### Description
Lists available Java versions from the specified backend.

### Parameters
- **backend** (string) - Optional - The backend to query (default: "sdkman").
- **platform** (string) - Optional - The platform to filter by.
- **arch** (string) - Optional - The architecture to filter by.
```

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

### java_resolve(version = NULL, type = c("exact", "min"), distribution = "Corretto", backend = getOption("rJavaEnv.backend", "native"), install = TRUE, accept_system_java = TRUE, quiet = FALSE, cache_path = getOption("rJavaEnv.cache_path"), platform = platform_detect()$os, arch = platform_detect()$arch, .use_cache = FALSE)

Source: https://www.ekotov.pro/rJavaEnv/reference/java_resolve.html

Finds or installs a Java distribution and returns the path to JAVA_HOME.

```APIDOC
## java_resolve

### Description
Finds or installs a Java distribution and returns the path to JAVA_HOME. This function does not modify any environment variables.

### Parameters
- **version** (character/numeric) - Optional - Java version specification (Major version, specific version, or SDKMAN identifier).
- **type** (character) - Optional - "exact" (default) checks for exact version match; "min" checks for version >= version.
- **distribution** (character) - Optional - The Java distribution to download (defaults to "Corretto"). Ignored if version is a SDKMAN identifier.
- **backend** (character) - Optional - Download backend: "native" (default) or "sdkman".
- **install** (logical) - Optional - If TRUE (default), attempts to download/install if missing.
- **accept_system_java** (logical) - Optional - If TRUE (default), scans the system for existing Java installations.
- **quiet** (logical) - Optional - Suppress messages.
- **cache_path** (character) - Optional - Destination directory for downloads.
- **platform** (character) - Optional - Platform for download (defaults to current).
- **arch** (character) - Optional - Architecture for download (defaults to current).
- **.use_cache** (logical) - Optional - If TRUE, uses session-scoped cached results.

### Return Value
- **Character string** - The path to JAVA_HOME.

### Example
```r
# Get path to Java 21 (installing if necessary)
path <- java_resolve(version = 21, install = TRUE)
```
```

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

### java_list_installed()

Source: https://www.ekotov.pro/rJavaEnv/reference/java_list_installed.html

Lists the contents of the Java installations cache folder.

```APIDOC
## java_list_installed

### Description
Lists the contents of the Java installations cache folder.

### Usage
java_list_installed(output = c("data.frame", "vector"), quiet = TRUE, cache_path = getOption("rJavaEnv.cache_path"))

### Arguments
- **output** (character) - Optional - The format of the output: "data.frame" or "vector". Defaults to "data.frame".
- **quiet** (logical) - Optional - A logical value indicating whether to suppress messages. Defaults to TRUE.
- **cache_path** (character) - Optional - The destination directory to download the Java distribution to. Defaults to a user-specific data directory.

### Value
A data frame or character vector with the contents of the cache directory.

### Examples
java_list_installed()
```

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

### Package .onLoad Integration

Source: https://www.ekotov.pro/rJavaEnv/reference/java_check_compatibility.html

Example implementation for verifying Java version requirements during package loading.

```R
if (FALSE) { # \dontrun{
# In a package .onLoad:
.onLoad <- function(libname, pkgname) {
  rJavaEnv::java_check_compatibility(version = 21, action = "warn")
}
} # }
```

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

### Interactive Example for java_clear_distrib

Source: https://www.ekotov.pro/rJavaEnv/reference/java_clear_distrib.html

Demonstrates how to invoke the function within an interactive R session.

```R
if (interactive()) {
  java_clear_distrib()
}
```

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

### List Available Java Versions

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv.qmd

Commands to list Java versions available for download and installation.

```R
java_list_available()
```

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

### java_install(java_distrib_path, project_path = NULL, distribution = NULL, backend = NULL, autoset_java_env = TRUE, quiet = FALSE, force = FALSE)

Source: https://www.ekotov.pro/rJavaEnv/reference/java_install.html

Unpacks a Java distribution file into a cache directory and links the installation into a project directory, optionally setting JAVA_HOME and PATH.

```APIDOC
## java_install

### Description
Unpack Java distribution file into cache directory and link the installation into a project directory, optionally setting the JAVA_HOME and PATH environment variables to the Java version that was just installed.

### Arguments
- **java_distrib_path** (character) - Required - Path to the Java distribution file.
- **project_path** (character) - Optional - Project directory where Java should be installed. Defaults to current working directory.
- **distribution** (character) - Optional - The Java distribution name (e.g., "Corretto", "Temurin").
- **backend** (character) - Optional - The download backend used (e.g., "native", "sdkman").
- **autoset_java_env** (logical) - Optional - Whether to set the JAVA_HOME and PATH environment variables. Defaults to TRUE.
- **quiet** (logical) - Optional - Whether to suppress messages. Defaults to FALSE.
- **force** (logical) - Optional - Whether to overwrite an existing installation. Defaults to FALSE.

### Value
The path to the installed Java directory.
```

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

### java_list_available(backend, platform, arch, force, quiet)

Source: https://www.ekotov.pro/rJavaEnv/reference/java_list_available.html

Retrieves a list of all available installable Java versions from the specified backend(s).

```APIDOC
## java_list_available

### Description
Retrieves a list of all available installable Java versions from the specified backend(s). It returns a unified data frame with version details, vendors, and checksum availability.

### Usage
java_list_available(backend = c("both", "native", "sdkman"), platform = platform_detect()$os, arch = platform_detect()$arch, force = FALSE, quiet = FALSE)

### Arguments
- **backend** (Character vector) - Optional - Backends to query: "native", "sdkman", or "both" (default).
- **platform** (Character) - Optional - Platform OS. Defaults to current platform. Use "all" to list for all supported platforms.
- **arch** (Character) - Optional - Architecture. Defaults to current architecture. Use "all" to list for all supported architectures.
- **force** (Logical) - Optional - If TRUE, bypasses and refreshes the internal cache.
- **quiet** (Logical) - Optional - If TRUE, suppresses progress messages.

### Value
A data.frame with columns:
- **backend**: "native" or "sdkman"
- **vendor**: Java distribution name
- **major**: Major version number
- **version**: Full version string
- **platform**: Platform OS
- **arch**: Architecture
- **identifier**: Internal identifier
- **checksum_available**: Whether checksum verification is available
```

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

### Set Project Directory

Source: https://www.ekotov.pro/rJavaEnv/articles/install-rjava-from-source.html

Sets the working directory to a temporary location for the installation process.

```R
project_dir <- tempdir()
setwd(project_dir)
```

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

### Example usage of java_list_distrib

Source: https://www.ekotov.pro/rJavaEnv/reference/java_list_distrib.html

Demonstrates calling the function to list cached distributions.

```R
# \donttest{
  java_list_distrib()
#> ✖ No Java distributions have been downloaded.
#> character(0)
# }
```

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

### Listing Java Versions

Source: https://www.ekotov.pro/rJavaEnv/reference/java_list_available.html

Examples for retrieving Java versions for the current platform or across all supported platforms and architectures.

```R
if (FALSE) { # \dontrun{
# List all available versions for current platform
java_list_available()

# List all versions for all platforms (Pro users)
java_list_available(platform = "all", arch = "all")
} # }
```

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

### Example of unsetting Java build environment

Source: https://www.ekotov.pro/rJavaEnv/reference/java_build_env_unset.html

Demonstrates how to call the function to remove Java settings from the current project.

```R
# Remove Java build environment settings from the current project
java_build_env_unset()
#> ! No .Rprofile found in the project directory:
#>   /home/runner/work/rJavaEnv/rJavaEnv/docs/reference
```

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

### List Project Java Versions

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv-step-by-step.qmd

Lists all Java versions currently installed in the project directory.

```R
java_list_project()
```

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

### Retrieve and Refresh Java Versions

Source: https://www.ekotov.pro/rJavaEnv/reference/java_valid_versions.html

Examples demonstrating standard retrieval and forcing a cache refresh for Java versions.

```R
# \donttest{
  # Retrieve valid Java versions (cached if available) using Amazon Corretto endpoint
  versions <- java_valid_versions()

  # Force refresh the list of Java versions for Amazon Corretto
  versions <- java_valid_versions(distribution = "Corretto", force = TRUE)
# }
```

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

### Clear Java Project Symlinks Example

Source: https://www.ekotov.pro/rJavaEnv/reference/java_clear_project.html

Demonstrates how to invoke the function in an interactive R session.

```R
if (interactive()) {
  java_clear_project()
}
```

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

### Install Java distribution

Source: https://www.ekotov.pro/rJavaEnv/reference/java_install.html

Unpacks a Java distribution file into a specified project directory and optionally configures environment variables.

```R
java_install(
  java_distrib_path,
  project_path = NULL,
  distribution = NULL,
  backend = NULL,
  autoset_java_env = TRUE,
  quiet = FALSE,
  force = FALSE
)
```

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

### java_check_version_cmd()

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv.qmd

Checks if the current Java installation is correctly configured for command-line usage.

```APIDOC
## java_check_version_cmd

### Description
Verifies the Java installation path and version for command-line based R packages.
```

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

### Configure and view cache path

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv-step-by-step.qmd

Sets the global cache directory for Java installations and retrieves the current configuration.

```R
options(rJavaEnv.cache_path = "/path/to/your/desired/cache/folder")
```

```R
getOption("rJavaEnv.cache_path")
```

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

### Usage of java_find_system

Source: https://www.ekotov.pro/rJavaEnv/reference/java_find_system.html

Basic syntax for calling the function to scan for system Java installations.

```R
java_find_system(quiet = TRUE, .use_cache = FALSE)
```

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

### Usage of java_list_installed

Source: https://www.ekotov.pro/rJavaEnv/reference/java_list_installed.html

Defines the function signature and available parameters for listing cached Java installations.

```R
java_list_installed(
  output = c("data.frame", "vector"),
  quiet = TRUE,
  cache_path = getOption("rJavaEnv.cache_path")
)
```

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

### Install Java distribution into project

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv-step-by-step.qmd

Extracts and links a Java distribution. Setting autoset_java_env to FALSE requires manual configuration of environment variables.

```R
java_install(
  java_distrib_path = java_17_distr,
  autoset_java_env = FALSE
)
```

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

### java_find_system(quiet = TRUE, .use_cache = FALSE)

Source: https://www.ekotov.pro/rJavaEnv/reference/java_find_system.html

Scans the system for installed Java Development Kits (JDKs).

```APIDOC
## java_find_system

### Description
Scans the system for installed Java Development Kits (JDKs). This function only returns true system installations and excludes Java installations managed by rJavaEnv.

### Usage
java_find_system(quiet = TRUE, .use_cache = FALSE)

### Arguments
- **quiet** (logical) - Optional - If TRUE, suppresses informational messages.
- **.use_cache** (logical) - Optional - If TRUE, uses memoisation cache for the system scanning part. Default is FALSE.

### Value
A data frame with the following columns:
- **java_home** (character) - Path to the Java home directory.
- **version** (character) - Major Java version.
- **is_default** (logical) - TRUE if this matches the current system default Java.
```

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

### use_java(version, distribution, backend, cache_path, platform, arch, quiet, ._skip_rjava_check)

Source: https://www.ekotov.pro/rJavaEnv/reference/use_java.html

Sets the JAVA_HOME and PATH environment variables for the current R session to the specified Java version. If the version is not in the cache, it is downloaded and installed automatically.

```APIDOC
## use_java

### Description
Sets the specified Java version and updates the `JAVA_HOME` and `PATH` environment variables in the current R session. If the distribution is not present in the cache, it is downloaded and installed.

### Parameters
- **version** (string/numeric) - Optional - Java version specification (e.g., "21", "21.0.9", or SDKMAN identifier).
- **distribution** (string) - Optional - The Java distribution to download. Defaults to "Corretto". Ignored if version is an SDKMAN identifier.
- **backend** (string) - Optional - The download backend to use (e.g., "native", "sdkman").
- **cache_path** (string) - Optional - The destination directory for the Java distribution. Defaults to a user-specific data directory.
- **platform** (string) - Optional - The target platform. Defaults to current platform.
- **arch** (string) - Optional - The target architecture. Defaults to current architecture.
- **quiet** (logical) - Optional - Whether to suppress messages. Defaults to TRUE.
- **._skip_rjava_check** (logical) - Optional - Internal use only. If TRUE, skips the rJava initialization check.

### Returns
- **Logical** - Returns TRUE invisibly on success.
```

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

### Example of clearing the Java cache

Source: https://www.ekotov.pro/rJavaEnv/reference/java_clear_installed.html

Demonstrates how to invoke the function within an interactive R session.

```R
if (interactive()) {
  java_clear_installed()
}
```

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

### Example usage of java_clear

Source: https://www.ekotov.pro/rJavaEnv/reference/java_clear.html

Demonstrates clearing different types of Java caches in an interactive session.

```R
if (interactive()) {
  java_clear("project")
  java_clear("installed")
  java_clear("distrib")
}
```

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

### Debug Java Environment

Source: https://www.ekotov.pro/rJavaEnv/articles/for-developers.html

Use quiet = FALSE to inspect resolution steps, active versions, and system installations.

```R
# See all resolution steps
rJavaEnv::java_ensure(version = 21, quiet = FALSE)

# Check what Java is currently active
rJavaEnv::java_check_version_cmd(quiet = FALSE)

# See all system Java installations
rJavaEnv::java_find_system(quiet = FALSE)
```

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

### Initialize Java in scripts

Source: https://www.ekotov.pro/rJavaEnv/articles/multiple-java-with-targets-callr.qmd

Call use_java at the start of scripts executed by targets or callr to ensure the correct Java version is active.

```r
library(rJavaEnv)
use_java("17")
```

```r
rJavaEnv::use_java("17")
```

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

### Execute code with a specific Java version

Source: https://www.ekotov.pro/rJavaEnv/reference/with_rjava_env.html

Example of running a function that initializes rJava and retrieves the Java version in a subprocess.

```R
# \donttest{
# Run a function using Java 21 in a subprocess
result <- with_rjava_env(
  version = 21,
  func = function(x) {
    library(rJava)
    .jinit()
    .jcall("java.lang.System", "S", "getProperty", "java.version")
  },
  args = list(x = 1)
)
print(result)
#> [1] "21.0.11"
# }
```

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

### with_rjava_env(version, func, args, distribution, install, accept_system_java, quiet, libpath)

Source: https://www.ekotov.pro/rJavaEnv/reference/with_rjava_env.html

Runs the provided function in a fresh R subprocess where rJava has not yet been loaded, allowing for specific Java version enforcement.

```APIDOC
## with_rjava_env

### Description
Runs the provided function in a fresh R subprocess where `rJava` has not yet been loaded. This allows you to enforce a specific Java version for `rJava` operations without affecting the main R session or requiring a restart.

### Usage
`with_rjava_env(version, func, args = list(), distribution = "Corretto", install = TRUE, accept_system_java = TRUE, quiet = TRUE, libpath = .libPaths())`

### Arguments
- **version** (string/numeric) - Required - Java version specification (Major version, specific version, or SDKMAN identifier).
- **func** (function) - Required - The function to execute in the subprocess.
- **args** (list) - Optional - A list of arguments to pass to `func`.
- **distribution** (character) - Optional - The Java distribution to download (defaults to "Corretto").
- **install** (logical) - Optional - If TRUE, attempts to download/install if missing.
- **accept_system_java** (logical) - Optional - If TRUE, scans the system for existing Java installations.
- **quiet** (logical) - Optional - Whether to suppress messages.
- **libpath** (character vector) - Optional - Library paths to use in the subprocess.

### Value
The result of `func`.

### Example
```r
result <- with_rjava_env(
  version = 21,
  func = function(x) {
    library(rJava)
    .jinit()
    .jcall("java.lang.System", "S", "getProperty", "java.version")
  },
  args = list(x = 1)
)
print(result)
```
```

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

### java_check_version_cmd(java_home = NULL, quiet = FALSE, .use_cache = FALSE)

Source: https://www.ekotov.pro/rJavaEnv/reference/java_check_version_cmd.html

Checks the installed Java version using terminal commands. Returns the major version as a character string or FALSE if the Java executable is not found.

```APIDOC
## java_check_version_cmd

### Description
Checks the installed Java version using terminal commands. This function is memoised within the R session to improve performance on repeated calls.

### Usage
java_check_version_cmd(java_home = NULL, quiet = FALSE, .use_cache = FALSE)

### Arguments
- **java_home** (character) - Optional - Path to Java home directory. If NULL, uses the JAVA_HOME environment variable.
- **quiet** (logical) - Optional - Whether to suppress messages. Defaults to FALSE.
- **.use_cache** (logical) - Optional - If TRUE, uses cached results for repeated calls with the same JAVA_HOME. Defaults to FALSE.

### Value
A character vector of length 1 containing the major Java version, or FALSE if JAVA_HOME is not set or the Java executable cannot be found.

### Example
```r
java_check_version_cmd()
```
```

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

### java_clear_installed(check = TRUE, delete_all = FALSE, cache_path = getOption("rJavaEnv.cache_path"))

Source: https://www.ekotov.pro/rJavaEnv/reference/java_clear_installed.html

Clears the Java installations cache folder. Users can choose to list contents before clearing and force deletion without prompts.

```APIDOC
## java_clear_installed

### Description
Clears the Java installations cache folder.

### Usage
```r
java_clear_installed(check = TRUE, delete_all = FALSE, cache_path = getOption("rJavaEnv.cache_path"))
```

### Arguments
- **check** (logical) - Whether to list the contents of the cache directory before clearing it. Defaults to TRUE.
- **delete_all** (logical) - Whether to delete all items without prompting. Defaults to FALSE.
- **cache_path** (character) - The destination directory to download the Java distribution to. Defaults to a user-specific data directory.

### Value
A message indicating whether the cache was cleared or not.
```

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

### Usage of java_ensure

Source: https://www.ekotov.pro/rJavaEnv/reference/java_ensure.html

This function checks for a specific Java version and optionally installs it if not found. It is designed to be safe for use in scripts or package startup code when install is set to FALSE.

```R
java_ensure(
  version = NULL,
  type = c("exact", "min"),
  accept_system_java = TRUE,
  install = TRUE,
  distribution = "Corretto",
  backend = getOption("rJavaEnv.backend", "native"),
  check_against = c("rJava", "cmd"),
  quiet = FALSE,
  cache_path = getOption("rJavaEnv.cache_path"),
  platform = platform_detect()$os,
  arch = platform_detect()$arch,
  .use_cache = FALSE,
  .check_rjava_fun = check_rjava_initialized,
  .rjava_ver_fun = java_check_current_rjava_version
)
```

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

### java_ensure(version = NULL, type = c("exact", "min"), ...)

Source: https://www.ekotov.pro/rJavaEnv/reference/java_ensure.html

Ensures a specific Java version is available by checking the current session, system installations, or the rJavaEnv cache, with an optional installation step.

```APIDOC
## java_ensure

### Description
Checks for a specific Java version and optionally installs it if not found. This function is designed to be lazy, making it safe for use in scripts or package startup code.

### Usage
java_ensure(version = NULL, type = c("exact", "min"), accept_system_java = TRUE, install = TRUE, distribution = "Corretto", backend = getOption("rJavaEnv.backend", "native"), check_against = c("rJava", "cmd"), quiet = FALSE, cache_path = getOption("rJavaEnv.cache_path"), platform = platform_detect()$os, arch = platform_detect()$arch, .use_cache = FALSE, .check_rjava_fun = check_rjava_initialized, .rjava_ver_fun = java_check_current_rjava_version)

### Parameters
- **version** (NULL) - The version of Java to ensure.
- **type** (character) - Matching type: "exact" or "min".
- **accept_system_java** (logical) - Whether to allow system-installed Java.
- **install** (logical) - Whether to download and install if not found.
- **distribution** (character) - Java distribution to use (default: "Corretto").
- **backend** (character) - Backend to use for installation.
- **check_against** (character) - Method to check version: "rJava" or "cmd".
- **quiet** (logical) - Suppress messages.
- **cache_path** (character) - Path to the installation cache.
```

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

### Load rJavaEnv

Source: https://www.ekotov.pro/rJavaEnv/articles/install-rjava-from-source.html

Initializes the rJavaEnv library.

```R
library(rJavaEnv)
```

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

### java_clear_installed(delete_all = TRUE)

Source: https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv.qmd

Clears installed Java versions from the cache.

```APIDOC
## java_clear_installed

### Description
Clears all installed Java versions from the package cache.

### Parameters
- **delete_all** (boolean) - Required - Whether to delete all installed versions.
```