org.ceryle.xtm
Class XtmTopic

java.lang.Object
  org.ceryle.xtm.XtmNode
      org.ceryle.xtm.XtmTopic

All Implemented Interfaces:

Comparable, Iterator, Constants

public class XtmTopic
extends XtmNode
implements Comparable

Defines a topic object, as in a topic map, such that instances of this class are objects containing the features of XTM topics, designed to assist in building in-memory representations via the XtmProcessor class. XtmTopics are not representations of XTM <topic> Elements.

Since:

JDK1.3

Version:

$Id: XtmTopic.java,v 3.3 2007-06-15 12:10:36 altheim Exp $

Author:

Murray Altheim

Field Summary

protected TreeSet	baseNames The TreeSet containing any scoped base names (as XtmBaseName objects) of this XtmTopic.
protected XtmOccurrence	description The XtmOccurrence acting as a textual description of this XtmTopic.
protected TreeSet	occurrences The TreeSet containing XtmOccurrence objects indicating the occurrences of this XtmTopic.
protected TreeSet	subjectIdentity The TreeSet containing XtmReference objects indicating the subjectIdentity of this XtmTopic.
protected TreeSet	types The TreeSet containing XtmReference objects indicating the type of this XtmTopic; this shows up in XML syntax as the content of an <instanceOf> element.

Fields inherited from class org.ceryle.xtm.XtmNode

ASSOCIATION_NODE, BASENAME_NODE, BASENAMESTRING_NODE, COMMENT_NODE, DOCUMENT_NODE, GrpSep, GRPSEP, id, INSTANCEOF_NODE, MEMBER_NODE, MERGEMAP_NODE, NODE, NonType, NONTYPE, OCCURRENCE_NODE, PARAMETERS_NODE, PROCESSING_INSTRUCTION_NODE, RecSep, RECSEP, REFERENCE_NODE, RESOURCEDATA_NODE, RESOURCEREF_NODE, ROLESPEC_NODE, SCOPE_NODE, SUBJECTIDENTITY_NODE, SUBJECTINDICATORREF_NODE, TOPIC_NODE, TOPICMAP_NODE, TOPICREF_NODE, VARIANT_NODE, VARIANTNAME_NODE

Fields inherited from interface org.ceryle.util.Constants

Amp, AMP, Apos, APOS, APP_NAME, APP_VERSION_NAME, APP_VERSION_NUMBER, AT, BANG, BAR, BIT_dev, BIT_http, BIT_ignoreCom, BIT_merge, BIT_none, BIT_noPreload, BIT_simple, BIT_ui, BIT_unused1, BIT_unused2, BIT_unused3, BIT_validating, BIT_verbose, BIT_xcatalog, BIT_xlink, BIT_xmlnsAware, BIT_xsd, BROKB, BSlash, BSLASH, CERYLE_CREDITS_FILE, CERYLE_DATA_DIR, CERYLE_HIST_FILE, CERYLE_LICENSE_FILE, CERYLE_PREF_FILE, CERYLE_PROP, CERYLE_PROP_BASE, CERYLE_PROP_FILE, CERYLE_RSRC_DIR, CERYLE_THANKS_FILE, CFLEX, Colon, COLON, Comma, COMMA, CR, CRet, Dash, DASH, DEFAULT_DIRECTORY, DEVELOPER, DOLR, Dot, DOT, EIGHT, Ellip, EOF, EqQuot, EQUAL, Equals, False, FALSE, FileProt, Filesep, FileURL, Five, FIVE, FONTSIZES, Four, FOUR, FSchar, GCOL_PROP, GRAPH_PROP, GRAVE, GT, Hash, HASH, HOME_DIRECTORY, HOME_DIRECTORY_PATH, HOME_DIRECTORY_URL, HTML, HttpProt, HttpURL, INDENT, INDENT_0, INDENT_1, INDENT_10, INDENT_2, INDENT_3, INDENT_4, INDENT_5, INDENT_6, INDENT_7, INDENT_8, INDENT_9, INIT, LCURL, LCurly, LF, LFS, Localhost, LPAR, LParen, LS, LSBrkt, LSBrkt2, LSQB, LT, MT, NBSP, NEL, NINE, NL, NL20x, NLchar, No, Null, NULL, NULL_STATE, NumParams, One, ONE, Pathsep, Percent, PERO, PLUS, Prcnt, PS, QMark, QMARK, Quot, QUOT, RCURL, RCurly, RESOURCE_BUNDLE, RPAR, RParen, RSBrkt, RSBrkt2, RSQB, Semi, SEMI, SEVEN, SIX, Slash, SLASH, SP, SPACE, Stago, Star, STAR, Tab, TAB, Tee, Three, THREE, Tilde, TILDE, TM_PROP, True, TRUE, Two, TWO, Under, UNDER, URI, URL, VBar, WIKI_PROP, XNodePfx, XNodeURL, XtmExt, Yes, Zero, ZERO

