Support configurable netCDF-Java CLASSPATH via R option and env var

[cofinoa]

Background / Motivation

A developer or user of loadeR.java may eventually need to run with different netCDF-Java setups without editing the package code:

• In production, use a single JAR (e.g., netcdfAll-*.jar).
• In development, point to class directories and/or multiple JARs (e.g., Gradle build/classes/java/main, build/resources/main, plus deps).
• In packaged installs, if nothing is configured, just use JAR bundle with the R package.

Right now, switching between these scenarios requires modifying the package or copying JARs into the repo. A small, standard initialization hook would cover all cases cleanly.

Proposed Behaviour (non-breaking)

loadeR.java should determine the Java classpath for netCDF-Java at startup using this precedence:

1. R option: loadeR.netcdf_java_classpath
2. Environment variable: LOADER_NETCDF_JAVA_CLASSPATH
3. Bundled fallback: package directory java/ (include directories and JARs in the classpath)

Both the option and env var accept a classpath string: one or many entries, directories and/or JARs, separated by the platform path separator (: on Linux/macOS, ; on Windows).

Why this approach

• Mirrors standard JVM usage (explicit -cp semantics).
• Avoids hardcoding a specific artifact (e.g., netcdfAll) and works equally well for ToolsUI fat jars or module class dirs.
• Keeps the current default (bundled jars) working for users who don’t configure anything.

User-facing Configuration (examples)

Production (single JAR)

# Session override
options(loadeR.netcdf_java_classpath = "/opt/netcdf-java/netcdfAll-5.9.0.jar")
library(loadeR.java)

Development (directories + jars)

options(loadeR.netcdf_java_classpath = paste(
  "~/dev/netcdf-java/cdm/build/classes/java/main",
  "~/dev/netcdf-java/cdm/build/resources/main",
  "~/dev/netcdf-java/grib/build/classes/java/main",
  "~/dev/netcdf-java/grib/build/resources/main",
  sep = .Platform$path.sep
))
library(loadeR.java)

Environment variable (persistent, default)

# Linux/macOS
export LOADER_NETCDF_JAVA_CLASSPATH="/opt/netcdf-java/lib/*"
R -q -e "library(loadeR.java)"

# Windows PowerShell
$env:LOADER_NETCDF_JAVA_CLASSPATH = "C:\netcdf-java\lib\*"
R -NoSave -e "library(loadeR.java)"

Bundled fallback (no config)

• Drop any required jars and directory into java/.

Expected Startup Messages

