8343609: Broken links in java.xml

Reviewed-by: naoto, lancea, iris
openjdk · Jan 24, 2025 · 471d63c · 471d63c · openjdk-notifier · Jan 24, 2025
1 parent 7f16a08
commit 471d63c
Show file tree

Hide file tree

Showing 7 changed files with 53 additions and 93 deletions.
diff --git a/src/java.xml/share/classes/javax/xml/catalog/Catalog.java b/src/java.xml/share/classes/javax/xml/catalog/Catalog.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 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
@@ -29,8 +29,7 @@
 
 /**
  * The Catalog class represents an entity Catalog as defined by
- * <a
- * href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html">
+ * <a href="https://groups.oasis-open.org/higherlogic/ws/public/download/14810/xml-catalogs.pdf">
  * XML Catalogs, OASIS Standard V1.1, 7 October 2005</a>.
  * <p>
  * A catalog is an XML file that contains a root {@code catalog} entry with a list

diff --git a/src/java.xml/share/classes/javax/xml/catalog/CatalogFeatures.java b/src/java.xml/share/classes/javax/xml/catalog/CatalogFeatures.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 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
@@ -137,10 +137,9 @@
  * <b>[2]</b> The value shall be exactly as listed in this table, case-sensitive.
  * Any unspecified value will result in {@link IllegalArgumentException}.
  * <p>
- * <b>[3]</b> The Catalog specification defined complex rules on
- * <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html#attrib.prefer">
- * the prefer attribute</a>. Although the prefer can be public or system, the
- * specification actually made system the preferred option, that is, no matter
+ * <b>[3]</b> The <a href="https://groups.oasis-open.org/higherlogic/ws/public/download/14810/xml-catalogs.pdf">Catalog specification</a>
+ * defined complex rules on the prefer attribute. Although it can be public or system,
+ * the specification made {@code system} the preferred option, that is, no matter
  * the option, a system entry is always used if found. Public entries are only
  * considered if the prefer is public and system entries are not found. It is
  * therefore recommended that the prefer attribute be set as public

diff --git a/src/java.xml/share/classes/javax/xml/catalog/CatalogManager.java b/src/java.xml/share/classes/javax/xml/catalog/CatalogManager.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 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
@@ -52,7 +52,7 @@ private CatalogManager() {
      * those referenced by the {@code nextCatalog} elements in the main catalog.
      * <p>
      * As specified in
-     * <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html#s.res.fail">
+     * <a href="https://groups.oasis-open.org/higherlogic/ws/public/download/14810/xml-catalogs.pdf">
      * XML Catalogs, OASIS Standard V1.1</a>, if a catalog entry is invalid, it
      * is ignored. In case all entries are invalid, the resulting Catalog object
      * will contain no Catalog elements. Any matching operation using the Catalog
@@ -126,7 +126,7 @@ public static CatalogResolver catalogResolver(Catalog catalog, CatalogResolver.N
      * those referenced by the {@code nextCatalog} elements in the main catalog.
      * <p>
      * As specified in
-     * <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html#s.res.fail">
+     * <a href="https://groups.oasis-open.org/higherlogic/ws/public/download/14810/xml-catalogs.pdf">
      * XML Catalogs, OASIS Standard V1.1</a>, if a catalog entry is invalid, it
      * is ignored. In case all entries are invalid, the resulting CatalogResolver
      * object will contain no valid catalog. Any resolution operation using the

diff --git a/src/java.xml/share/classes/javax/xml/catalog/CatalogResolver.java b/src/java.xml/share/classes/javax/xml/catalog/CatalogResolver.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 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
@@ -40,7 +40,7 @@
  * Transform {@link javax.xml.transform.URIResolver}, and resolves
  * external references using catalogs.
  * <p>
- * The <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html">
+ * The <a href="https://groups.oasis-open.org/higherlogic/ws/public/download/14810/xml-catalogs.pdf">
  * Catalog Standard</a> distinguished {@code external identifiers} from {@code uri entries}
  * as being used to solely identify DTDs, while {@code uri entries} for
  * other resources such as stylesheets and schema. The Java APIs, such as

diff --git a/src/java.xml/share/classes/javax/xml/catalog/Normalizer.java b/src/java.xml/share/classes/javax/xml/catalog/Normalizer.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 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
@@ -32,8 +32,7 @@
 /**
  * The Normalizer is responsible for normalizing Public and System Identifiers
  * as specified in section 6.2, 6.3 and 6.4 of the specification
- *  * <a
- * href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html">
+ * <a href="https://groups.oasis-open.org/higherlogic/ws/public/download/14810/xml-catalogs.pdf">
  * XML Catalogs, OASIS Standard V1.1, 7 October 2005</a>.
  *
  * @since 9

diff --git a/src/java.xml/share/classes/javax/xml/catalog/package-info.java b/src/java.xml/share/classes/javax/xml/catalog/package-info.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 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
@@ -26,8 +26,8 @@
 /**
  *
  * Provides the classes for implementing
- * <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html">
- *     XML Catalogs OASIS Standard V1.1, 7 October 2005</a>.
+ * <a href="https://groups.oasis-open.org/higherlogic/ws/public/download/14810/xml-catalogs.pdf">
+ * XML Catalogs OASIS Standard V1.1, 7 October 2005</a>.
  *
  * <p>
  * The Catalog API defines a standard solution for resolving external resources

diff --git a/src/java.xml/share/classes/javax/xml/namespace/QName.java b/src/java.xml/share/classes/javax/xml/namespace/QName.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 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
@@ -50,9 +50,9 @@
  * <strong><em>only</em></strong> the Namespace URI and local part.</p>
  *
  * <p>If not specified, the Namespace URI is set to {@link
- * javax.xml.XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI}.
+ * XMLConstants#NULL_NS_URI XMLConstants.NULL_NS_URI}.
  * If not specified, the prefix is set to {@link
- * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
+ * XMLConstants#DEFAULT_NS_PREFIX
  * XMLConstants.DEFAULT_NS_PREFIX}.</p>
  *
  * <p><code>QName</code> is immutable.</p>
@@ -89,13 +89,13 @@ public class QName implements Serializable {
      * and local part.</p>
      *
      * <p>If the Namespace URI is <code>null</code>, it is set to
-     * {@link javax.xml.XMLConstants#NULL_NS_URI
+     * {@link XMLConstants#NULL_NS_URI
      * XMLConstants.NULL_NS_URI}.  This value represents no
      * explicitly defined Namespace as defined by the <a
      * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
      * in XML</a> specification.  This action preserves compatible
      * behavior with QName 1.0.  Explicitly providing the {@link
-     * javax.xml.XMLConstants#NULL_NS_URI
+     * XMLConstants#NULL_NS_URI
      * XMLConstants.NULL_NS_URI} value is the preferred coding
      * style.</p>
      *
@@ -105,11 +105,11 @@ public class QName implements Serializable {
      * compatible behavior with QName 1.0. </p>
      *
      * <p>When using this constructor, the prefix is set to {@link
-     * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
+     * XMLConstants#DEFAULT_NS_PREFIX
      * XMLConstants.DEFAULT_NS_PREFIX}.</p>
      *
      * <p>The Namespace URI is not validated as a
-     * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
+     * <a href="https://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
      * The local part is not validated as a
      * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
      * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
@@ -134,13 +134,13 @@ public QName(final String namespaceURI, final String localPart) {
      * local part and prefix.</p>
      *
      * <p>If the Namespace URI is <code>null</code>, it is set to
-     * {@link javax.xml.XMLConstants#NULL_NS_URI
+     * {@link XMLConstants#NULL_NS_URI
      * XMLConstants.NULL_NS_URI}.  This value represents no
      * explicitly defined Namespace as defined by the <a
      * href="http://www.w3.org/TR/REC-xml-names/#ns-qualnames">Namespaces
      * in XML</a> specification.  This action preserves compatible
      * behavior with QName 1.0.  Explicitly providing the {@link
-     * javax.xml.XMLConstants#NULL_NS_URI
+     * XMLConstants#NULL_NS_URI
      * XMLConstants.NULL_NS_URI} value is the preferred coding
      * style.</p>
      *
@@ -151,12 +151,12 @@ public QName(final String namespaceURI, final String localPart) {
      *
      * <p>If the prefix is <code>null</code>, an
      * <code>IllegalArgumentException</code> is thrown.  Use {@link
-     * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
+     * XMLConstants#DEFAULT_NS_PREFIX
      * XMLConstants.DEFAULT_NS_PREFIX} to explicitly indicate that no
      * prefix is present or the prefix is not relevant.</p>
      *
      * <p>The Namespace URI is not validated as a
-     * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
+     * <a href="https://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
      * The local part and prefix are not validated as a
      * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
      * as specified in <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces
@@ -204,9 +204,9 @@ public QName(String namespaceURI, String localPart, String prefix) {
      * compatible behavior with QName 1.0. </p>
      *
      * <p>When using this constructor, the Namespace URI is set to
-     * {@link javax.xml.XMLConstants#NULL_NS_URI
+     * {@link XMLConstants#NULL_NS_URI
      * XMLConstants.NULL_NS_URI} and the prefix is set to {@link
-     * javax.xml.XMLConstants#DEFAULT_NS_PREFIX
+     * XMLConstants#DEFAULT_NS_PREFIX
      * XMLConstants.DEFAULT_NS_PREFIX}.</p>
      *
      * <p><em>In an XML context, all Element and Attribute names exist
@@ -329,28 +329,14 @@ public final int hashCode() {
     }
 
     /**
-     * <p><code>String</code> representation of this
-     * <code>QName</code>.</p>
-     *
-     * <p>The commonly accepted way of representing a <code>QName</code>
-     * as a <code>String</code> was
-     * <a href="http://jclark.com/xml/xmlns.htm">defined</a>
-     * by James Clark.  Although this is not a <em>standard</em>
-     * specification, it is in common use, e.g. {@link
-     * javax.xml.transform.Transformer#setParameter(String name, Object value)}.
-     * This implementation represents a <code>QName</code> as:
-     * "{" + Namespace URI + "}" + local part.  If the Namespace URI
-     * <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
-     * local part is returned.  An appropriate use of this method is
-     * for debugging or logging for human consumption.</p>
-     *
-     * <p>Note the prefix value is <strong><em>NOT</em></strong>
-     * returned as part of the <code>String</code> representation.</p>
-     *
-     * <p>This method satisfies the general contract of {@link
-     * java.lang.Object#toString() Object.toString()}.</p>
-     *
-     *  @return <code>String</code> representation of this <code>QName</code>
+     * {@return the string representation of this {@code QName}}
+     * The format is:
+     * <pre> {@code
+     *     {NamespaceURI}LocalPart
+     * }</pre>
+     * If {@code NamespaceURI} is {@code null}, only {@code LocalPart} is returned.
+     *
+     * @apiNote The {@code Prefix} is not returned in the string representation.
      */
     public String toString() {
         if (namespaceURI.equals(XMLConstants.NULL_NS_URI)) {
@@ -361,48 +347,25 @@ public String toString() {
     }
 
     /**
-     * <p><code>QName</code> derived from parsing the formatted
-     * <code>String</code>.</p>
-     *
-     * <p>If the <code>String</code> is <code>null</code> or does not conform to
-     * {@link #toString() QName.toString()} formatting, an
-     * <code>IllegalArgumentException</code> is thrown.</p>
-     *
-     * <p><em>The <code>String</code> <strong>MUST</strong> be in the
-     * form returned by {@link #toString() QName.toString()}.</em></p>
-     *
-     * <p>The commonly accepted way of representing a <code>QName</code>
-     * as a <code>String</code> was
-     * <a href="http://jclark.com/xml/xmlns.htm">defined</a>
-     * by James Clark.  Although this is not a <em>standard</em>
-     * specification, it is in common use, e.g. {@link
-     * javax.xml.transform.Transformer#setParameter(String name, Object value)}.
-     * This implementation parses a <code>String</code> formatted
-     * as: "{" + Namespace URI + "}" + local part.  If the Namespace
-     * URI <code>.equals(XMLConstants.NULL_NS_URI)</code>, only the
-     * local part should be provided.</p>
-     *
-     * <p>The prefix value <strong><em>CANNOT</em></strong> be
-     * represented in the <code>String</code> and will be set to
-     * {@link javax.xml.XMLConstants#DEFAULT_NS_PREFIX
-     * XMLConstants.DEFAULT_NS_PREFIX}.</p>
-     *
-     * <p>This method does not do full validation of the resulting
-     * <code>QName</code>.
-     * <p>The Namespace URI is not validated as a
-     * <a href="http://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
-     * The local part is not validated as a
+     * {@return a {@code QName} from its string representation}
+     * The string representation must be in the format returned by {@link #toString()}:
+     * <pre> {@code
+     *     {NamespaceURI}LocalPart
+     * }</pre>
+     * Since the {@code Prefix} is not represented in the string form, it will be
+     * set to {@link XMLConstants#DEFAULT_NS_PREFIX XMLConstants.DEFAULT_NS_PREFIX}.
+     *
+     * @apiNote This method does not perform full validation of the resulting
+     * {@code QName}. The {@code NamespaceURI} is not validated as a
+     * <a href="https://www.ietf.org/rfc/rfc2396.txt">URI reference</a>.
+     * The {@code LocalPart} is not validated as a
      * <a href="http://www.w3.org/TR/REC-xml-names/#NT-NCName">NCName</a>
      * as specified in
-     * <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a>.</p>
-     *
-     * @param qNameAsString <code>String</code> representation
-     * of the <code>QName</code>
-     *
-     * @throws IllegalArgumentException When <code>qNameAsString</code> is
-     *   <code>null</code> or malformed
+     * <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a>.
      *
-     * @return <code>QName</code> corresponding to the given <code>String</code>
+     * @param qNameAsString the string representation of the {@code QName}
+     * @throws IllegalArgumentException if {@code qNameAsString} is {@code null}
+     * or malformed
      * @see #toString() QName.toString()
      */
     public static QName valueOf(String qNameAsString) {