8316996: Catalog API Enhancement: add a factory method

Reviewed-by: naoto, lancea

src/java.xml/share/classes/javax/xml/catalog/CatalogImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2023, 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
@@ -41,6 +41,7 @@
 import static javax.xml.catalog.CatalogFeatures.DEFER_TRUE;
 import javax.xml.catalog.CatalogFeatures.Feature;
 import static javax.xml.catalog.CatalogMessages.formatMessage;
+import javax.xml.catalog.CatalogResolver.NotFoundAction;
 import javax.xml.parsers.ParserConfigurationException;
 import javax.xml.parsers.SAXParser;
 import javax.xml.parsers.SAXParserFactory;
@@ -59,8 +60,8 @@ class CatalogImpl extends GroupEntry implements Catalog {
     //Value of the defer attribute to determine if alternative catalogs are read
     boolean isDeferred = true;
 
-    //Value of the resolve attribute
-    ResolveType resolveType = ResolveType.STRICT;
+    //Value of the resolve attribute mapped to the resolver's action type
+    NotFoundAction resolveType = NotFoundAction.STRICT;
 
     //indicate whether the Catalog is empty
     boolean isEmpty;
@@ -259,15 +260,15 @@ public boolean isDeferred() {
      * @param value The value of the resolve attribute
      */
     public final void setResolve(String value) {
-        resolveType = ResolveType.getType(value);
+        resolveType = NotFoundAction.getType(value);
     }
 
     /**
      * Gets the value of the resolve attribute
      *
      * @return The value of the resolve attribute
      */
-    public final ResolveType getResolve() {
+    public final NotFoundAction getResolve() {
         return resolveType;
     }
 

src/java.xml/share/classes/javax/xml/catalog/CatalogManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2023, 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
@@ -77,6 +77,12 @@ public static Catalog catalog(CatalogFeatures features, URI... uris) {
     /**
      * Creates an instance of a {@code CatalogResolver} using the specified catalog.
      *
+     * @apiNote The {@code CatalogResolver} created by this method delegates to
+     * the underlying {@code catalog}'s RESOLVE property. The {@code CatalogResolver}
+     * created by {@link #catalogResolver(Catalog, CatalogResolver.NotFoundAction)
+     * catalogResover(Catalog, CatalogResolver.NotFoundAction)} is based on the
+     * specified action type when it is unable to resolve a reference.
+     *
      * @param catalog the catalog instance
      * @return an instance of a {@code CatalogResolver}
      */
@@ -85,6 +91,28 @@ public static CatalogResolver catalogResolver(Catalog catalog) {
         return new CatalogResolverImpl(catalog);
     }
 
+    /**
+     * Creates a {@code CatalogResolver} that resolves external references with the given
+     * {@code catalog} and {@link CatalogResolver.NotFoundAction action} type
+     * that determines the behavior when unable to resolve a reference.
+     * <p>
+     * The {@link CatalogResolver.NotFoundAction action} types are mapped to the values
+     * of the {@link CatalogFeatures.Feature#RESOLVE RESOLVE} property.
+     *
+     * @param catalog the catalog instance
+     * @param action the action to be taken when unable to resolve a reference
+     *
+     * @return a {@code CatalogResolver} with the {@code catalog} and {@code action} type
+     *
+     * @since 22
+     */
+    public static CatalogResolver catalogResolver(Catalog catalog, CatalogResolver.NotFoundAction action) {
+        if (catalog == null) CatalogMessages.reportNPEOnNull("catalog", null);
+        if (action == null) CatalogMessages.reportNPEOnNull("action", null);
+
+        return new CatalogResolverImpl(catalog, action);
+    }
+
     /**
      * Creates an instance of a {@code CatalogResolver} using the specified feature
      * settings and uri(s) to one or more catalog files.

src/java.xml/share/classes/javax/xml/catalog/CatalogReader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2023, 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
@@ -159,7 +159,7 @@ public void startElement(String namespaceURI,
                                 CatalogFeatures.DEFER_TRUE : CatalogFeatures.DEFER_FALSE;
                     }
                     if (resolve == null) {
-                        resolve = catalog.getResolve().literal;
+                        resolve = catalog.getResolve().toString();
                     }
                     //override property settings with those from the catalog file
                     catalog.setResolve(resolve);
@@ -172,7 +172,7 @@ public void startElement(String namespaceURI,
                 return;
             } else {
                 inGroup = true;
-                group = new GroupEntry(catalog, base, prefer);
+                group = new GroupEntry(catalog, Util.getAbsoluteURI(catalog.systemId, base), prefer);
                 catalog.addEntry(group);
                 return;
             }

src/java.xml/share/classes/javax/xml/catalog/CatalogResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2023, 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
@@ -235,4 +235,55 @@ public InputStream resolveEntity(String publicId, String systemId,
     public LSInput resolveResource(String type, String namespaceUri,
             String publicId, String systemId, String baseUri);
 
+    /**
+     * Defines the actions that a CatalogResolver may take when it is unable to
+     * resolve an external reference. The actions are mapped to the string values
+     * of the {@link CatalogFeatures.Feature#RESOLVE RESOLVE} property.
+     *
+     * @since 22
+     */
+    public static enum NotFoundAction {
+        /**
+         * Indicates that the processing should continue as defined by the
+         * {@link CatalogFeatures.Feature#RESOLVE RESOLVE} property.
+         */
+        CONTINUE {
+            @Override
+            public String toString() { return "continue"; }
+        },
+        /**
+         * Indicates that the reference is skipped as defined by the
+         * {@link CatalogFeatures.Feature#RESOLVE RESOLVE} property.
+         */
+        IGNORE {
+            @Override
+            public String toString() { return "ignore"; }
+        },
+        /**
+         * Indicates that the resolver should throw a CatalogException as defined
+         * by the {@link CatalogFeatures.Feature#RESOLVE RESOLVE} property.
+         */
+        STRICT {
+            @Override
+            public String toString() { return "strict"; }
+        };
+
+        /**
+         * Returns the action type mapped to the specified
+         * {@link CatalogFeatures.Feature#RESOLVE resolve} property.
+         *
+         * @param resolve the value of the RESOLVE property
+         * @return the action type
+         */
+        static public NotFoundAction getType(String resolve) {
+            for (NotFoundAction type : NotFoundAction.values()) {
+                if (type.toString().equals(resolve)) {
+                    return type;
+                }
+            }
+            CatalogMessages.reportIAE(CatalogMessages.ERR_INVALID_ARGUMENT,
+                    new Object[]{resolve, "RESOLVE"}, null);
+            return null;
+        }
+    }
 }

src/java.xml/share/classes/javax/xml/catalog/CatalogResolverImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2023, 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
@@ -51,16 +51,34 @@
  */
 final class CatalogResolverImpl implements CatalogResolver {
     Catalog catalog;
+    // resolution action type
+    NotFoundAction resolveType;
 
     /**
      * Construct an instance of the CatalogResolver from a Catalog.
      *
      * @param catalog A Catalog.
      */
     public CatalogResolverImpl(Catalog catalog) {
-        this.catalog = catalog;
+        this(catalog, null);
     }
 
+    /**
+     * Construct an instance of the CatalogResolver from a Catalog and the
+     * {@link CatalogResolver.NotFoundAction action} type.
+     *
+     * @param catalog a Catalog object
+     * @param action the action type
+     */
+    public CatalogResolverImpl(Catalog catalog, NotFoundAction action) {
+        this.catalog = catalog;
+        // Note: can only happen in this impl
+        if (action == null) {
+            resolveType = ((CatalogImpl) catalog).getResolve();
+        } else {
+            resolveType = action;
+        }
+    }
     /*
        Implements the EntityResolver interface
     */
@@ -91,7 +109,6 @@ public InputSource resolveEntity(String publicId, String systemId) {
             return new InputSource(resolvedSystemId);
         }
 
-        GroupEntry.ResolveType resolveType = ((CatalogImpl) catalog).getResolve();
         switch (resolveType) {
             case IGNORE:
                 return new InputSource(new StringReader(""));
@@ -145,7 +162,6 @@ public Source resolve(String href, String base) {
 
         //Report error or return the URI as is when no match is found
         if (result == null) {
-            GroupEntry.ResolveType resolveType = c.getResolve();
             switch (resolveType) {
                 case IGNORE:
                     return new SAXSource(new InputSource(new StringReader("")));
@@ -229,7 +245,6 @@ public InputStream resolveEntity(String publicId, String systemId, String baseUr
 
         }
 
-        GroupEntry.ResolveType resolveType = ((CatalogImpl) catalog).getResolve();
         switch (resolveType) {
             case IGNORE:
                 return null;
@@ -250,7 +265,6 @@ public LSInput resolveResource(String type, String namespaceURI, String publicId
             return new LSInputImpl(is.getSystemId());
         }
 
-        GroupEntry.ResolveType resolveType = ((CatalogImpl) catalog).getResolve();
         switch (resolveType) {
             case IGNORE:
                 return null;

src/java.xml/share/classes/javax/xml/catalog/GroupEntry.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2023, 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
@@ -107,34 +107,6 @@ public boolean prefer(String prefer) {
         }
     }
 
-    /**
-     * PreferType represents possible values of the resolve property
-     */
-    public static enum ResolveType {
-        STRICT(CatalogFeatures.RESOLVE_STRICT),
-        CONTINUE(CatalogFeatures.RESOLVE_CONTINUE),
-        IGNORE(CatalogFeatures.RESOLVE_IGNORE);
-
-        final String literal;
-
-        ResolveType(String literal) {
-            this.literal = literal;
-        }
-
-        static public ResolveType getType(String resolveType) {
-            for (ResolveType type : ResolveType.values()) {
-                if (type.isType(resolveType)) {
-                    return type;
-                }
-            }
-            return null;
-        }
-
-        public boolean isType(String type) {
-            return literal.equals(type);
-        }
-    }
-
     /**
      * Constructs a GroupEntry
      *

src/java.xml/share/classes/javax/xml/catalog/Util.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2023, 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
@@ -28,6 +28,7 @@
 import java.io.IOException;
 import java.net.MalformedURLException;
 import java.net.URI;
+import java.net.URL;
 import java.util.Iterator;
 import java.util.jar.JarEntry;
 import java.util.jar.JarFile;
@@ -267,4 +268,32 @@ static void validateFeatureInput(Feature f, String value) {
             Util.validateUrisSyntax(value.split(";"));
         }
     }
+
+    /**
+     * Returns the absolute form of the specified uri after resolving it against
+     * the base. Returns the uri as is if it's already absolute.
+     *
+     * @param base the base, that is the system id of the catalog within the
+     * Catalog implementation
+     * @param uri the specified uri
+     * @return the absolute form of the specified uri
+     */
+    @SuppressWarnings("deprecation")
+    static String getAbsoluteURI(String base, String uri) {
+        String temp = "";
+        try {
+            URL baseURL = new URL(base);
+            URI specURI = URI.create(uri);
+
+            if (specURI.isAbsolute()) {
+                temp = specURI.toURL().toString();
+            } else {
+                temp = (new URL(baseURL, uri)).toString();
+            }
+        } catch (MalformedURLException ex) {
+            // shouldn't happen since inputs are validated, report error in case
+            CatalogMessages.reportError(CatalogMessages.ERR_INVALID_CATALOG);
+        }
+        return temp;
+    }
 }