Skip to content

8358701: Remove misleading javax.management.remote API doc wording about JMX spec, and historic link to JMXMP #25670

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

8358701: Remove misleading javax.management.remote API doc wording about JMX spec, and historic link to JMXMP #25670

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
26ffc32
8358701: Java API docs for javax.management.remote should not link to…
kevinjwalls Jun 6, 2025
25c90c7
update
kevinjwalls Jun 6, 2025
e3b46cc
update
kevinjwalls Jun 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 9 additions & 27 deletions src/java.management/share/classes/javax/management/remote/package-info.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2002, 2024, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2002, 2025, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -27,12 +27,9 @@
* <p>Interfaces for remote access to
* JMX MBean servers.
* This package defines the essential interfaces for making a JMX
* MBean server manageable remotely. The specification of this
* functionality is completed by Part III of the
* <a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr160/index2.html">
* JMX Specification, version 1.4</a></p>
* MBean server manageable remotely.</p>
*
* <p>The JMX specification defines the notion of <b>connectors</b>.
* <p>JMX defines the notion of <b>connectors</b>.
* A connector is attached to a JMX API MBean server and makes it
* accessible to remote Java clients. The client end of a
* connector exports essentially the same interface as the MBean
Expand All @@ -41,32 +38,17 @@
* interface.</p>
*
* <p>A connector makes an MBean server remotely accessible through
* a given protocol. The JMX Remote API allows the use of different
* type of connectors:
* a given protocol.
*
* <ul>
* <ul>
* <li>The JMX Remote API defines a standard connector,
* the <b>RMI Connector</b>, which provides remote access to an
* MBeanServer through RMI.
* MBeanServer through RMI.
*
* <li>The JMX Remote API also defines an optional connector called
* <b>JMXMP Connector</b> implementing the JMX Message Protocol
* (JMXMP). As it is optional, it is not part of this bundle (see
* note below).
*
* <li>User-defined connector protocols are also possible using the
* <li>Other connector protocols are also possible using the
* {@link javax.management.remote.JMXConnectorFactory
* JMXConnectorFactory} and, optionally, the Generic Connector
* (not part of this bundle, see note below).
* </ul>
*
* <p><u>Note</u>: the optional packages implementing
* the optional part of the <em>JMX Remote API</em>
* are not included in the <em>Java SE Platform</em>
* but are available from the <em>JMX Remote API
* <a href="https://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html">
* Reference Implementation</a></em>.</p>
*
* JMXConnectorFactory}.
* </ul>
Copy link
Member

@dfuch dfuch Jun 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should keep the first part of the note - without the link. Something like:

 *
 *       <p><u>Note</u>: The historical JMX Remote API specification
 *         also defined an optional part; optional packages implementing
 *         the optional part of the <em>JMX Remote API</em>
 *         are not part of the <em>Java SE Platform</em>.</p>
 *

@AlanBateman do you think that would be helpful to keep?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would you think about dropping the sentence "The JMX Remote API allows the use of different type of connectors" and drop "User-defined" from the last list item? Doing that makes it much easier to say that the RMI Connector is standard and that other Connectors are possible using using the JMXConnectorFactory. It removes any discussion as to whether there are two or three "difference types".

I think we want "RMI Connector" to link to either RMIConnector or to the java.management.rmi module description.

My concern with having a historical note is that it invites readers to search for these other "interesting" optional parts, and they will be disappointed. If you do have a historical note then I think it need to say more than "are not part of the Java Platform", it will also need to say that they are not included in the JDK.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK - let's drop the historical note then.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would you think about dropping the sentence "The JMX Remote API allows the use of different type of connectors" and drop "User-defined" from the last list item

Yes that's fine. As is "User-defined connector protocols..." -> "Other connector protocols..."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As is "User-defined connector protocols..." -> "Other connector protocols..."

I think that would be okay.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also removing:
" and, optionally, the Generic Connector (not part of this bundle, see note below)."

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

*
* <h2>Connector addresses</h2>
*
Expand Down