Constructor Summary

XtmTopic(String id)
XtmTopic constructor with a required ID String id.

XtmTopic(String id, XtmReference xref)
XtmTopic constructor with a required ID String id and an XtmReference topic type xref (see setType(XtmReference)).

Method Summary

XtmBaseName	addBaseName(XtmBaseName baseName) Add an XtmBaseName name to this XtmTopic, returning the provided XtmBaseName.
void	addDescription(String id, String text) Add a textual description of this XtmTopic as an XtmOccurrence occurrence whose type is the PSI http://purl.org/ceryle/psi/ceryle/#Description, with a required ID value id.
void	addOccurrence(XtmOccurrence occurrence) Add an XtmOccurrence occurrence to this XtmTopic.
void	addSubjectIdentity(XtmReference xref) Add an XtmReference xref to the subject identity of this XtmTopic.
int	compareTo(Object o) Compares the ID of this XtmTopic with the provided Object for order.
Iterator	getBaseNames() Returns an Iterator over a collection of XtmBaseNames, or null if none have been defined.
XtmOccurrence	getDescription() Returns a textual description of this XtmTopic as an XtmOccurrence, null if this hasn't been set (the topic description is indicated by a PSI).
TreeSet	getHashes() Returns a TreeSet containing a collection of Strings, each representing a scoped base name string using XtmBaseName.getHash().
static String	getLabel(XtmTopic topic) Returns this XtmTopic's display name (label) from one of its base names.
String	getName() Returns a String containing the name of this XTM element type.
short	getNodeType() A short integer indicating what type of node this is.
int	getOccurrenceCount(boolean ignoreDescription) Returns the number of XtmOccurrences.
Iterator	getOccurrences() Returns an Iterator over a collection of XtmOccurrences, or null if none have been defined.
Iterator	getSubjectIdentity() Returns an Iterator over a collection of XtmReferences, or null if none have been defined.
XtmReference	getType() Returns the XtmReference indicating a type to which this XtmTopic belongs, or null if this has not been set.
Iterator	getTypes() Returns an iterator of XtmReference objects each indicating a type to which this XtmTopic belongs, or null if none have been set.
boolean	matchesClass(String uri) Returns true if this XtmTopic is an instance of the class (or "type") ascertained by a String match with the URI reference uri.
boolean	matchesClass(XtmReference xref) Returns true if this XtmTopic is an instance of the class (or "type") ascertained by (a) an identify match of any of the XtmNode's types with the provided XtmReference, or (b) a String match with the URI reference of the XtmReference xref.
boolean	removeBaseName(XtmBaseName baseName) Remove the XtmBaseName basename from this XtmTopic, returning true if the provided XtmBaseName was actually attached to this XtmTopic.
boolean	removeOccurrence(XtmOccurrence occurrence) Remove the XtmOccurrence occurrence from this XtmTopic, returning true if this occurred.
void	setDescription(String id, String text) Sets the textual description of this XtmTopic as an XtmOccurrence occurrence whose type is the PSI http://purl.org/ceryle/psi/ceryle/#Description, with a required ID value id.
void	setLabel(String label) Sets a label for this XtmTopic to the string label.
void	setType(XtmReference xref) Adds the type indicated by the XtmReference xref to this XtmTopic.
void	setType(XtmReference xref, boolean replace) Adds the type indicated by the XtmReference xref to this XtmTopic.
void	setTypes(Collection xrefs) Adds the types indicated by the XtmReferences xrefs to this XtmTopic.