• Print which source was used:
  • netCDF-Java CLASSPATH from R option loadeR.netcdf_java_classpath: ...
  • netCDF-Java CLASSPATH from env LOADER_NETCDF_JAVA_CLASSPATH: ...
  • netCDF-Java CLASSPATH from bundled inst/java/*: ...

Implementation Notes (sketch, not a full rewrite)

• In .onLoad():
  • Read getOption("loadeR.netcdf_java_classpath", "") and Sys.getenv("LOADER_NETCDF_JAVA_CLASSPATH", "").
  • Split by .Platform$path.sep.
  • If both option and env are set and differ, option wins; consider warning (or loadeR.java.strict_classpath to error).
  • Fallback: file.path(system.file("java", package = pkgname), "*").
  • Initialize JVM via rJava::.jinit(classpath = classpath, parameters = ...).
• In .onAttach():
  • Optionally report detected netCDF-Java runtime version via Package.getImplementationVersion() when available; otherwise print a friendly “version unknown/dev” message when using dirs/wildcards.

Tests (suggested)

• Option supplies two directories → both present in .jclassPath().
• Env var supplies wildcard dir → jars are available (verify a known class loads).
• Neither option nor env set → classpath contains one entry ending in inst/java/*.
• Already-initialized JVM → entries added, wildcard warning printed.
• Windows path separator (;) works as expected.

Documentation snippet (README)

#### Selecting netCDF-Java at startup

`loadeR.java` looks for a netCDF-Java classpath in this order:

1. `options(loadeR.netcdf_java_classpath)`
2. `LOADER_NETCDF_JAVA_CLASSPATH` (env var)
3. All jars under the package’s `inst/java/` (`inst/java/*`)

The classpath may contain one or more directories and/or JARs separated by the platform path separator (`:` on Linux/macOS, `;` on Windows). Wildcards like `.../lib/*` are supported and are expanded by the JVM at startup. Example:

```r
options(loadeR.netcdf_java_classpath = "/opt/netcdf-java/lib/*")
library(loadeR.java)
```

[mariadlor]

I have implemented the configurable netCDF-Java CLASSPATH support in both .onLoad() and .onAttach() on the new branch feature-configurable-classpath.

Key changes

• Classpath resolution order:

  1. R option: loadeR.netcdf_java_classpath
  2. Environment variable: LOADER_NETCDF_JAVA_CLASSPATH
  3. Fallback: bundled jars and directories under inst/java/

• Conflict handling:

  • If both R option and env var are set with different values:
    • By default → R option wins and a warning is issued.
    • If options(loadeR.java.strict_classpath = TRUE) → stop with an error.

• Classpath expansion:

  • Values are split by the platform path separator (: on Linux/macOS, ; on Windows).
  • Supports wildcards and directories via Sys.glob.
  • Cleaned for empty entries and duplicates.

• JVM initialization:

  • If the JVM is not yet initialized → call .jinit(classpath = ...).
  • If already initialized → add entries dynamically via .jaddClassPath() with a warning that a restart may be needed.

• Startup messages:

  • On attach, the package reports the source of the netCDF-Java CLASSPATH:

    netCDF-Java CLASSPATH from R option loadeR.netcdf_java_classpath: ...
    netCDF-Java CLASSPATH from env LOADER_NETCDF_JAVA_CLASSPATH: ...
    netCDF-Java CLASSPATH from bundled inst/java/*: ...
    

[cofinoa]

@mor427unican I’d like to clarify how rJava handles the CLASSPATH environment variable during JVM initialization and how this should inform our implementation of the configurable classpath feature.

According to the documentation and source code of rJava, when .jinit() is invoked:

• Any classpath argument provided by the user is prepended to the current system CLASSPATH. In effect, if a user specifies a custom classpath via .jinit(classpath=...), those entries come before whatever is defined in the system environment variable CLASSPATH.
• If no classpath argument is provided, the system’s CLASSPATH is used as-is.
• Therefore, rJava does not ignore CLASSPATH, it explicitly includes it unless overridden.

Given this behaviour, it would be prudent for our new feature to test that:

1. If the user defines a custom classpath via the R option or environment variable, it should override or be prepended as designed.
2. The system CLASSPATH is still honored after that, so we don’t inadvertently drop existing paths.

Specifically, a test case could:

• Set a system CLASSPATH (e.g., via Sys.setenv("CLASSPATH", ... ) before loading loadeR.java),
• Then set a custom classpath via the R option,
• After .jinit(), check via .jclassPath() that the two items appear in the correct order (user-defined first, system after).

Would you agree that we should explicitly include such a test in the feature branch to ensure this integration works correctly?

As a general use case, I think it would be better to suggest users rely on the CLASSPATH environment variable, and reserve the other mechanisms for advanced usage (e.g., developer options).

---

https://www.rdocumentation.org/packages/rJava/versions/1.0-11/topics/jinit

[mariadlor]

Thanks for clarifying the behavior of rJava with respect to the system CLASSPATH.
I’ve updated the feature branch accordingly and can confirm the following:

• Forced version option:
  Since some setups (e.g., multiple class directories without a fat JAR) don’t provide a MANIFEST.MF, I added support for options(loadeR.java.forced_version = "x.y.z"). This way, users can manually specify the netCDF-Java version if detection fails.

• Classpath integration test:
  I added an automated test (tests/testthat/test-loadeRjava.R) that sets both a system CLASSPATH and a user-defined classpath. It then checks via .jclassPath() that:

  1. The user-defined classpath is present.
  2. The system CLASSPATH is still honored.
  3. The user-defined entries appear before the system entries, consistent with rJava’s documented behavior.

This ensures that we don’t inadvertently drop existing CLASSPATH values while still respecting user overrides.