From 471d63c91f9fdc9468cb4d483a242511bad026da Mon Sep 17 00:00:00 2001 From: Joe Wang Date: Fri, 24 Jan 2025 00:29:49 +0000 Subject: [PATCH] 8343609: Broken links in java.xml Reviewed-by: naoto, lancea, iris --- .../classes/javax/xml/catalog/Catalog.java | 5 +- .../javax/xml/catalog/CatalogFeatures.java | 9 +- .../javax/xml/catalog/CatalogManager.java | 6 +- .../javax/xml/catalog/CatalogResolver.java | 4 +- .../classes/javax/xml/catalog/Normalizer.java | 5 +- .../javax/xml/catalog/package-info.java | 6 +- .../classes/javax/xml/namespace/QName.java | 111 ++++++------------ 7 files changed, 53 insertions(+), 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 index bab7152543e3e..47dbe35c53fee 100644 --- 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 - * + * * XML Catalogs, OASIS Standard V1.1, 7 October 2005. *

* 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 index 4376bbe9fdf43..32936c30e0f84 100644 --- 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 @@ * [2] The value shall be exactly as listed in this table, case-sensitive. * Any unspecified value will result in {@link IllegalArgumentException}. *

- * [3] The Catalog specification defined complex rules on - * - * the prefer attribute. Although the prefer can be public or system, the - * specification actually made system the preferred option, that is, no matter + * [3] The Catalog specification + * 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 index 41336526e13aa..f859754b0dbd5 100644 --- 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. *

* As specified in - * + * * XML Catalogs, OASIS Standard V1.1, 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. *

* As specified in - * + * * XML Catalogs, OASIS Standard V1.1, 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 index 3fd4b6a7858fd..fd6556bafc47c 100644 --- 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. *

- * The + * The * Catalog Standard 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 index 01f1554a6b4c7..0c01d27437a5c 100644 --- 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 - * * + * * XML Catalogs, OASIS Standard V1.1, 7 October 2005. * * @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 index 70db1b31a6c6a..62a8f769a07e0 100644 --- 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 - * - * XML Catalogs OASIS Standard V1.1, 7 October 2005. + * + * XML Catalogs OASIS Standard V1.1, 7 October 2005. * *

* 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 index 94121d0d334d5..aaab6ae5333d3 100644 --- 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 @@ * only the Namespace URI and local part.

* *

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}.

* *

QName is immutable.

@@ -89,13 +89,13 @@ public class QName implements Serializable { * and local part.

* *

If the Namespace URI is null, 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 Namespaces * in XML 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.

* @@ -105,11 +105,11 @@ public class QName implements Serializable { * compatible behavior with QName 1.0.

* *

When using this constructor, the prefix is set to {@link - * javax.xml.XMLConstants#DEFAULT_NS_PREFIX + * XMLConstants#DEFAULT_NS_PREFIX * XMLConstants.DEFAULT_NS_PREFIX}.

* *

The Namespace URI is not validated as a - * URI reference. + * URI reference. * The local part is not validated as a * NCName * as specified in Namespaces @@ -134,13 +134,13 @@ public QName(final String namespaceURI, final String localPart) { * local part and prefix.

* *

If the Namespace URI is null, 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 Namespaces * in XML 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.

* @@ -151,12 +151,12 @@ public QName(final String namespaceURI, final String localPart) { * *

If the prefix is null, an * IllegalArgumentException 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.

* *

The Namespace URI is not validated as a - * URI reference. + * URI reference. * The local part and prefix are not validated as a * NCName * as specified in Namespaces @@ -204,9 +204,9 @@ public QName(String namespaceURI, String localPart, String prefix) { * compatible behavior with QName 1.0.

* *

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}.

* *

In an XML context, all Element and Attribute names exist @@ -329,28 +329,14 @@ public final int hashCode() { } /** - *

String representation of this - * QName.

- * - *

The commonly accepted way of representing a QName - * as a String was - * defined - * by James Clark. Although this is not a standard - * specification, it is in common use, e.g. {@link - * javax.xml.transform.Transformer#setParameter(String name, Object value)}. - * This implementation represents a QName as: - * "{" + Namespace URI + "}" + local part. If the Namespace URI - * .equals(XMLConstants.NULL_NS_URI), only the - * local part is returned. An appropriate use of this method is - * for debugging or logging for human consumption.

- * - *

Note the prefix value is NOT - * returned as part of the String representation.

- * - *

This method satisfies the general contract of {@link - * java.lang.Object#toString() Object.toString()}.

- * - * @return String representation of this QName + * {@return the string representation of this {@code QName}} + * The format is: + * 
 {@code
+     *     {NamespaceURI}LocalPart
+     * }
+ * 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() { } /** - *

QName derived from parsing the formatted - * String.

- * - *

If the String is null or does not conform to - * {@link #toString() QName.toString()} formatting, an - * IllegalArgumentException is thrown.

- * - *

The String MUST be in the - * form returned by {@link #toString() QName.toString()}.

- * - *

The commonly accepted way of representing a QName - * as a String was - * defined - * by James Clark. Although this is not a standard - * specification, it is in common use, e.g. {@link - * javax.xml.transform.Transformer#setParameter(String name, Object value)}. - * This implementation parses a String formatted - * as: "{" + Namespace URI + "}" + local part. If the Namespace - * URI .equals(XMLConstants.NULL_NS_URI), only the - * local part should be provided.

- * - *

The prefix value CANNOT be - * represented in the String and will be set to - * {@link javax.xml.XMLConstants#DEFAULT_NS_PREFIX - * XMLConstants.DEFAULT_NS_PREFIX}.

- * - *

This method does not do full validation of the resulting - * QName. - *

The Namespace URI is not validated as a - * URI reference. - * 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()}: + * 

 {@code
+     *     {NamespaceURI}LocalPart
+     * }
+ * 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 + * URI reference. + * The {@code LocalPart} is not validated as a * NCName * as specified in - * Namespaces in XML.

- * - * @param qNameAsString String representation - * of the QName - * - * @throws IllegalArgumentException When qNameAsString is - * null or malformed + * Namespaces in XML. * - * @return QName corresponding to the given String + * @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) {