|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
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.
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 |
public java.lang.String getName()
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.
getVocabulary()
public java.lang.String getVocabulary()
This method returns only a vocabulary that has been explicitly provided in the XML.
getDefaultVocabulary(boolean)
public java.lang.String getDefaultVocabulary(boolean useExternal) throws java.io.IOException
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:
An explicit Vocabulary attribute always takes precedence over a DefaultVocabularyFor declaration, however.
useExternal
- If true, follow links outside of the current
NewsML document during catalog resolution.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)
).getName()
,
getVocabulary()
public java.lang.String getDefaultScheme(boolean useExternal) throws java.io.IOException
See getDefaultVocabulary(boolean)
for resolution details.
useExternal
- If true, follow links outside of the current
document for Catalog resolution.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)
).FormalName.getScheme()
,
NewsItemId.getScheme()
public TopicSet getTopicSet(boolean useExternal) throws java.io.IOException
This method will attempt to look up a topic set corresponding to the vocabulary.
useExternal
- If true, follow links outside of the
current document for topic set resolution.java.io.IOException
- If there is an error retrieving
an external resource.public java.lang.String toString()
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.
toString
in class java.lang.Object
getVocabulary()
,
FormalName.getScheme()
,
NewsItemId.getScheme()
,
getName()
public java.lang.String toString(boolean useExternal) throws java.io.IOException
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.
useExternal
- If true, follow links outside of the current
NewsML document during catalog resolution.java.io.IOException
- If there is an error retrieving
an external resource.getDefaultVocabulary(boolean)
,
getDefaultScheme(boolean)
,
getName()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |