Package 'rJavaEnv'

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-10-13 07:06:40 UTC
Source: https://github.com/e-kotov/rJavaEnv

Help Index


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

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

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

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)

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

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)

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
)

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)

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

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)

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

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)

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

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)

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

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)

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

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)

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

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)

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

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)