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 */ 25 26package javax.xml.catalog; 27 28import java.util.stream.Stream; 29 30/** 31 * The Catalog class represents an entity Catalog as defined by 32 * <a 33 * href="https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html"> 34 * XML Catalogs, OASIS Standard V1.1, 7 October 2005</a>. 35 * <p> 36 * A catalog is an XML file that contains a root {@code catalog} entry with a list 37 * of catalog entries. The entries can also be grouped with a {@code group} entry. 38 * The catalog and group entries may specify {@code prefer} and {@code xml:base} 39 * attributes that set preference of public or system type of entries and base URI 40 * to resolve relative URIs. 41 * 42 * <p> 43 * A catalog can be used in two situations: 44 * <ul> 45 * <li>Locate the external resources with a public or system identifier; 46 * </li> 47 * <li>Locate an alternate URI reference with a URI. 48 * </li> 49 * </ul> 50 * <p> 51 * For case 1, the standard defines 6 External Identifier Entries:<br> 52 * {@code public, system, rewriteSystem, systemSuffix, delegatePublic, and 53 * delegateSystem}. 54 * <p> 55 * While for case 2, it defines 4 URI Entries:<br> 56 * {@code uri, rewriteURI, uriSuffix and delegateURI}. 57 * <p> 58 * In addition to the above entry types, a catalog may define nextCatalog 59 * entries to add additional catalog entry files. 60 * 61 * @since 9 62 */ 63public interface Catalog { 64 65 /** 66 * Attempts to find a matching entry in the catalog by systemId. 67 * 68 * <p> 69 * The method searches through the system-type entries, including {@code system, 70 * rewriteSystem, systemSuffix, delegateSystem}, and {@code group} entries in the 71 * current catalog in order to find a match. 72 * <p> 73 * Resolution follows the steps listed below: <br> 74 * <ul> 75 * <li>If a matching {@code system} entry exists, it is returned immediately.</li> 76 * <li>If more than one {@code rewriteSystem} entry matches, the matching entry with 77 * the longest normalized {@code systemIdStartString} value is returned.</li> 78 * <li>If more than one {@code systemSuffix} entry matches, the matching entry 79 * with the longest normalized {@code systemIdSuffix} value is returned.</li> 80 * <li>If more than one {@code delegateSystem} entry matches, the matching entry 81 * with the longest matching {@code systemIdStartString} value is returned.</li> 82 * </ul> 83 * 84 * @param systemId the system identifier of the entity to be matched 85 * 86 * @return a URI string if a mapping is found, or null otherwise 87 */ 88 public String matchSystem(String systemId); 89 90 /** 91 * Attempts to find a matching entry in the catalog by publicId. The method 92 * searches through the public-type entries, including {@code public, 93 * delegatePublic}, and {@code group} entries in the current catalog in order to find 94 * a match. 95 * <p> 96 * Refer to the description about <a href="CatalogFeatures.html#PREFER"> 97 * Feature PREFER in the table Catalog Features</a> in class 98 * {@link CatalogFeatures}. Public entries are only considered if the 99 * {@code prefer} is {@code public} and {@code system} entries are not found. 100 * <p> 101 * Resolution follows the steps listed below: <br> 102 * <ul> 103 * <li>If a matching {@code public} entry is found, it is returned immediately.</li> 104 * <li>If more than one {@code delegatePublic} entry matches, the matching entry 105 * with the longest matching {@code publicIdStartString} value is returned.</li> 106 * </ul> 107 * 108 * @param publicId the public identifier of the entity to be matched 109 * @see CatalogFeatures.Feature 110 * @return a URI string if a mapping is found, or null otherwise 111 */ 112 public String matchPublic(String publicId); 113 114 /** 115 * Attempts to find a matching entry in the catalog by the uri element. 116 * 117 * <p> 118 * The method searches through the uri-type entries, including {@code uri, 119 * rewriteURI, uriSuffix, delegateURI} and {@code group} entries in the current 120 * catalog in order to find a match. 121 * 122 * <p> 123 * Resolution follows the steps listed below: <br> 124 * <ul> 125 * <li>If a matching {@code uri} entry is found, it is returned immediately.</li> 126 * <li>If more than one {@code rewriteURI} entry matches, the matching entry with 127 * the longest normalized {@code uriStartString} value is returned.</li> 128 * <li>If more than one {@code uriSuffix} entry matches, the matching entry with 129 * the longest normalized {@code uriSuffix} value is returned.</li> 130 * <li>If more than one {@code delegatePublic} entry matches, the matching entry 131 * with the longest matching {@code uriStartString} value is returned.</li> 132 * </ul> 133 * 134 * @param uri the URI reference of the entity to be matched 135 * 136 * @return a URI string if a mapping is found, or null otherwise 137 */ 138 public String matchURI(String uri); 139 140 /** 141 * Returns a sequential Stream of alternative Catalogs specified using the 142 * {@code nextCatalog} entries in the current catalog, and as the input of 143 * catalog files excluding the current catalog (that is, the first in the 144 * input list) when the Catalog object is created by the {@link CatalogManager}. 145 * <p> 146 * The order of Catalogs in the returned stream is the same as the order 147 * in which the corresponding {@code nextCatalog} entries appear in the 148 * current catalog. The alternative catalogs from the input file list are 149 * appended to the end of the stream in the order they are entered. 150 * 151 * @return a sequential Stream of Catalogs 152 */ 153 public Stream<Catalog> catalogs(); 154 155} 156