Catalogs Package

Maintainer: Petr Kuzel

Updated on: 6th feb 2001

Introduction

What is catalog?

In order to use a variety of XML tools in a variety of computer environments, the problem of addressing resources that are inaccessible using their explicit system identifiers must be solved.

The short term solution to this problem is to define an entity catalog that handles the simple cases of mapping an external entity's public identifier and/or system identifier to an alternate URI. This solution allows for a probably system-dependent but application-independent catalog. Though it does not handle all issues that a combination of a complete entity manager and storage manager addresses, it simplifies both the use of multiple products in a great majority of cases and the task of processing documents on different systems.

What is Entity Resolution?

Entity resolution is the process that an XML processor goes through when it has been requested to find another file[1] in the course of processing the file it's working on. The XML processor knows labelling information about the file such as its system identifier and possibly a name, public identifier, and so forth. These identifiers can be used to determine the actual location of the desired external file. This determination process (which "maps" the known labelling information into an actual location) is called an entity resolution, and the file that contains the specific mapping information is called the entity resolution catalog.

[1] file is used here for simplicity, but could be any other resource consisting of such things as declarations, a parsed entity, an unparsed entity, etc.


Requirements

  • Catalog can define public ID to system ID mappings.
  • Catalog must allow to mount user's catalogs
  • Mounted catalog's should be persistent
  • Catalog must provide mappings to OpenIDE APIs
  • Visualize build-in catalog
  • Define catalog SPI

    Dependencies

    OpenIDE should allow to add custom EntityResolvers.

    Developer's View

    OpenIDE Support

    XMLDataObject allows registering custom catalogs by two methods.

    XMLDataObject API

    @deprecated

    I call it Entity Resolving API. It consists of registerCatalogEntry() methods.

    Two new methods have been introduced into it to support users catalogs:

  • addEntityResolver(EntityResolver resolver)
  • removeEntityResolver(EntityResolver resolver)

    The mapping registered by registerCatalogEntry() must stay of

  • the highest priority
  • transient among IDE restarts
  • must use latter registered mapping prevails previous mapping strategy.

    Declarative way

    XMLDataObject recognize well known folder named XML/catalog containing EntityResolver's implemetations registrations.

    The Catalog package put there its implementation of EntityResolver.

    User's Persistent Catalogs

    A user can have its own catalog on some place following some DTD or other format (SOCAT). This feature supports integration of such catalogs into IDE mappings. Every catalog must provide a CatalogReader interface implementation. See SPI interface for details.

    The catalog implementation provides a EntityResolver implementation based upon mounted catalogs. The resolver is registered into the IDE resolver chain. See JavaDoc.


    User's View

    A user will browse and manage catalog using a node structure.
     + XML Catalog Browser ~-------------------------{root}
       + System Catalog [ro] ~--------------------{catalog}
       | + -//Netbeans Toolbars DTD//EN ~---{catalog entry}
       | + -//Other system DTD//EN
       | + -//X Catalog//EN
       + My SOCAT [ro]
       + My XCatalog [rw]
         + +//WML 1.1//EN
    

    Catalog Root

    Root of all catalogs used in system. It always contains a system catalog as a child.

    Actions:

    Catalog

    A catalog must be mounted by New action at Catalog Root. One mounted then all actions in XML module use mappings defined by the catalog. Depending on catalog type the mounting is persistent in per project basis.

    Actions:

    Catalog Entry

    It may be read-only depending on catalog provider type.

    Actions:

    Properties: