Package 'rJavaEnv' reference manual

Title:	'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.
Authors:	Egor Kotov [aut, cre, cph] , Mauricio Vargas [ctb] , Hadley Wickham [ctb] (use_java feature suggestion and PR review)
Maintainer:	Egor Kotov <[email protected]>
License:	MIT + file LICENSE
Version:	0.2.2
Built:	2024-09-13 20:16:52 UTC
Source:	https://github.com/e-kotov/rJavaEnv

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)
java_check_version_cmd(java_home = NULL, quiet = FALSE)

Arguments

`java_home`	Path to Java home directory. If NULL, the function uses the JAVA_HOME environment variable.
`quiet`	A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`.

Value

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

Examples

java_check_version_cmd()

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)
java_check_version_rjava(java_home = NULL, quiet = FALSE)

Arguments

`java_home`	Path to Java home directory. If NULL, the function uses the JAVA_HOME environment variable.
`quiet`	A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`.

Value

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

Examples

## Not run: 
java_check_version_rjava()

## End(Not run)

## Not run: 
java_check_version_rjava()

## End(Not run)

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
)
java_clear(
  type = c("project", "installed", "distrib"),
  target_dir = NULL,
  check = TRUE,
  delete_all = FALSE
)

Arguments

`type`	What to clear: "project" - remove symlinks to install cache in the current project, "installed" - remove installed Java versions, "distrib" - remove downloaded Java distributions.
`target_dir`	The directory to clear. Defaults to current working directory for "project" and user-specific data directory for "installed" and "distrib". Not recommended to change.
`check`	Whether to list the contents of the cache directory before clearing it. Defaults to TRUE.
`delete_all`	Whether to delete all items without prompting. Defaults to FALSE.

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)

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

## End(Not run)

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,
  temp_dir = FALSE
)
java_download(
  version = 21,
  distribution = "Corretto",
  cache_path = getOption("rJavaEnv.cache_path"),
  platform = platform_detect()$os,
  arch = platform_detect()$arch,
  quiet = FALSE,
  temp_dir = FALSE
)

Arguments

`version`	`Integer` or `character` vector of length 1 for major version of Java to download or install. If not specified, defaults to the latest LTS version. Can be "8", "11", "17", "21", "22", or 8, 11, 17, 21, or 22.
`distribution`	The Java distribution to download. If not specified, defaults to "Amazon Corretto". Currently only "Amazon Corretto" is supported.
`cache_path`	The destination directory to download the Java distribution to. Defaults to a user-specific data directory.
`platform`	The platform for which to download the Java distribution. Defaults to the current platform.
`arch`	The architecture for which to download the Java distribution. Defaults to the current architecture.
`quiet`	A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`.
`temp_dir`	A logical. Whether the file should be saved in a temporary directory. Defaults to `FALSE`.

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)
## 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
)
java_env_set(
  where = c("session", "both", "project"),
  java_home,
  project_path = NULL,
  quiet = FALSE
)

Arguments

`where`	Where to set the `JAVA_HOME`: "session", "project", or "both". Defaults to "session" and only updates the paths in the current R session. When "both" or "project" is selected, the function updates the .Rprofile file in the project directory to set the JAVA_HOME and PATH environment variables at the start of the R session.
`java_home`	The path to the desired `JAVA_HOME`.
`project_path`	A `character` vector of length 1 containing the project directory where Java should be installed. If not specified or `NULL`, defaults to the current working directory.
`quiet`	A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`.

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

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)
java_env_unset(project_path = NULL, quiet = FALSE)

Arguments

`project_path`	A `character` vector of length 1 containing the project directory where Java should be installed. If not specified or `NULL`, defaults to the current working directory.
`quiet`	A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`.

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)
## 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
)
java_install(
  java_distrib_path,
  project_path = NULL,
  autoset_java_env = TRUE,
  quiet = FALSE
)

Arguments

`java_distrib_path`	A `character` vector of length 1 containing the path to the Java distribution file.
`project_path`	A `character` vector of length 1 containing the project directory where Java should be installed. If not specified or `NULL`, defaults to the current working directory.
`autoset_java_env`	A `logical` indicating whether to set the `JAVA_HOME` and `PATH` environment variables to the installed Java directory. Defaults to `TRUE`.
`quiet`	A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`.

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)
## 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
)
java_list(
  type = c("project", "installed", "distrib"),
  output = c("data.frame", "vector"),
  quiet = TRUE,
  target_dir = NULL
)

