1 /*
2 * Copyright (c) 2015, 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 */
25 package javax.xml.catalog;
26
27
28 /**
29 * The Catalog Manager manages the creation of XML Catalogs and Catalog Resolvers.
30 *
31 * @since 9
32 */
33 public final class CatalogManager {
34 /**
35 * Creating CatalogManager instance is not allowed.
36 */
37 private CatalogManager() {
38 }
39
40 /**
41 * Creates a {@code Catalog} object using the specified feature settings and
42 * path to one or more catalog files.
43 * <p>
44 * If {@code paths} is empty, system property {@code javax.xml.catalog.files}
45 * will be read to locate the initial list of catalog files.
46 * <p>
47 * If more than one catalog files are specified through the paths argument or
48 * {@code javax.xml.catalog.files} property, the first entry is considered
49 * the main catalog, while others are treated as alternative catalogs after
50 * those referenced by the {@code nextCatalog} elements in the main catalog.
51 * <p>
52 * As specified in
53 * <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html#s.res.fail">
54 * XML Catalogs, OASIS Standard V1.1</a>, invalid path entries will be ignored.
55 * No error will be reported. In case all entries are invalid, the resolver
56 * will return as no mapping is found.
57 *
58 * @param features the catalog features
59 * @param paths path(s) to one or more catalogs.
60 *
61 * @return an instance of a {@code Catalog}
62 * @throws CatalogException If an error occurs while parsing the catalog
63 */
64 public static Catalog catalog(CatalogFeatures features, String... paths) {
65 return new CatalogImpl(features, paths);
66 }
67
68 /**
69 * Creates an instance of a {@code CatalogResolver} using the specified catalog.
70 *
71 * @param catalog the catalog instance
72 * @return an instance of a {@code CatalogResolver}
73 */
74 public static CatalogResolver catalogResolver(Catalog catalog) {
75 if (catalog == null) CatalogMessages.reportNPEOnNull("catalog", null);
76 return new CatalogResolverImpl(catalog);
77 }
78
79 /**
80 * Creates an instance of a {@code CatalogUriResolver} using the specified catalog.
81 *
82 * @param catalog the catalog instance
83 * @return an instance of a {@code CatalogResolver}
84 */
85 public static CatalogUriResolver catalogUriResolver(Catalog catalog) {
86 if (catalog == null) CatalogMessages.reportNPEOnNull("catalog", null);
87 return new CatalogUriResolverImpl(catalog);
88 }
89
90 /**
91 * Creates an instance of a {@code CatalogResolver} using the specified feature
92 * settings and path to one or more catalog files.
93 * <p>
94 * If {@code paths} is empty, system property {@code javax.xml.catalog.files}
95 * will be read to locate the initial list of catalog files.
96 * <p>
97 * If more than one catalog files are specified through the paths argument or
98 * {@code javax.xml.catalog.files} property, the first entry is considered
99 * the main catalog, while others are treated as alternative catalogs after
100 * those referenced by the {@code nextCatalog} elements in the main catalog.
101 * <p>
102 * As specified in
103 * <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html#s.res.fail">
104 * XML Catalogs, OASIS Standard V1.1</a>, invalid path entries will be ignored.
105 * No error will be reported. In case all entries are invalid, the resolver
106 * will return as no mapping is found.
107 *
108 * @param features the catalog features
109 * @param paths the path(s) to one or more catalogs
110 *
111 * @return an instance of a {@code CatalogResolver}
112 * @throws CatalogException If an error occurs while parsing the catalog
113 */
114 public static CatalogResolver catalogResolver(CatalogFeatures features, String... paths) {
115 Catalog catalog = catalog(features, paths);
116 return new CatalogResolverImpl(catalog);
117 }
118
119 /**
120 * Creates an instance of a {@code CatalogUriResolver} using the specified
121 * feature settings and path to one or more catalog files.
122 * <p>
123 * If {@code paths} is empty, system property {@code javax.xml.catalog.files}
124 * will be read to locate the initial list of catalog files.
125 * <p>
126 * If more than one catalog files are specified through the paths argument or
127 * {@code javax.xml.catalog.files} property, the first entry is considered
128 * the main catalog, while others are treated as alternative catalogs after
129 * those referenced by the {@code nextCatalog} elements in the main catalog.
130 * <p>
131 * As specified in
132 * <a href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html#s.res.fail">
133 * XML Catalogs, OASIS Standard V1.1</a>, invalid path entries will be ignored.
134 * No error will be reported. In case all entries are invalid, the resolver
135 * will return as no mapping is found.
136 *
137 * @param features the catalog features
138 * @param paths the path(s) to one or more catalogs
139 *
140 * @return an instance of a {@code CatalogUriResolver}
141 * @throws CatalogException If an error occurs while parsing the catalog
142 */
143 public static CatalogUriResolver catalogUriResolver(CatalogFeatures features, String... paths) {
144 Catalog catalog = catalog(features, paths);
145 return new CatalogUriResolverImpl(catalog);
146 }
147 }