Motivation

The XML catalogs are used to resolve the version of the Netopeer schema to URI of this schema. This allows to frontends and libraries to be independent on emplacement of the Netopeer schemas. The version is the namespace for the XML configuration in the Netopeer system.

For example: if we have the XML configuration, which begins:

<configuration xmlns="http://www.liberouter.org/ns/netopeer/1.1.10">

The http://www.liberouter.org/ns/netopeer/1.1.10 is the version of the XML configuration (and its namespace too). It can be resolved by catalog to the local path (e.g., /usr/local/etc/netopeer/1.1.10/netopeer.rng)

All operations with XML catalog are fully transparent for users.

Local catalog in Netopeer

There is a local catalog used in the Netopeer. This catalog is used for resolving the version to the name of the file in the local filesystem. E.g., the version http://www.liberouter.org/ns/netopeer/1.1.10 corresponds /usr/local/etc/netopeer/1.1.10/netopeer.rng. The content of this catalog depends on schemas which user has installed. It is possible to have more than one Netopeer catalog.

Working with catalogs in the netopeer_xml library

Here is described how the netopeer_xml library (which is used by all rontends) works with catalogs.

Importing catalogs

It is important to import some catalog before the resolving the version of the Netopeer schema. It may be done by several ways:

• using preprocessing instruction in the XML configuration to import specified catalog: <?oasis-xml-catalog catalog="someURI"?>
• using the default system catalog - this is the local catalog placed at /etc/xml/catalog
• using Netopeer default catalog - it is created link to this catalog from the system catalog during Netopeer installation (root privileg is needed)
• using Netopeer configuration file to set the catalog for the netopeer_xml library (the configuration files are /etc/netopeer, /usr/local/etc/netopeer, &vlnka;/.netopeer etc., you can set the location during Netopeer install)
• using the XML_CATALOG_FILES variable - it contains all catalogs processed by XML parser; you can set your own catalogs list

Note: If there is some error during importing the catalog, the exception is thrown - see documentation of the netopeer_xml library for more.

Resolving the version to the URI

The version of the XML configuration is resolved to the URI by the follow way:

First the version is resolved by the local catalog to the local URI, if possible. It means that if the user has installed the proper version of the Netopeer schema on his system, this schema is used.

If the resolution by the local catalog fails (e.g., the version of the XML configuration is newer than schemas which the user has installed), the schema from the Netopeer Web is used. The URL of this schema is the namespace of the XML configuration. There are all Netopeer schemas on the Web (these schemas are managed by Netopeer developers). If this step fails (e.g., the user has not connection to the Netopeer Web or the version of the XML configuration is "wired"), the exception is thrown (see documentation of the netopeer_xml library for more).

Note: The local catalog is ever imported, because it is imported to the system catalog and the system catalog is ever imported automatically by the XML parser.

Managing the local catalog in the Netopeer distribution

There are some scripts for managing the catalogs in the Netopeer (most of these scripts are for other Netopeer tools or for testing, not for common users):

• mkcatalog - creates the catalog (see mkcatalog --help for more)
• catalogs - for editing the catalog (see catalogs --help for more)
• installschema - installs the new Netopeer schema and updates the local catalog

The local catalog for Netopeer is implicitly located at /usr/local/etc/netopeer/. It is imported to the system catalog at /etc/xml/catalog (the link to the system catalog is added during install of the Netopeer distribution; if you install Netopeer as a non-root, it is created the system_catalog_path script which root must execute to patch the system catalog).

There is added the line like this to the system catalog:

<nextCatalog catalog="/usr/local/etc/netopeer/catalog"/>

Other catalogs can be used too, see section Importing catalogs for more.

Installing the new Netopeer schema

User can install the new Netopeer schema during the installschema script. It installs the schema implicitly to the /usr/local/etc/netopeer/<version>/netopeer.rng and then updates the local catalog (the <version> is only the number here, e.g., 1.1.10).

So, installation is fully transparent for the user and he/she cannot know that there is some catalog in the Netopeer.