Arguments

`type`	The type of cache to list: "distrib", "installed", or "project". Defaults to "project".
`output`	The format of the output: ⁠data.frame`` or ⁠vector“. Defaults to `data.frame`.
`quiet`	A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`.
`target_dir`	The cache directory to list. Defaults to the user-specific data directory for "distrib" and "installed", and the current working directory for "project".

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)

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

## End(Not run)

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
)
java_quick_install(
  version = 21,
  distribution = "Corretto",
  project_path = NULL,
  platform = platform_detect()$os,
  arch = platform_detect()$arch,
  quiet = FALSE,
  temp_dir = FALSE
)

Arguments

`version`	`Integer` or `character` vector of length 1 for major version of Java to download or install. If not specified, defaults to the latest LTS version. Can be "8", "11", "17", "21", "22", or 8, 11, 17, 21, or 22.
`distribution`	The Java distribution to download. If not specified, defaults to "Amazon Corretto". Currently only "Amazon Corretto" is supported.
`project_path`	A `character` vector of length 1 containing the project directory where Java should be installed. If not specified or `NULL`, defaults to the current working directory.
`platform`	The platform for which to download the Java distribution. Defaults to the current platform.
`arch`	The architecture for which to download the Java distribution. Defaults to the current architecture.
`quiet`	A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`.
`temp_dir`	A logical. Whether the file should be saved in a temporary directory. Defaults to `FALSE`.

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)
## 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)
java_unpack(java_distrib_path, quiet = FALSE)

Arguments

`java_distrib_path`	A `character` vector of length 1 containing the path to the Java distribution file.
`quiet`	A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`.

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)

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

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)
rje_consent(provided = FALSE)

Arguments

provided

Logical indicating if consent is already provided. To provide consent in non-interactive R sessions use rJavaEnv::rje_consent(provided = TRUE). Default is FALSE.

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)

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)

## Not run: 

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

## End(Not run)

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
)
use_java(
  version = NULL,
  distribution = "Corretto",
  cache_path = getOption("rJavaEnv.cache_path"),
  platform = platform_detect()$os,
  arch = platform_detect()$arch,
  quiet = TRUE
)

Arguments

`version`	`Integer` or `character` vector of length 1 for major version of Java to download or install. If not specified, defaults to the latest LTS version. Can be "8", "11", "17", "21", "22", or 8, 11, 17, 21, or 22.
`distribution`	The Java distribution to download. If not specified, defaults to "Amazon Corretto". Currently only "Amazon Corretto" is supported.
`cache_path`	The destination directory to download the Java distribution to. Defaults to a user-specific data directory.
`platform`	The platform for which to download the Java distribution. Defaults to the current platform.
`arch`	The architecture for which to download the Java distribution. Defaults to the current architecture.
`quiet`	A `logical` value indicating whether to suppress messages. Can be `TRUE` or `FALSE`.

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)

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

Package 'rJavaEnv'

Help Index

Check installed Java version using terminal commands

Description

Usage

Arguments

Value

Examples

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

Description

Usage

Arguments

Value

Examples

Manage Java installations and distributions caches

Description

Usage

Arguments

Value

Examples

Download a Java distribution

Description

Usage

Arguments

Value

Examples

Set the JAVA_HOME and PATH environment variables to a given path

Description

Usage

Arguments

Value

Examples

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

Description

Usage

Arguments

Value

Examples

Install Java from a distribution file

Description

Usage

Arguments

Value

Examples

List the contents of the Java versions installed or cached

Description

Usage

Arguments

Value

Examples

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

Description

Usage

Arguments

Value

Examples

Unpack a Java distribution file into cache directory

Description

Usage

Arguments

Value

Examples

Obtain User Consent for rJavaEnv

Description

Usage

Arguments

Details

Value

Examples

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

Description

Usage

Arguments

Value

Examples

Set the `JAVA_HOME` and `PATH` environment variables to a given path

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