Component balxml_namespaceregistry [Package balxml]

Provide a unique integer ID for each XML namespace. More...

Namespaces
namespace	balxml

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Preregistered Namespaces
  • Thread Safety
  • Usage

Purpose:

Provide a unique integer ID for each XML namespace.

Classes:

balxml::NamespaceRegistry

namespace-to-id mapping registry

See also:

Component balxml_prefixstack

Description:

This component provides an in-core value-semantic type, balxml::NamespaceRegistry, that associates an integer ID with each registered namespace URI. In typical usage, client code would call the lookupOrRegister method each time it encounters a namespace URI. The lookupOrRegister method will return the ID corresponding to the URI, assigning a new ID if none already exists. The client can also retrieve the ID an already-registered namespace by providing the URI to the lookup method and can retrieve the URI of an already-registered namespace by providing the ID to the lookup method.

Note that namespace IDs may be negative. Client code should not assume an incremental assignment of IDs starting at zero. (See Preregistered Namespaces), below.

Preregistered Namespaces:

Even before any namespaces have been registered, a balxml::NamespaceRegistry can be used to lookup several preregistered namespaces. The IDs for these preregistered namespaces are declared as constants within the balxml::NamespaceRegistry class. These constants and their associated URI's are as follows:

  Namespace ID               URI String
  ============               ==========
  BAEXML_XML                   http://www.w3.org/XML/1998/namespace
  BAEXML_XMLNS                 http://www.w3.org/2000/xmlns/
  BAEXML_XMLSCHEMA             http://www.w3.org/2001/XMLSchema
  BAEXML_XMLSCHEMA_INSTANCE    http://www.w3.org/2001/XMLSchema-instance
  BAEXML_WSDL                  http://schemas.xmlsoap.org/wsdl/
  BAEXML_WSDL_SOAP             http://schemas.xmlsoap.org/wsdl/soap/
  BAEXML_BDEM                  http://bloomberg.com/schemas/bdem

Note that the above constants are negative numbers. In addition, the value, -1, is permanently assigned to the empty string. The use of predefined namespace IDs allows client code avoid lookups of the above, well-known URIs.

Thread Safety:

It is safe to read or modify multiple instances of balxml::NamespaceRegistry simultaneously, each from a separate thread. It is safe to read a single instance of balxml::NamespaceRegistry from multiple threads, provided no thread is modifying it at the same time. It is not safe to read or modify an instance of balxml::NamespaceRegistry from one thread while any other thread is modifying the same instance.

Usage:

Typically, a program will register namespaces as it encounters them in an XML document. Alternatively, namespaces that are important to the program are registered in advance, as in the following code:

  const char googleUri[] = "http://www.google.com/schemas/results.xsd";
  const char yahooUri[]  = "http://www.yahoo.com/xsd/searchResults.xsd";

  balxml::NamespaceRegistry namespaceRegistry;
  int googleId = namespaceRegistry.lookupOrRegister(googleUri);
  assert(googleId >= 0);
  int yahooId = namespaceRegistry.lookupOrRegister(yahooUri);
  assert(yahooId >= 0);
  assert(yahooId != googleId);

Later, IDs can be looked up without concern for whether they have already been registered. Any new namespaces are simply given a new ID:

  char input[100];

  // First input is a new namespace URI.
  bsl::strcpy(input, "http://www.bloomberg.com/schemas/example.xsd");
  int id1 = namespaceRegistry.lookupOrRegister(input);
  assert(id1 >= 0);
  assert(id1 != googleId);
  assert(id1 != yahooId);

  // Next input happens to be the same as yahoo.
  bsl::strcpy(input, "http://www.yahoo.com/xsd/searchResults.xsd");
  int id2 = namespaceRegistry.lookupOrRegister(input);
  assert(id2 == yahooId);

If one of the preregistered namespaces is presented, it's predefined ID is returned, even though it was never explicitly registered:

  bsl::strcpy(input, "http://www.w3.org/2001/XMLSchema");
  int id3 = namespaceRegistry.lookupOrRegister(input);
  assert(id3 == balxml::NamespaceRegistry::BAEXML_XMLSCHEMA);

Using the lookup method, a namespace ID can be looked up without registering it. In this case, an unregistered namespace will result in an ID of -1:

  assert(googleId  == namespaceRegistry.lookup(googleUri));
  assert(balxml::NamespaceRegistry::BAEXML_BDEM ==
         namespaceRegistry.lookup("http://bloomberg.com/schemas/bdem"));
  assert(-1 == namespaceRegistry.lookup("urn:1234"));

There is also a lookup method for performing the reverse mapping -- from ID to URI:

  const char *uri = namespaceRegistry.lookup(googleId);
  assert(0 == bsl::strcmp(uri, googleUri));