Methods inherited from class org.ceryle.xtm.XtmNode

addPI, getID, getPI, getPIs, hasNext, next, remove, removePI, setID

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

types

protected TreeSet types

The TreeSet containing XtmReference objects indicating the type of this XtmTopic; this shows up in XML syntax as the content of an <instanceOf> element.

subjectIdentity

protected TreeSet subjectIdentity

The TreeSet containing XtmReference objects indicating the subjectIdentity of this XtmTopic.

baseNames

protected TreeSet baseNames

The TreeSet containing any scoped base names (as XtmBaseName objects) of this XtmTopic.

occurrences

protected TreeSet occurrences

The TreeSet containing XtmOccurrence objects indicating the occurrences of this XtmTopic.

description

protected XtmOccurrence description

The XtmOccurrence acting as a textual description of this XtmTopic.

Constructor Detail

XtmTopic

public XtmTopic(String id)
         throws XtmException

XtmTopic constructor with a required ID String id.

Throws:

XtmException

XtmTopic

public XtmTopic(String id,
                XtmReference xref)
         throws XtmException

XtmTopic constructor with a required ID String id and an XtmReference topic type xref (see setType(XtmReference)).

Throws:

XtmException

Method Detail

getName

public String getName()

Returns a String containing the name of this XTM element type.

Overrides:

getName in class XtmNode

getNodeType

public short getNodeType()

A short integer indicating what type of node this is. The named constants for this value are defined in the org.ceryle.XtmNode class.

Overrides:

getNodeType in class XtmNode

setType

public void setType(XtmReference xref)
             throws XtmException

Adds the type indicated by the XtmReference xref to this XtmTopic. A convenience method whose default is to replace any existing type, which exists so that all setType() methods in the package have the same, single parameter.

Throws:

XtmException

setType

public void setType(XtmReference xref,
                    boolean replace)
             throws XtmException

Adds the type indicated by the XtmReference xref to this XtmTopic. Each type shows up in XML syntax as the content of an <instanceOf> Element. If the boolean replace is true, the new type will replace any existing type(s).

Throws:

XtmException

setTypes

public void setTypes(Collection xrefs)
              throws XtmException

Adds the types indicated by the XtmReferences xrefs to this XtmTopic. Each type shows up in XML syntax as the content of an <instanceOf> Element. A topic may be an instance of more than one type.

Throws:

XtmException

getType

public XtmReference getType()

Returns the XtmReference indicating a type to which this XtmTopic belongs, or null if this has not been set. Each type shows up in XML syntax as the content of an <instanceOf> Element. If this XtmTopic might belong to more than one type, use getTypes().

getTypes

public Iterator getTypes()

Returns an iterator of XtmReference objects each indicating a type to which this XtmTopic belongs, or null if none have been set. Each type shows up in XML syntax as the content of an <instanceOf> Element.

matchesClass

public boolean matchesClass(XtmReference xref)

Returns true if this XtmTopic is an instance of the class (or "type") ascertained by (a) an identify match of any of the XtmNode's types with the provided XtmReference, or (b) a String match with the URI reference of the XtmReference xref. Note that topics may be instances of more than one class. This first tries identity matching with the XtmReference before calling the string match method.

matchesClass

public boolean matchesClass(String uri)

