[java] encapsulation + resource immutability for option classes #54370

axreldable · 2025-07-07T15:49:35Z

Why are these changes needed?

Add encapsulation of fields and immutability for exposed structures such as maps and lists in classes within the io.ray.api.options module, as requested in issue #54310.

Related issue number

Closes #54310

Checks

I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
I've run scripts/format.sh to lint the changes in this PR.
I've included any doc changes needed for https://docs.ray.io/en/master/.
- I've added any new APIs to the API Reference. For example, if I added a
  method in Tune, I've added it in doc/source/tune/api/ under the
  corresponding .rst file.
I've made sure the tests are passing. Note that there might be a few flaky tests, see the recent failures at https://flakey-tests.ray.io/
Testing Strategy
- Unit tests
- Release tests
- This PR is not tested :(

Signed-off-by: axreldable <[email protected]>

axreldable · 2025-07-07T17:03:49Z

Hi, @codope!
Could you please check if the PR addresses what you requested in the issue #54310?

Copilot

Pull Request Overview

This PR refactors several option classes to enforce encapsulation and immutability, and updates code sites to use the new getters.

Converted public fields in option classes to private finals with getters and builder patterns
Wrapped mutable collections (resources, bundles, concurrency groups) in unmodifiable views
Updated runtime/task submitter and core runtime code to replace field access with the new getters

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
java/runtime/.../NativeTaskSubmitter.java	Replaced direct field access with getters
java/runtime/.../LocalModeTaskSubmitter.java	Replaced direct field access with getters
java/runtime/.../AbstractRayRuntime.java	Switched to getters for jvmOptions
java/api/.../PlacementGroupCreationOptions.java	Introduced builder pattern and immutable bundles
java/api/.../CallOptions.java	Introduced builder pattern and getters
java/api/.../BaseTaskOptions.java	Made resources map immutable with getter
java/api/.../ActorCreationOptions.java	Introduced builder pattern and getters

Comments suppressed due to low confidence (4)

java/api/src/main/java/io/ray/api/options/CallOptions.java:43

[nitpick] The getter name getSerializedRuntimeEnvInfo differs from ActorCreationOptions' getSerializedRuntimeEnv; consider aligning these names for consistency.

  public String getSerializedRuntimeEnvInfo() {

java/api/src/main/java/io/ray/api/options/ActorCreationOptions.java:87

[nitpick] The getter name getSerializedRuntimeEnv is inconsistent with CallOptions' getSerializedRuntimeEnvInfo; unifying naming across option classes would improve API clarity.

  public String getSerializedRuntimeEnv() {

java/api/src/main/java/io/ray/api/options/CallOptions.java:117

Switching from a public constructor to a builder-only approach is a breaking change; consider deprecating the old constructor or providing migration notes in the API docs.

      return new CallOptions(this);

java/runtime/src/main/java/io/ray/runtime/task/NativeTaskSubmitter.java:63

[nitpick] The error message 'Actor of name %s exists' could be clearer; for example, 'An actor with name %s already exists.'

            !actor.isPresent(), String.format("Actor of name %s exists", options.getName()));

Copilot · 2025-07-07T17:26:58Z

java/runtime/src/main/java/io/ray/runtime/task/NativeTaskSubmitter.java

        Preconditions.checkArgument(
-            options.bundleIndex == -1
-                || options.bundleIndex >= 0 && options.bundleIndex < group.getBundles().size(),
+            options.getBundleIndex() == -1
+                || options.getBundleIndex() >= 0
+                    && options.getBundleIndex() < group.getBundles().size(),
            String.format(
                "Bundle index %s is invalid, the correct bundle index should be "
                    + "either in the range of 0 to the number of bundles "
                    + "or -1 which means put the task to any available bundles.",
-                options.bundleIndex));
+                options.getBundleIndex()));


[nitpick] Consider assigning options.getBundleIndex() to a local variable to avoid repeated method calls and improve readability.

Signed-off-by: axreldable <[email protected]>

codope

@axreldable Thanks for the contribution! This is in line with my expectation. Left one minor comment.

java/api/src/main/java/io/ray/api/options/BaseTaskOptions.java

… BaseTaskOptions class + unit tests Signed-off-by: axreldable <[email protected]>

Signed-off-by: axreldable <[email protected]>

codope · 2025-07-08T16:23:35Z

