rJavaEnv: Java Environments for R Projects rJavaEnv website

Project Status: Active Lifecycle: stable CRAN status CRAN/METACRAN Total downloads CRAN/METACRAN Downloads per month R-CMD-check codecov

DOI DOI

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.

Install

Install from CRAN:

install.packages('rJavaEnv')

Install latest release from R-multiverse:

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

You can also install the development version of rJavaEnv from GitHub:

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

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

Simple Example

rJavaEnv::java_quick_install(version = 21)

This will:

As part of normal operation, rJavaEnv will update the JAVA_HOME and PATH environment variables in the current R session, the local cache in your R package library, and the .Rprofile file in the project/current working directory. In line with CRAN policies, explicit user consent is required before making these changes. Therefore, the first time you run any function from rJavaEnv that makes such changes, you will be asked for consent. To explicitly consent and/or to prevent interruptions in non-interactive mode, you can use the rje_consent() function:

rje_consent(provided = TRUE)

Using rJavaEnv with targets and callr

Just insert this line into the begining of any script that you run with targets or callr:

rJavaEnv::use_java("21")

This acts exactly like java_quick_install(), but only sets the environment variables in the current session and does not copy or link Java binaries into the project directory.

More details are in the vignette Multiple Java environments in one project with targets and callr.

Cleanup

If you do not want to use rJavaEnv anymore, please clear the cache folders before removing the package:

java_clear("project", delete_all = TRUE)
java_clear("installed", delete_all = TRUE)
java_clear("distrib", delete_all = TRUE)

Also, clear the .Rprofile file in the projects there you used the package:

java_env_unset()

Functions Overview

The package has several core functions:

  1. java_quick_install()
  2. java_check_version_cmd()
  3. java_version_check_rjava()
  4. java_download()
  5. java_install()
  6. java_env_set()
  7. java_env_unset()
  8. java_list()
  9. java_clear()
  10. use_java()

See more details on all the functions in the Reference.

For detailed usage, see the Quick Start Vignette (work in progress).

Limitations

Currently, rJavaEnv only supports major Java versions such as 8, 11, 17, 21, 22. The download and install functions ignore the minor version of the Java distribution and just downloads the latest stable subversion of the specified major version. This is done to simplify the process and avoid the need to update the package every time a new minor version of Java is released. For most users this should be sufficient, but this is substandard for full reproducibility.

The main limitation is that if you want to switch to another Java environment, you will most likely have to restart the current R session and set the JAVA_HOME and PATH environment variables to the desired Java environment using rJavaEnv::java_env_set(). This cannot be done dynamically within the same R session due to the way Java is initialized in R, particularly with the rJava-dependent packages such as r5r. With packages like opentripplanner, that performs Java calls using command line, you can switch Java environments dynamically within the same R session as much as you want.

Therefore, if you need to use R packages that depend on different Java versions within the same project, you will have to create separate R scripts for each Java environment and run them in separate R sessions. One effective way of doing this is to use the callr package to run R scripts in separate R sessions. Another option is to use the targets package to manage the whole project workflow, which, as a side effect, will lead to all R scripts being run in separate R sessions. To use rJavaEnv with targets, you will need to download and install several Java environments using rJavaEnv::java_download() and rJavaEnv::java_install() and set the relevant path with rJavaEnv::java_env_set() at the beginning of each function that requires a certain Java version.

Future work

The future work includes:

I am open to suggestions and contributions, welcome to issues and pull requests.

Acknowledgements

I thank rOpenSci for the Dev Guide, as well as Hadley Wickham and Jennifer Bryan for the R Packages book.

Package hex sticker logo is partially generated by DALL-E by OpenAI. The logo also contains the original R logo.

Citation

To cite package ‘rJavaEnv’ in publications use:

Kotov E (2024). rJavaEnv: Java Environments for R Projects. doi:10.32614/CRAN.package.rJavaEnv https://doi.org/10.32614/CRAN.package.rJavaEnv, https://github.com/e-kotov/rJavaEnv.

BibTeX:

@Manual{rjavaenv,
  title = {rJavaEnv: Java Environments for R Projects},
  author = {Egor Kotov},
  year = {2024},
  url = {https://github.com/e-kotov/rJavaEnv},
  doi = {10.32614/CRAN.package.rJavaEnv},
}