Returns true if this XtmTopic is an instance of the class (or "type") ascertained by a String match with the URI reference uri. Note that topics may be instances of more than one class.

getHashes

public TreeSet getHashes()

Returns a TreeSet containing a collection of Strings, each representing a scoped base name string using XtmBaseName.getHash().

Returns:

a TreeSet containing hashed scoped base name Strings.

getBaseNames

public Iterator getBaseNames()

Returns an Iterator over a collection of XtmBaseNames, or null if none have been defined.

Returns:

an Iterator over a collection of XtmBaseNames.

getLabel

public static String getLabel(XtmTopic topic)

Returns this XtmTopic's display name (label) from one of its base names. This returns the first (in Iterator order) of any base name's variant having a display name parameter (ie., a variant described as having a parameter ('type') matching the PSI for display). In the absence of any such base names, returns the first base name string. If there are no base names, returns the topic ID.

setLabel

public void setLabel(String label)
              throws XtmException

Sets a label for this XtmTopic to the string label.

NOTE: This first locates any existing base names having a "display" variant name, eliminates those base names, and sets this as the only one. This is necessarily ignoring scoping on the base name itself.

Throws:

XtmException

addBaseName

public XtmBaseName addBaseName(XtmBaseName baseName)

Add an XtmBaseName name to this XtmTopic, returning the provided XtmBaseName.

removeBaseName

public boolean removeBaseName(XtmBaseName baseName)

Remove the XtmBaseName basename from this XtmTopic, returning true if the provided XtmBaseName was actually attached to this XtmTopic.

getSubjectIdentity

public Iterator getSubjectIdentity()

Returns an Iterator over a collection of XtmReferences, or null if none have been defined.

Returns:

an Iterator over a collection of XtmReferences.

addSubjectIdentity

public void addSubjectIdentity(XtmReference xref)

Add an XtmReference xref to the subject identity of this XtmTopic.

addOccurrence

public void addOccurrence(XtmOccurrence occurrence)

Add an XtmOccurrence occurrence to this XtmTopic.

removeOccurrence

public boolean removeOccurrence(XtmOccurrence occurrence)

Remove the XtmOccurrence occurrence from this XtmTopic, returning true if this occurred.

getOccurrenceCount

public int getOccurrenceCount(boolean ignoreDescription)

Returns the number of XtmOccurrences. If ignoreDescription is true, ignores the presence of the description (which is a type of occurrence).

Returns:

an int indicating the number of XtmOccurrences.

getOccurrences

public Iterator getOccurrences()

Returns an Iterator over a collection of XtmOccurrences, or null if none have been defined.

Returns:

an Iterator over a collection of XtmOccurrences.

addDescription

public void addDescription(String id,
                           String text)
                    throws XtmException

Add a textual description of this XtmTopic as an XtmOccurrence occurrence whose type is the PSI http://purl.org/ceryle/psi/ceryle/#Description, with a required ID value id. This will overwrite the reference to any previous description (though its XtmOccurrence remains in the Vector of occurrences).

Throws:

XtmException

setDescription

public void setDescription(String id,
                           String text)
                    throws XtmException

Sets the textual description of this XtmTopic as an XtmOccurrence occurrence whose type is the PSI http://purl.org/ceryle/psi/ceryle/#Description, with a required ID value id. Unlike addDescription(), this replaces any previous XtmOccurrence used as a description. Any references to the previous description's resource ID may then be invalid. If either id or text is null, removes any existing description.

Throws:

XtmException

getDescription

public XtmOccurrence getDescription()

Returns a textual description of this XtmTopic as an XtmOccurrence, null if this hasn't been set (the topic description is indicated by a PSI). The String content of the XtmOccurrence is available from toString(). Note that if addDescription is used instead of setDescription(), the most recent addition will be returned, to the exclusion of any others.

compareTo

public int compareTo(Object o)

Compares the ID of this XtmTopic with the provided Object for order.

Specified by:

compareTo in interface Comparable