The topic maps standard does not restrict the method(s) you can use to refer to resources. For example the original ISO 13250 standard makes use of the HyTime multimedia linking language (which is not widely implemented), whereas the XTM 1.0 specification (and the XTM 1.0 DTD which is included as part of the second edition of the ISO standard) uses XLink.
TMAPI addresses this flexibility in addressing schemes by defining a simple generic model for all addresses. In this model and address is represented by a string. The format of the string (and the rules by which the string is interpreted as a reference to a resource) are determined by the address notation. In TMAPI the address notation is itself identified by a string.
To determine if a given notation is supported by a TMAPI implementation, TMAPI defines the feature string "http://tmapi.org/features/notation/notationID" where notationID is the identifer string for the address notation. You can then test for support for a given notation using code such as the following (which tests for support for the "URI" notation):
TopicMapSystemFactory factory = TopicMapSystemFactory.newInstance();
try {
factory.setFeature("http://tmapi.org/features/notation/URI", true);
} catch (FeatureNotSupportedException ex) {
System.err.println("No support for URI notation addresses!");
} catch (FeatureNotRecognizedException ex) {
System.err.println("Your topic map processor does not support URI notation addresses!");
}
As well as providing methods for retrieving the notation and address strings, the Locator interface provides a method for creating new Locators by resolving an address string relative to that Locator's address using the relative address resolution rules defined for the particular notation. For example, certain classes of URI (such as the http:// and file:// schemes) are "hierarchical" URIs with a defined algorithm for the resolution of relative addresses, so resolving the address "foo/bar.xtm" relative to the address "http://www.example.com/" will result in a URI notation locator with the address "http://www.example.com/foo/bar.xtm".
The most common form of address notation found on the Web is the URI. This includes the common http:// and file:// forms of address as well as less common urn: ftp:// wais: and so on. All URIs conform to a common generic syntax which is defined by an IETF specification (RFC 2396).
TMAPI defines the string "URI" as the notation identifier for URI notation addresses. So the code to create a URI notation address is:
Locator myLoc = tm.createLocator("http://www.example.com/some/uri", "URI");
Due to its widespread use on the Web, TMAPI also defines URI notation as the default notation for address strings, so you can also use the following code to the same effect:
Locator myLoc = tm.createLocator("http://www.example.com/some/uri");Implementations of the URI notation are required to support the resolution of relative addresses for hierarchical URI schemes. Implementations may (but are not required to) support relative address resolution mechanisms for other non-hierarchical URI schemes.
It is strongly recommended that you implement support for URI notation addresses.