CatalogManager.java revision 1060:8c9a2a24752b
1/* 2 * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25package javax.xml.catalog; 26 27import java.net.URI; 28 29/** 30 * The Catalog Manager manages the creation of XML Catalogs and Catalog Resolvers. 31 * 32 * @since 9 33 */ 34public final class CatalogManager { 35 /** 36 * Creating CatalogManager instance is not allowed. 37 */ 38 private CatalogManager() { 39 } 40 41 /** 42 * Creates a {@code Catalog} object using the specified feature settings and 43 * uri(s) to one or more catalog files. 44 * <p> 45 * If {@code uris} is empty, system property {@code javax.xml.catalog.files}, 46 * as defined in {@link CatalogFeatures}, will be read to locate the initial 47 * list of catalog files. 48 * <p> 49 * If multiple catalog files are specified through the {@code uris} argument or 50 * {@code javax.xml.catalog.files} property, the first entry is considered 51 * the main catalog, while others are treated as alternative catalogs after 52 * those referenced by the {@code nextCatalog} elements in the main catalog. 53 * <p> 54 * As specified in 55 * <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html#s.res.fail"> 56 * XML Catalogs, OASIS Standard V1.1</a>, if a catalog entry is invalid, it 57 * is ignored. In case all entries are invalid, the resulting Catalog object 58 * will contain no Catalog elements. Any matching operation using the Catalog 59 * will return null. 60 * 61 * @param features the catalog features 62 * @param uris uri(s) to one or more catalogs. 63 * 64 * @return an instance of a {@code Catalog} 65 * @throws IllegalArgumentException if either the URIs are not absolute 66 * or do not have a URL protocol handler for the URI scheme 67 * @throws CatalogException If an error occurs while parsing the catalog 68 * @throws SecurityException if access to the resource is denied by the security manager 69 */ 70 public static Catalog catalog(CatalogFeatures features, URI... uris) { 71 Util.validateUrisSyntax(uris); 72 CatalogImpl catalog = new CatalogImpl(features, uris); 73 catalog.load(); 74 return catalog; 75 } 76 77 /** 78 * Creates an instance of a {@code CatalogResolver} using the specified catalog. 79 * 80 * @param catalog the catalog instance 81 * @return an instance of a {@code CatalogResolver} 82 */ 83 public static CatalogResolver catalogResolver(Catalog catalog) { 84 if (catalog == null) CatalogMessages.reportNPEOnNull("catalog", null); 85 return new CatalogResolverImpl(catalog); 86 } 87 88 /** 89 * Creates an instance of a {@code CatalogResolver} using the specified feature 90 * settings and uri(s) to one or more catalog files. 91 * <p> 92 * If {@code uris} is empty, system property {@code javax.xml.catalog.files}, 93 * as defined in {@link CatalogFeatures}, will be read to locate the initial 94 * list of catalog files. 95 * <p> 96 * If multiple catalog files are specified through the {@code uris} argument or 97 * {@code javax.xml.catalog.files} property, the first entry is considered 98 * the main catalog, while others are treated as alternative catalogs after 99 * those referenced by the {@code nextCatalog} elements in the main catalog. 100 * <p> 101 * As specified in 102 * <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html#s.res.fail"> 103 * XML Catalogs, OASIS Standard V1.1</a>, if a catalog entry is invalid, it 104 * is ignored. In case all entries are invalid, the resulting CatalogResolver 105 * object will contain no valid catalog. Any resolution operation using the 106 * resolver therefore will return as no mapping is found. See {@link CatalogResolver} 107 * for the behavior when no mapping is found. 108 * 109 * @param features the catalog features 110 * @param uris the uri(s) to one or more catalogs 111 * 112 * @return an instance of a {@code CatalogResolver} 113 * @throws IllegalArgumentException if either the URIs are not absolute 114 * or do not have a URL protocol handler for the URI scheme 115 * @throws CatalogException If an error occurs while parsing the catalog 116 * @throws SecurityException if access to the resource is denied by the security manager 117 */ 118 public static CatalogResolver catalogResolver(CatalogFeatures features, URI... uris) { 119 Catalog catalog = catalog(features, uris); 120 return new CatalogResolverImpl(catalog); 121 } 122} 123