Module java.xml
Package javax.xml.catalog

# Interface Catalog

public interface Catalog
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 `catalog` entry with a list of catalog entries. The entries can also be grouped with a `group` entry. The catalog and group entries may specify `prefer` and `xml:base` attributes that set preference of public or system type of entries and base URI to resolve relative URIs.

A catalog can be used in two situations:

- Locate the external resources with a public or system identifier;
- Locate an alternate URI reference with a URI.

For case 1, the standard defines 6 External Identifier Entries:
`public, system, rewriteSystem, systemSuffix, delegatePublic, and delegateSystem`.

While for case 2, it defines 4 URI Entries:
`uri, rewriteURI, uriSuffix and delegateURI`.

In addition to the above entry types, a catalog may define nextCatalog entries to add additional catalog entry files.

Since:
  9

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Stream<Catalog>`
  `catalogs()`
  Returns a sequential Stream of alternative Catalogs specified using the `nextCatalog` entries in the current catalog, and as the input of catalog files excluding the current catalog (that is, the first in the input list) when the Catalog object is created by the `CatalogManager`.
  `String`
  `matchPublic(String publicId)`
  Attempts to find a matching entry in the catalog by publicId.
  `String`
  `matchSystem(String systemId)`
  Attempts to find a matching entry in the catalog by systemId.
  `String`
  `matchURI(String uri)`
  Attempts to find a matching entry in the catalog by the uri element.

- ## Method Details

  - ### matchSystem

    String matchSystem(String systemId)
    Attempts to find a matching entry in the catalog by systemId.

    The method searches through the system-type entries, including `system, rewriteSystem, systemSuffix, delegateSystem`, and `group` entries in the current catalog in order to find a match.

    Resolution follows the steps listed below:

    - If a matching `system` entry exists, it is returned immediately.
    - If more than one `rewriteSystem` entry matches, the matching entry with the longest normalized `systemIdStartString` value is returned.
    - If more than one `systemSuffix` entry matches, the matching entry with the longest normalized `systemIdSuffix` value is returned.
    - If more than one `delegateSystem` entry matches, the matching entry with the longest matching `systemIdStartString` value is returned.
    Parameters:
      `systemId` - the system identifier of the entity to be matched
    Returns:
      a URI string if a mapping is found, or null otherwise

  - ### matchPublic

    String matchPublic(String publicId)
    Attempts to find a matching entry in the catalog by publicId. The method searches through the public-type entries, including `public, delegatePublic`, and `group` entries in the current catalog in order to find a match.

    Refer to the description about Feature PREFER in the table Catalog Features in class `CatalogFeatures`. Public entries are only considered if the `prefer` is `public` and `system` entries are not found.

    Resolution follows the steps listed below:

    - If a matching `public` entry is found, it is returned immediately.
    - If more than one `delegatePublic` entry matches, the matching entry with the longest matching `publicIdStartString` value is returned.
    Parameters:
      `publicId` - the public identifier of the entity to be matched
    Returns:
      a URI string if a mapping is found, or null otherwise
    See Also:
      - `CatalogFeatures.Feature`

  - ### matchURI

    String matchURI(String uri)
    Attempts to find a matching entry in the catalog by the uri element.

    The method searches through the uri-type entries, including `uri, rewriteURI, uriSuffix, delegateURI` and `group` entries in the current catalog in order to find a match.

    Resolution follows the steps listed below:

    - If a matching `uri` entry is found, it is returned immediately.
    - If more than one `rewriteURI` entry matches, the matching entry with the longest normalized `uriStartString` value is returned.
    - If more than one `uriSuffix` entry matches, the matching entry with the longest normalized `uriSuffix` value is returned.
    - If more than one `delegatePublic` entry matches, the matching entry with the longest matching `uriStartString` value is returned.
    Parameters:
      `uri` - the URI reference of the entity to be matched
    Returns:
      a URI string if a mapping is found, or null otherwise

  - ### catalogs

    Stream<Catalog> catalogs()
    Returns a sequential Stream of alternative Catalogs specified using the `nextCatalog` entries in the current catalog, and as the input of catalog files excluding the current catalog (that is, the first in the input list) when the Catalog object is created by the `CatalogManager`.

    The order of Catalogs in the returned stream is the same as the order in which the corresponding `nextCatalog` entries appear in the current catalog. The alternative catalogs from the input file list are appended to the end of the stream in the order they are entered.

    Returns:
      a sequential Stream of Catalogs