org.newsml.toolkit
Interface FormalNameNode

All Known Subinterfaces:
AssignedFormalName, FormalName, Instruction, NewsItemId, OfInterestTo, Party, ProviderId, TopicSet

public interface FormalNameNode

Base interface for three-part NewsML names.

Formal names are the key to NewsML's extensibility, and bear very strong similarities to XML Namespace-qualified names. Each formal name consists of three parts:

  1. A pointer to a vocabulary including the name. This property is roughly equivalent to an XML Namespace, but it may also be used to retrieve an actual document (or fragment of the current document) describing the vocabulary.
  2. The name of a scheme within the vocabulary (essentially, a mechanism for dividing large vocabularies into sections when needed. This property has no analogue in XML Namespaces.
  3. The name itself. This property is roughly equivalent to an XML localname in a Namespace-qualified name.

For full interoperability, applications must consider all three parts of the formal name.

Note that unlike many of the interfaces in this library, the FormalNameNode interface does not correspond to a single XML element type; instead, it is used to deliver formal-name information present in many different types of XML elements.

The vocabulary and scheme information for a formal name may appear in the XML element itself, or it may be defaulted from another element in the XML document or even from a separate document. To help avoid nasty surprises (such delays or failures retrieving large external catalogs over HTTP), this interface has two pairs of methods for retrieving the vocabulary and scheme: getVocabulary() and (in the derived FormalName and NewsItemId interfaces) FormalName.getScheme() and NewsItemId.getScheme() retrieve only the vocabulary and scheme explicitly provided in the XML element containing the formal name, and thus work in constant time; getDefaultVocabulary(boolean) and getDefaultScheme(boolean) look for DefaultVocabularyFor declarations in higher-level Catalog objects within the current document, and, if the useExternal parameter is set, in external catalogs as well. Please note that using this option could be extremely slow, depending on the quality of your network connection and the availability of the server hosting the catalog.

Version:
1.0
Author:
Reuters PLC

Method Summary
 java.lang.String getDefaultScheme(boolean useExternal)
          Get an explicit or defaulted scheme.
 java.lang.String getDefaultVocabulary(boolean useExternal)
          Get an explicit or defaulted vocabulary reference.
 java.lang.String getName()
          Get the local name.
 TopicSet getTopicSet(boolean useExternal)
          Get the topic set for the formal name.
 java.lang.String getVocabulary()
          Get an explicitly-specified vocabulary reference.
 java.lang.String toString()
          Generate a naive string representation of this FormalNameNode.
 java.lang.String toString(boolean useExternal)
          Generate a proper string representation of this formal name.
 

Method Detail

getName

public java.lang.String getName()
Get the local name.

The local name is the basic name, such as "length" or "person"; it may be qualified by a vocabulary and, optionally, a scheme. In the XML markup, the local name is usually specified by a FormalName attribute, but it occasionally appears as character-data content; this interface hides the inconsistency from the user.

Returns:
A string representing the local part of the name.
See Also:
getVocabulary()

getVocabulary

public java.lang.String getVocabulary()
Get an explicitly-specified vocabulary reference.

This method returns only a vocabulary that has been explicitly provided in the XML.

Returns:
A string representing a reference to the vocabulary, either a URI or a local Duid reference beginning with '#'.
See Also:
getDefaultVocabulary(boolean)

getDefaultVocabulary

public java.lang.String getDefaultVocabulary(boolean useExternal)
                                      throws java.io.IOException
Get an explicit or defaulted vocabulary reference.

A pointer to the vocabulary for the formal name. The pointer may be a reference to an internal topic set (beginning with '#'), or it may be a URL or URN. If the vocabulary comes from a resource with a DefaultVocabularyFor declaration, then the following order of precedence applies:

  1. If there is an internal Url for the resource (i.e. one beginning with '#'), return it; if there is more than one, return the first one found.
  2. Otherwise, if there is a Urn for the resource, return it.
  3. Otherwise, if there are any Urls at all for the resource return the first one.
  4. Otherwise, return null.

An explicit Vocabulary attribute always takes precedence over a DefaultVocabularyFor declaration, however.

Parameters:
useExternal - If true, follow links outside of the current NewsML document during catalog resolution.
Returns:
A string representing a pointer to the vocabulary for the formal name, or null if none was provided.
Throws:
java.io.IOException - If there is an error retrieving an external resource.
NewsMLException - If there is an error retrieving an ancestor Catalog (see Catalog.getReferencedCatalog(boolean)).
See Also:
getName(), getVocabulary()

getDefaultScheme

public java.lang.String getDefaultScheme(boolean useExternal)
                                  throws java.io.IOException
Get an explicit or defaulted scheme.

See getDefaultVocabulary(boolean) for resolution details.

Parameters:
useExternal - If true, follow links outside of the current document for Catalog resolution.
Returns:
The scheme, or null if none was found.
Throws:
java.io.IOException - If there is an error retrieving an external resource.
NewsMLException - If there is an error retrieving an ancestor Catalog (see Catalog.getReferencedCatalog(boolean)).
See Also:
FormalName.getScheme(), NewsItemId.getScheme()

getTopicSet

public TopicSet getTopicSet(boolean useExternal)
                     throws java.io.IOException
Get the topic set for the formal name.

This method will attempt to look up a topic set corresponding to the vocabulary.

Parameters:
useExternal - If true, follow links outside of the current document for topic set resolution.
Returns:
The topic set, or null if none could be found.
Throws:
java.io.IOException - If there is an error retrieving an external resource.

toString

public java.lang.String toString()
Generate a naive string representation of this FormalNameNode.

The generated string will consist of the vocabulary URL in braces, followed by the scheme in braces, followed by the local name, as in

 {Vocabulary}{Scheme}LocalName
 

If the vocabulary or scheme is absent, it will be represented by an empty pair of braces.

NOTE: to avoid problems during debugging situations, the string will be generated only from the information supplied explicitly in attributes; defaulted vocabularies and schemes from DefaultVocabularyFor declarations in Resource objects will not be used. To get the defaulted information in the string, use the toString(boolean) method.

Overrides:
toString in class java.lang.Object
Returns:
A string representation of the formal name.
See Also:
getVocabulary(), FormalName.getScheme(), NewsItemId.getScheme(), getName()

toString

public java.lang.String toString(boolean useExternal)
                          throws java.io.IOException
Generate a proper string representation of this formal name.

The format is the same as that used by the zero-argument toString() method, but this method will look for defaulted vocabulary and scheme information from catalogs in the current document, and, if the useExternal flag is true, from external documents as well.

Parameters:
useExternal - If true, follow links outside of the current NewsML document during catalog resolution.
Returns:
A string representation of the formal name.
Throws:
java.io.IOException - If there is an error retrieving an external resource.
See Also:
getDefaultVocabulary(boolean), getDefaultScheme(boolean), getName()