java_env_set.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/java_env.R
\name{java_env_set}
\alias{java_env_set}
\title{Set the \code{JAVA_HOME} and \code{PATH} environment variables to a given path}
\usage{
java_env_set(
  where = c("session", "both", "project"),
  java_home,
  project_path = NULL,
  quiet = FALSE
)
}
\arguments{
\item{where}{Where to set the \code{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.}

\item{java_home}{The path to the desired \code{JAVA_HOME}.}

\item{project_path}{A \code{character} vector of length 1 containing the project directory where Java should be installed. If not specified or \code{NULL}, defaults to the current working directory.}

\item{quiet}{A \code{logical} value indicating whether to suppress messages. Can be \code{TRUE} or \code{FALSE}.}
}
\value{
Nothing. Sets the JAVA_HOME and PATH environment variables.
}
\description{
Sets the JAVA_HOME and PATH environment variables for command-line Java tools and
rJava initialization. See details for important information about rJava timing.
}
\section{Additional Details}{

To use a different Java version with rJava-dependent packages, you must:
\enumerate{
\item Set JAVA_HOME using this function BEFORE loading rJava or any package that imports it
\item Restart your R session if you already loaded rJava with the wrong Java version
}
}

\section{rJava Path-Locking}{

\strong{Important for \emph{rJava} Users}: This function sets environment variables
(JAVA_HOME, PATH) that affect both command-line Java tools and \emph{rJava} initialization.
However, due to \emph{rJava}'s path-locking behavior when \code{\link[rJava]{.jinit}} is called
(see \url{https://github.com/s-u/rJava/issues/25}, \url{https://github.com/s-u/rJava/issues/249}, and \url{https://github.com/s-u/rJava/issues/334}),
this function must be called \strong{BEFORE} \code{\link[rJava]{.jinit}} is invoked. Once \code{\link[rJava]{.jinit}}
initializes, the Java version is locked for that R session and cannot be changed without restarting R.

\code{\link[rJava]{.jinit}} is invoked (and Java locked) when you:
\itemize{
\item Explicitly call \code{library(rJava)}
\item Load any package that imports \emph{rJava} (which auto-loads it as a dependency)
\item Even just use IDE autocomplete with \code{rJava::} (this triggers initialization!)
\item Call any \emph{rJava}-dependent function
}

Once any of these happen, the Java version used by \emph{rJava} for that session is locked in.
For command-line Java tools that don't use \emph{rJava}, this function can be called at any
time to switch Java versions for subsequent system calls.
}

\examples{
\donttest{
# 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 = "project",
  java_home = java_home,
  project_path = tempdir()
)

}
}