---
title: "Quick Start Guide: Java Setup for R Projects"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Quick Start Guide: Java Setup for R Projects}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

This guide will walk you through downloading, installing, and managing Java environments for your R projects using the `rJavaEnv` package. We'll cover setting up the environment, unsetting it, managing distributions, installing Java, and checking Java versions.

### Step 1: Download and Install Java

1. **Install `rJavaEnv`**:
   First, install the development version of `rJavaEnv` from GitHub:
   ```r
   devtools::install_github("e-kotov/rJavaEnv")
   ```

2. **Quick Install Java**:
   To quickly install Java 21 (default) in your current project directory and set the environment:
   ```r
   library(rJavaEnv)
   java_quick_install()
   ```
   This command:
   - Downloads the Java distribution compatible with your OS and architecture.
   - Installs Java in a cache directory.
   - Sets the JAVA_HOME and PATH environment variables for the current session and project.

   Expected output:
   ```
   Platform detected or provided: <your_platform>
   Architecture detected or provided: <your_architecture>
   Downloading Java 21 (Corretto) for <your_platform> <your_architecture> to <destination_path>
   Download completed.
   Java 21 (Corretto) for <your_platform> <your_architecture> installed at <installed_path> and symlinked to <symlink_path>
   ```

3. **Step-by-Step Installation**:
   If you prefer a more controlled process:
   
   - **Download Java**:
     ```r
     java_distr_path <- java_download(version = 21, distribution = "Corretto")
     ```
     This will download Java 21 from the Corretto distribution.

     Expected output:
     ```
     Downloading Java 21 (Corretto) for <your_platform> <your_architecture> to <destination_path>
     Download completed.
     ```

   - **Install Java**:
     ```r
     java_home_path <- java_install(java_distr_path)
     ```
     This will install the downloaded Java distribution and set the JAVA_HOME and PATH environment variables.

     Expected output:
     ```
     Java 21 (Corretto) installed at <installed_path> and symlinked to <symlink_path>
     ```

### Step 2: Set Java Environment

Set the JAVA_HOME and PATH environment variables to the installed Java directory:
```r
java_env_set(java_home_path)
```
This function sets the JAVA_HOME and PATH environment variables for the current R session and/or the project `.Rprofile` file.

Expected output:
```
Current R Session: JAVA_HOME and PATH set to <java_home_path>
Current R Project/Working Directory: JAVA_HOME and PATH set to <java_home_path> in .Rprofile in <project_directory>
```

### Step 3: Unset Java Environment

Remove the JAVA_HOME and PATH environment variables settings from the project `.Rprofile` file:
```r
java_env_unset()
```
This function removes the JAVA_HOME and PATH environment variables from the `.Rprofile` file in the project directory.

Expected output:
```
Removed JAVA_HOME settings from .Rprofile in <project_directory>
```

### Step 4: Manage Java Distributions

- **List Cached Java Distributions**:
  ```r
  java_list(type = "distrib")
  ```
  This function lists all Java distributions cached in the user-specific data directory.

  Expected output:
  ```
  <data.frame or vector of cached Java distributions>
  ```

- **Clear Cached Java Distributions**:
  ```r
  java_clear(type = "distrib")
  ```
  This function clears all cached Java distributions.

  Expected output:
  ```
  Java distributions cache cleared.
  ```

### Step 5: Manage Installed Java Versions

- **List Installed Java Versions**:
  ```r
  java_list(type = "installed")
  ```
  This function lists all installed Java versions in the user-specific data directory.

  Expected output:
  ```
  <data.frame or vector of installed Java versions>
  ```

- **Clear Installed Java Versions**:
  ```r
  java_clear(type = "installed")
  ```
  This function clears all installed Java versions.

  Expected output:
  ```
  Java installations cache cleared.
  ```

### Step 6: Manage Project-Specific Java Versions

- **List Project-Specific Java Versions**:
  ```r
  java_list(type = "project")
  ```
  This function lists all Java versions symlinked in the current project directory.

  Expected output:
  ```
  <data.frame or vector of project-specific Java versions>
  ```

- **Clear Project-Specific Java Versions**:
  ```r
  java_clear(type = "project")
  ```
  This function clears all Java versions symlinked in the current project directory.

  Expected output:
  ```
  All Java symlinks in the project have been cleared.
  ```

### Step 7: Check Java Version

- **Check Installed Java Version using Terminal Commands**:
  ```r
  java_check_version_cmd()
  ```
  This function checks the Java version using terminal commands and prints the Java version and path.

  Expected output:
  ```
  JAVA_HOME: <current_java_home>
  Java path: <java_path>
  Java version:
  <java_version_details>
  ```

- **Check Java Version using `rJava` in a Separate R Session**:
  ```r
  java_check_version_rjava("/path/to/installed/java")
  ```
  This function checks the Java version using `rJava` in a separate R session.

  Expected output:
  ```
  With the current session's JAVA_HOME <java_version_details>
  or
  With the user-specified JAVA_HOME <java_version_details>
  ```