@kfstorm @SongGuyang @WangTaoTheTonic @raulchen Could you please take a look and merge the PR?

axreldable · 2025-07-11T10:01:11Z

Hi @kfstorm @SongGuyang @WangTaoTheTonic @raulchen ,
Could you kindly check the PR? Thank you!

…project#54370) Signed-off-by: axreldable <[email protected]> Co-authored-by: Sagar Sumit <[email protected]> Signed-off-by: dshepelev15 <[email protected]>

…project#54370) Signed-off-by: axreldable <[email protected]> Co-authored-by: Sagar Sumit <[email protected]> Signed-off-by: alimaazamat <[email protected]>

…project#54370) Signed-off-by: axreldable <[email protected]> Co-authored-by: Sagar Sumit <[email protected]> Signed-off-by: Krishna Kalyan <[email protected]>

Copilot AI review requested due to automatic review settings July 7, 2025 15:49

axreldable requested review from kfstorm, raulchen, WangTaoTheTonic and SongGuyang as code owners July 7, 2025 15:49

This comment was marked as outdated.

Sign in to view

axreldable force-pushed the java_encapsulation branch from 7b4a057 to 607a3e5 Compare July 7, 2025 16:03

[java] encapsulation + resource immutability for options classes

14f7bd4

Signed-off-by: axreldable <[email protected]>

axreldable force-pushed the java_encapsulation branch from 607a3e5 to 14f7bd4 Compare July 7, 2025 16:08

axreldable added 2 commits July 7, 2025 18:10

Merge branch 'master' into java_encapsulation

0e2bdc0

Merge branch 'master' into java_encapsulation

1907e21

axreldable requested a review from Copilot July 7, 2025 17:04

This comment was marked as outdated.

Sign in to view

Merge branch 'master' into java_encapsulation

15d9289

axreldable requested a review from Copilot July 7, 2025 17:25

Copilot AI reviewed Jul 7, 2025

View reviewed changes

axreldable added 2 commits July 7, 2025 19:49

[java] immutability for options classes

1e8c6a8

Signed-off-by: axreldable <[email protected]>

[java] roll back to public constructor for backward compatibility

8951e6c

Signed-off-by: axreldable <[email protected]>

codope added the go add ONLY when ready to merge, run all tests label Jul 8, 2025

codope reviewed Jul 8, 2025

View reviewed changes

java/api/src/main/java/io/ray/api/options/BaseTaskOptions.java Outdated Show resolved Hide resolved

codope self-assigned this Jul 8, 2025

[java] Move filtering to validation and refactor the structure of the…

5efad89

… BaseTaskOptions class + unit tests Signed-off-by: axreldable <[email protected]>

axreldable requested a review from codope July 8, 2025 13:19

[java] Enhance the clarity of the error message

4885f8d

Signed-off-by: axreldable <[email protected]>

codope approved these changes Jul 8, 2025

View reviewed changes

cszhu added community-contribution Contributed by the community core Issues that should be addressed in Ray Core labels Jul 9, 2025

codope and others added 2 commits July 14, 2025 07:11

Merge branch 'master' into java_encapsulation

0c1ae65

Merge branch 'master' into java_encapsulation

508f583

jjyao merged commit 7b9f799 into ray-project:master Jul 18, 2025
5 checks passed

axreldable deleted the java_encapsulation branch August 10, 2025 10:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[java] encapsulation + resource immutability for option classes #54370

[java] encapsulation + resource immutability for option classes #54370

Uh oh!

axreldable commented Jul 7, 2025 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

axreldable commented Jul 7, 2025 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jul 7, 2025

Uh oh!

codope left a comment

Uh oh!

Uh oh!

codope commented Jul 8, 2025

Uh oh!

axreldable commented Jul 11, 2025

Uh oh!

Uh oh!

Uh oh!

[java] encapsulation + resource immutability for option classes #54370

[java] encapsulation + resource immutability for option classes #54370

Uh oh!

Conversation

axreldable commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why are these changes needed?

Related issue number

Checks

Uh oh!

This comment was marked as outdated.

Uh oh!

axreldable commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

codope left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codope commented Jul 8, 2025

Uh oh!

axreldable commented Jul 11, 2025

Uh oh!

Uh oh!

Uh oh!

axreldable commented Jul 7, 2025 •

edited

Loading

axreldable commented Jul 7, 2025 •

edited

Loading