Title:	'Java' Environments for R Projects
Version:	0.3.0
Description:	Quickly install 'Java Development Kit (JDK)' without administrative privileges and set environment variables in current R session or project to solve common issues with 'Java' environment management in 'R'. Recommended to users of 'Java'/'rJava'-dependent 'R' packages such as 'r5r', 'opentripplanner', 'xlsx', 'openNLP', 'rWeka', 'RJDBC', 'tabulapdf', and many more. 'rJavaEnv' prevents common problems like 'Java' not found, 'Java' version conflicts, missing 'Java' installations, and the inability to install 'Java' due to lack of administrative privileges. 'rJavaEnv' automates the download, installation, and setup of the 'Java' on a per-project basis by setting the relevant 'JAVA_HOME' in the current 'R' session or the current working directory (via '.Rprofile', with the user's consent). Similar to what 'renv' does for 'R' packages, 'rJavaEnv' allows different 'Java' versions to be used across different projects, but can also be configured to allow multiple versions within the same project (e.g. with the help of 'targets' package). Note: there are a few extra steps for 'Linux' users, who don't have any 'Java' previously installed in their system, and who prefer package installation from source, rather then installing binaries from 'Posit Package Manager'. See documentation for details.
License:	MIT + file LICENSE
URL:	https://github.com/e-kotov/rJavaEnv, https://www.ekotov.pro/rJavaEnv/
BugReports:	https://github.com/e-kotov/rJavaEnv/issues
Depends:	R (≥ 4.0)
Imports:	checkmate, cli, curl, jsonlite, utils
Suggests:	quarto, rJava, testthat (≥ 3.0.0)
VignetteBuilder:	quarto
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-04-04 13:00:51 UTC; ek
Author:	Egor Kotov [aut, cre, cph], Chung-hong Chan [aut], Mauricio Vargas [ctb], Hadley Wickham [ctb] (use_java feature suggestion and PR review), Enrique Mondragon-Estrada [ctb], Jonas Lieth [ctb]
Maintainer:	Egor Kotov <kotov.egor@gmail.com>
Repository:	CRAN
Date/Publication:	2025-04-04 13:20:02 UTC

rJavaEnv: 'Java' Environments for R Projects

Description

Quickly install 'Java Development Kit (JDK)' without administrative privileges and set environment variables in current R session or project to solve common issues with 'Java' environment management in 'R'. Recommended to users of 'Java'/'rJava'-dependent 'R' packages such as 'r5r', 'opentripplanner', 'xlsx', 'openNLP', 'rWeka', 'RJDBC', 'tabulapdf', and many more. 'rJavaEnv' prevents common problems like 'Java' not found, 'Java' version conflicts, missing 'Java' installations, and the inability to install 'Java' due to lack of administrative privileges. 'rJavaEnv' automates the download, installation, and setup of the 'Java' on a per-project basis by setting the relevant 'JAVA_HOME' in the current 'R' session or the current working directory (via '.Rprofile', with the user's consent). Similar to what 'renv' does for 'R' packages, 'rJavaEnv' allows different 'Java' versions to be used across different projects, but can also be configured to allow multiple versions within the same project (e.g. with the help of 'targets' package). Note: there are a few extra steps for 'Linux' users, who don't have any 'Java' previously installed in their system, and who prefer package installation from source, rather then installing binaries from 'Posit Package Manager'. See documentation for details.

Author(s)

Maintainer: Egor Kotov kotov.egor@gmail.com (ORCID) [copyright holder]

Authors:

• Chung-hong Chan chainsawtiney@gmail.com (ORCID)

Other contributors:

• Mauricio Vargas mavargas11@uc.cl (ORCID) [contributor]

• Hadley Wickham hadley@posit.co (use_java feature suggestion and PR review) [contributor]

• Enrique Mondragon-Estrada enriquemondragon@proton.me (ORCID) [contributor]

• Jonas Lieth jonas.lieth@gesis.org (ORCID) [contributor]

See Also

Useful links:

• https://github.com/e-kotov/rJavaEnv

• https://www.ekotov.pro/rJavaEnv/

• Report bugs at https://github.com/e-kotov/rJavaEnv/issues

Global Quiet Parameter

Description

Documentation for the quiet parameter, used globally.

Usage

global_quiet_param(quiet)

Arguments

Check installed Java version using terminal commands

Description

Check installed Java version using terminal commands

Usage

java_check_version_cmd(java_home = NULL, quiet = FALSE)

Arguments

Value

A character vector of length 1 containing the major Java version.

Examples

java_check_version_cmd()

Check Java Version with a Specified JAVA_HOME Using a Separate R Session

Description

This function sets the JAVA_HOME environment variable, initializes the JVM using rJava, and prints the Java version that would be used if the user sets the given JAVA_HOME in the current R session. This check is performed in a separate R session to avoid having to reload the current R session. The reason for this is that once Java is initialized in an R session, it cannot be uninitialized unless the current R session is restarted.

Usage

java_check_version_rjava(java_home = NULL, quiet = FALSE)

Arguments

Value

A character vector of length 1 containing the major Java version.

Examples

## Not run: 
java_check_version_rjava()

## End(Not run)

Check and print Java path and version using system commands

Description

This function checks the Java executable path and retrieves the Java version, then prints these details to the console.

Usage

java_check_version_system(quiet)

Arguments

Value

A character vector of length 1 containing the major Java version.

Manage Java installations and distributions caches

Description

Wrapper function to clear the Java symlinked in the current project, installed, or distributions caches.

Usage

java_clear(
  type = c("project", "installed", "distrib"),
  target_dir = NULL,
  check = TRUE,
  delete_all = FALSE
)

Arguments

Value

A message indicating whether the cache was cleared or not.

Examples

## Not run: 
java_clear("project", target_dir = tempdir())
java_clear("installed", target_dir = tempdir())
java_clear("distrib", target_dir = tempdir())

## End(Not run)

Clear the Java distributions cache folder

Description

Clear the Java distributions cache folder

Usage

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

Arguments

Value

A message indicating whether the cache was cleared or not.

Clear the Java versions symlinked in the current project

Description

Clear the Java versions symlinked in the current project

Usage

java_clear_in_project(project_path = NULL, check = TRUE, delete_all = FALSE)

Arguments

Value

A message indicating whether the symlinks were cleared or not.

Clear the Java installations cache folder

Description

Clear the Java installations cache folder

Usage

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

Arguments

Value

A message indicating whether the cache was cleared or not.

Download a Java distribution

Description

Download a Java distribution

Usage

java_download(
  version = 21,
  distribution = "Corretto",
  cache_path = getOption("rJavaEnv.cache_path"),
  platform = platform_detect()$os,
  arch = platform_detect()$arch,
  quiet = FALSE,
  force = FALSE,
  temp_dir = FALSE
)

Arguments

Value

The path to the downloaded Java distribution file.

Examples

## Not run: 

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

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

## End(Not run)

Set the JAVA_HOME and PATH environment variables to a given path

Description

Set the JAVA_HOME and PATH environment variables to a given path

Usage

java_env_set(
  where = c("session", "both", "project"),
  java_home,
  project_path = NULL,
  quiet = FALSE
)

Arguments

Value

Nothing. Sets the JAVA_HOME and PATH environment variables.

Examples

## Not run: 
# download, install Java 17
java_17_distrib <- java_download(version = "17", temp_dir = TRUE)
java_home <- java_install(
  java_distrib_path = java_17_distrib,
  project_path = tempdir(),
  autoset_java_env = FALSE
)

# now manually set the JAVA_HOME and PATH environment variables in current session
java_env_set(
  where = "session",
  java_home = java_home
)

# or set JAVA_HOME and PATH in the spefific projects' .Rprofile
java_env_set(
  where = "session",
  java_home = java_home,
  project_path = tempdir()
)


## End(Not run)

Update the .Rprofile file in the project directory

Description

Update the .Rprofile file in the project directory

Usage

java_env_set_rprofile(java_home, project_path = NULL)

Arguments

Set the JAVA_HOME and PATH environment variables for the current session

Description

Set the JAVA_HOME and PATH environment variables for the current session

Usage

java_env_set_session(java_home)

Arguments

Unset the JAVA_HOME and PATH environment variables in the project .Rprofile

Description

Unset the JAVA_HOME and PATH environment variables in the project .Rprofile

Usage

java_env_unset(project_path = NULL, quiet = FALSE)

Arguments

Value

Nothing. Removes the JAVA_HOME and PATH environment variables settings from the project .Rprofile.

Examples

## Not run: 
# clear the JAVA_HOME and PATH environment variables in the specified project .Rprofile
java_env_unset(project_path = tempdir())

## End(Not run)

Install Java from a distribution file

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.

Usage

java_install(
  java_distrib_path,
  project_path = NULL,
  autoset_java_env = TRUE,
  quiet = FALSE
)

Arguments

Value

The path to the installed Java directory.

Examples

## Not run: 

# 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())

## End(Not run)

List the contents of the Java versions installed or cached

Description

This function lists one of the following:

• project - list the contents of the Java symlinked/copied in the current project or directory specified by target_dir

• distrib - list the contents of the downloaded Java distributions cache in default location or specified by target_dir

• installed - list the contents of the Java installations cache (unpacked distributions) in default location or specified by target_dir

Usage

java_list(
  type = c("project", "installed", "distrib"),
  output = c("data.frame", "vector"),
  quiet = TRUE,
  target_dir = NULL
)

Arguments

Value

A dataframe or character vector with the contents of the specified cache or project directory.

Examples

## Not run: 
java_list("project")
java_list("installed")
java_list("distrib")

## End(Not run)

List the contents of the Java distributions cache folder

Description

List the contents of the Java distributions cache folder

Usage

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

Arguments

Value

A character vector with the contents of the cache directory.

List the Java versions symlinked in the current project

Description

List the Java versions symlinked in the current project

Usage

java_list_in_project(
  project_path = NULL,
  output = c("data.frame", "vector"),
  quiet = TRUE
)

Arguments

Value

A data frame or character vector with the symlinked Java versions in the project directory.

List the contents of the Java installations cache folder

Description

List the contents of the Java installations cache folder

Usage

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

Arguments

Value

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

Download and install and set Java in current working/project directory

Description

Download and install and set Java in current working/project directory

Usage

java_quick_install(
  version = 21,
  distribution = "Corretto",
  project_path = NULL,
  platform = platform_detect()$os,
  arch = platform_detect()$arch,
  quiet = FALSE,
  temp_dir = FALSE
)

Arguments

Value

Message indicating that Java was installed and set in the current working/project directory.

Examples

## Not run: 

# quick download, unpack, install and set in current working directory default Java version (21)
java_quick_install(17, temp_dir = TRUE)

## End(Not run)

Unpack a Java distribution file into cache directory

Description

Unpack the Java distribution file into cache directory and return the path to the unpacked Java directory with Java binaries.

Usage

java_unpack(java_distrib_path, quiet = FALSE)

Arguments

Value

A character vector containing of length 1 containing the path to the unpacked Java directory.

Examples

## Not run: 

# 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)

## End(Not run)

Load Java URLs from JSON file

Description

Load Java URLs from JSON file

Usage

java_urls_load()

Value

A list with the Java URLs structured as in the JSON file by distribution, platform, and architecture.

Get Available Online Versions of Amazon Corretto

Description

This function downloads the latest Amazon Corretto version information from the Corretto GitHub endpoint and returns a data frame with details for all eligible releases.

Usage

java_valid_major_versions_corretto(
  arch = NULL,
  platform = NULL,
  imageType = "jdk"
)

Arguments

Details

It leverages the existing platform_detect() function to infer the current operating system and architecture if these are not provided.

Value

A character vector of available major Corretto versions.

Retrieve Valid Java Versions

Description

This function retrieves a list of valid Java versions by querying an appropriate API endpoint based on the chosen distribution. The result is cached for 8 hours to avoid repeated API calls. If the API call fails (for example, due to a lack of internet connectivity), the function falls back to a pre-defined list of Java versions.

Usage

java_valid_versions(
  distribution = "Corretto",
  platform = platform_detect()$os,
  arch = platform_detect()$arch,
  force = FALSE
)

Arguments

Value

A character vector of valid Java versions.

Examples

## Not run: 
  # Retrieve valid Java versions (cached if available) using Amazon Corretto endpoint
  versions <- java_valid_versions()

  # Force refresh the list of Java versions using the Oracle endpoint
  versions <- java_valid_versions(distribution = "Corretto", force = TRUE)

## End(Not run)

Check Java version using rJava

Description

Check Java version using rJava

Usage

java_version_check_rscript(java_home)

Arguments

Value

A message with the Java version or an error message.

Detect platform and architecture

Description

Detect platform and architecture

Usage

platform_detect(quiet = TRUE)

Arguments

Value

A list of length 2 with the detected platform and architecture.

Obtain User Consent for rJavaEnv

Description

Get user consent for rJavaEnv to write and update files on the file system. rJavaEnv needs permission to manage files in your project and cache directories to function correctly.

Usage

rje_consent(provided = FALSE)

Arguments

Details

In line with CRAN policies, explicit user consent is required before making these changes. Please call rJavaEnv::consent() to provide consent.

Alternatively, you can set the following R option (especially useful for non-interactive R sessions):

options(rJavaEnv.consent = TRUE)

The function is based on the code of the renv package. Copyright 2023 Posit Software, PBC License: https://github.com/rstudio/renv/blob/main/LICENSE

Value

TRUE if consent is given, otherwise an error is raised.

Examples

## Not run: 

# to provide consent and prevent other functions from interrupting to get the consent
rje_consent(provided = TRUE)

## End(Not run)

Verify User Consent for rJavaEnv

Description

Ensure that the user has granted permission for rJavaEnv to manage files on their file system.

Usage

rje_consent_check()

Details

The function is based on the code of the renv package. Copyright 2023 Posit Software, PBC License: https://github.com/rstudio/renv/blob/main/LICENSE

Value

TRUE if consent is verified, otherwise an error is raised.

Helper for clean env var check

Description

#' The function is based on the code of the renv package. Copyright 2023 Posit Software, PBC License: https://github.com/rstudio/renv/blob/main/LICENSE

Usage

rje_envvar_exists(key)

Arguments

Test all Java URLs

Description

Test all Java URLs

Usage

urls_test_all()

Value

A list with the results of testing all Java URLs.

Install specified Java version and set the JAVA_HOME and PATH environment variables in current R session

Description

Using specified Java version, set the JAVA_HOME and PATH environment variables in the current R session. If Java distribtuion has not been downloaded yet, download it. If it was not installed into cache directory yet, install it there and then set the environment variables. This is intended as a quick and easy way to use different Java versions in R scripts that are in the same project, but require different Java versions. For example, one could use this in scripts that are called by targets package or callr package.

Usage

use_java(
  version = NULL,
  distribution = "Corretto",
  cache_path = getOption("rJavaEnv.cache_path"),
  platform = platform_detect()$os,
  arch = platform_detect()$arch,
  quiet = TRUE
)

Arguments

Value

NULL. Prints the message that Java was set in the current R session if quiet is set to FALSE.

Examples

## Not run: 

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

# install and set Java 8 in current R session
use_java(8)
# check Java version
"8" == java_check_version_cmd(quiet = TRUE)
"8" == java_check_version_rjava(quiet = TRUE)

# install and set Java 17 in current R session
use_java(17)
# check Java version
"17" == java_check_version_cmd(quiet = TRUE)
"17" == java_check_version_rjava(quiet = TRUE)


## End(Not run)