org.newsml.toolkit
Interface FormalNameNode

All Known Subinterfaces:

AssignedFormalName, FormalName, Instruction, NewsItemId, OfInterestTo, Party, Property, 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 local name 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:

2.0

Author:

Reuters PLC

Method Summary

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

Method Detail

getName

public Text 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 under a different attribute name (such as "HowPresent") or even as character-data content; this interface hides the inconsistency from the user.

Returns:

Text containing the local part of the name.

See Also:

getVocabulary()

getVocabulary

public Text getVocabulary()

Get an explicitly-specified vocabulary reference.

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

Returns:

Text containing a reference to the vocabulary, either a URI or a local Duid reference beginning with '#'.

See Also:

getDefaultVocabulary(boolean)

getDefaultVocabulary

public String getDefaultVocabulary(boolean useExternal)
                            throws IOException

Get an explicit or defaulted vocabulary reference.

Get 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.

Note 1: the XPath for the DefaultVocabularyFor declaration will be applied using the parent of the containing Catalog as the context node (the NewsML 1.0 functional specification fails to specify any context node, so this is a best guess). According to the XPath specification, an XPath expression like "TopicType" is an abbreviation of "child::TopicType", so it will fail unless TopicType is a sibling of the Catalog. Normally, it will be best to write expressions like "descendant::TopicType" to avoid ambiguity.

Note 2: XPath expressions may match the FormalName attribute or the containing element. If an attribute other than FormalName holds the formal name (as is the case with the %assignment; attributes Importance, Confidence, and HowPresent) the XPath expression must match the attribute itself to avoid ambiguity.

Parameters:

useExternal - If true, follow links outside of the current NewsML document during catalog resolution.

Returns:

Text containing a pointer to the vocabulary for the formal name, or null if none was provided.

Throws:

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 String getDefaultScheme(boolean useExternal)
                        throws 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:

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 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:

IOException - If there is an error retrieving an external resource.

findTopic

public Topic findTopic(boolean useExternal)
                throws IOException

Find the topic associated with this formal name.

Try to find a topic for this formal name, using the vocabulary to locate a TopicSet, and then the name and scheme to locate a Topic. This method will follow all TopicSetRefs within the limits of the useExternal parameter, but will fail with NewsML URNs.

Parameters:

useExternal - If true, follow links outside of the current NewsML document during topic-set reference resolution.

Returns:

The Topic associated with this FormalNameNode, or null if none could be located.

Throws:

IOException - If there is an error retrieving an external resource.

toString

public 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 Object

Returns:

A string representation of the formal name.

See Also:

getVocabulary(), FormalName.getScheme(), NewsItemId.getScheme(), getName()

toString

public String toString(boolean useExternal)
                throws 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:

IOException - If there is an error retrieving an external resource.

See Also:

getDefaultVocabulary(boolean), getDefaultScheme(boolean), getName()