org.tm4j.topicmap
Interface TopicMapObject

All Known Subinterfaces:

Association, BaseName, Member, NamedObject, Occurrence, ScopedObject, Topic, TopicMap, Variant, VariantName

All Known Implementing Classes:

UnifiedAssociation, UnifiedBaseName, UnifiedMember, UnifiedOccurrence, UnifiedScopedObject, UnifiedTopic, UnifiedTopicMap, UnifiedTopicMapObject, UnifiedVariant

public interface TopicMapObject

The generic base interface for topic map objects. All of the interfaces that represent constructs from the topic map are derived from this interface. For a more detailed discussion of the purpose of this interface and its capablities, see the section titled TopicMapObject in the TM4J Developer's Guide.

Note: TM4J provides a generic way for any client application to detect changes made in a topic map, which involves the use of properties and the java.beans.PropertyChangeListener interface. For more in-depth information about using properties in TM4J, and for a discussion of available properties, see the Property Change Listeners section in the TM4J Developer's Guide.

Author:

Kal Ahmed

Method Summary

void	addMultiValuePropertyChangeListener(MultiValuePropertyChangeListener listener) Adds a MultiValue Property Change Listener.
void	addMultiValuePropertyChangeListener(java.lang.String propertyName, MultiValuePropertyChangeListener listener) Adds a MultiValue Property Change Listener.
void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Adds a Property Change Listener.
void	addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Adds a Property Change Listener.
void	addSourceLocator(Locator loc) Adds a locator to the set of locators of the XML or other resources which contributed to this topic map object.
void	addVetoableChangeListener(java.beans.VetoableChangeListener listener)
void	destroy() Permanently removes this object from the topic map.
void	fireMultiValuePropertyChange(MultiValuePropertyChangeEvent propertyChange) Notifies the MultiValue Property Change Listeners of a property change.
void	fireMultiValuePropertyChange(java.lang.String propertyName, int operation, java.lang.Object operand) Notifies the MultiValue Property Change Listeners of a property change to this object
void	firePropertyChange(java.beans.PropertyChangeEvent propertyChange) Notifies the Property Change Listeners of a property change.
void	firePropertyChange(java.lang.String propertyName, java.lang.Object oldVal, java.lang.Object newVal) Notifies a Property Change Listener of a property change.
void	fireVetoableChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue)
java.lang.String	getID() Returns the object ID of the TopicMapObject.
Locator	getResourceLocator() Deprecated. From 0.9.0 use getSourceLocators()
java.util.Set	getSourceLocators() Returns the Locators of the XML or other resources which contributed to this topic map object.
TopicMap	getTopicMap() Returns a handle to the topic map which this object is part of.
void	removeMultiValuePropertyChangeListener(MultiValuePropertyChangeListener listener) Removes a MultiValue Property Change Listener.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Removes a Property Change Listener.
void	removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Removes a Property Change listener for a specific property
void	removeSourceLocator(Locator loc) Removes a locator from the set of locators of the XML or other resources which contributed to this topic map object.
void	removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
void	setID(java.lang.String id) Sets the object ID of the TopicMapObject.
void	setResourceLocator(Locator loc) Deprecated. From 0.9.0 use addSourceLocator(Locator)

Method Detail

setID

public void setID(java.lang.String id)
           throws DuplicateObjectIDException,
                  DuplicateResourceLocatorException

Sets the object ID of the TopicMapObject. The object ID is an internal identifier assigned by the application to a topic map object. ID values must be unique for each object in the same topic map. Implementations are free to assign ID values in any way they see fit.

Parameters:

id - the new internal object ID.

Throws:

DuplicateObjectIDException - If an attempt is made to set the object's ID to a value already assigned to an object in the same TopicMap.

DuplicateResourceLocatorException - If the resource locator of the object being updated clashes with the resource locator of an existing object.

getID

public java.lang.String getID()

Returns the object ID of the TopicMapObject. Note that implementations are free to assign ID values in any way they see fit. To get the Locator of the XTM element which is represented by this object, use getResourceLocator().

Returns:

the internal object ID.

See Also:

setID(java.lang.String)

getResourceLocator

public Locator getResourceLocator()

Deprecated. From 0.9.0 use getSourceLocators()

Returns the Locator of the XML or other resource which caused the creation of this topic map object.

Returns:

The creating Locator.

setResourceLocator

public void setResourceLocator(Locator loc)
                        throws DuplicateResourceLocatorException

Deprecated. From 0.9.0 use addSourceLocator(Locator)

Sets the Locator of the XML or other resource which caused the creation of this topic map object. Typically, this will be the Locator of an XTM element.

Parameters:

loc - the creating Locator.

Throws:

DuplicateResourceLocatorException - if loc is already assigned as a resource locator to some other topic map object.

getSourceLocators

public java.util.Set getSourceLocators()

Returns the Locators of the XML or other resources which contributed to this topic map object.

NOTE: under the dynamic merging model, calling getResourceLocators() on a Topic object will return the resourceLocator of the Topic itself, plust that of all Topics which it is merged with.

Returns:

an unmodifiable Set of Locator objects.

addSourceLocator

public void addSourceLocator(Locator loc)
                      throws DuplicateResourceLocatorException

Adds a locator to the set of locators of the XML or other resources which contributed to this topic map object.

Parameters:

loc - the locator of the contributing resource

Throws:

DuplicateResourceLocatorException - if loc is already assigned as a resource locator to some other topic map object in the same TopicMap.

removeSourceLocator

public void removeSourceLocator(Locator loc)

Removes a locator from the set of locators of the XML or other resources which contributed to this topic map object.

Parameters:

loc - the locator to be removed

getTopicMap

public TopicMap getTopicMap()

Returns a handle to the topic map which this object is part of.

Returns:

This object's parent topic map.

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String propertyName,
                                      java.beans.PropertyChangeListener listener)

Adds a Property Change Listener. The listener is registered for only one property.

Parameters:

propertyName - The property whose changes the listener monitors.

listener - The new listener to be registered. It only listens for changes in the property specified by propertyName.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Adds a Property Change Listener. The listener is registered for all properties.

Parameters:

listener - The new listener to be registered. It listens for changes in all available properties.

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Removes a Property Change Listener.

Parameters:

listener - The listener to be removed.

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propertyName,
                                         java.beans.PropertyChangeListener listener)

Removes a Property Change listener for a specific property

Parameters:

propertyName - The property that the listener should be removed from

listener - The listener to be removed

firePropertyChange

public void firePropertyChange(java.lang.String propertyName,
                               java.lang.Object oldVal,
                               java.lang.Object newVal)

Notifies a Property Change Listener of a property change. Note that if oldVal equals newVal, no property change event is actually fired.

Parameters:

propertyName - The property for which a property change is to be fired. The Property Change Listener responsible for handling changes to this particular property is selected automatically.

oldVal - The property's original value.

newVal - The property's new value.

firePropertyChange

public void firePropertyChange(java.beans.PropertyChangeEvent propertyChange)

Notifies the Property Change Listeners of a property change.

Parameters:

propertyChange - The PropertyChangeEvent to be fired. The Property Change Listener is responsible for handling changes to this particular property is selected automatically.

addMultiValuePropertyChangeListener

public void addMultiValuePropertyChangeListener(java.lang.String propertyName,
                                                MultiValuePropertyChangeListener listener)

Adds a MultiValue Property Change Listener. The listener is registered for only one property.

Parameters:

propertyName - The property whose changes the listener monitors.

listener - The new listener to be registered. It only listens for changes in the property specified by propertyName.

addMultiValuePropertyChangeListener

public void addMultiValuePropertyChangeListener(MultiValuePropertyChangeListener listener)

Adds a MultiValue Property Change Listener. The listener is registered for all properties.

Parameters:

listener - The new listener to be registered. It listens for changes in all available properties.

removeMultiValuePropertyChangeListener

public void removeMultiValuePropertyChangeListener(MultiValuePropertyChangeListener listener)

Removes a MultiValue Property Change Listener.

Parameters:

listener - The listener to be removed.

fireMultiValuePropertyChange

public void fireMultiValuePropertyChange(java.lang.String propertyName,
                                         int operation,
                                         java.lang.Object operand)

Notifies the MultiValue Property Change Listeners of a property change to this object

Parameters:

propertyName - The name of the property modified.

operation - The type of modification to the property. Allowed values are specified in the class MultiValuePropertyChangeEvent

operand - The object or Collection of objects which were involved in the modification. For OP_CLEAR events, no operand is required. For OP_ADD_SINGLE or OP_REMOVE_SINGLE events, the operand must be the object added or removed. For OP_ADD_SET and OP_REMOVE_SET events, the operand must be a Collection of all the objects added or removed. For OP_SET events, the operand must be a collection of the new values assigned to the property.

fireMultiValuePropertyChange

public void fireMultiValuePropertyChange(MultiValuePropertyChangeEvent propertyChange)

Notifies the MultiValue Property Change Listeners of a property change.

Parameters:

propertyChange - The MultiValuePropertyChangeEvent to be fired. The MultiValue Property Change Listener is responsible for handling changes to this particular property is selected automatically.

addVetoableChangeListener

public void addVetoableChangeListener(java.beans.VetoableChangeListener listener)

removeVetoableChangeListener

public void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)

fireVetoableChange

public void fireVetoableChange(java.lang.String propertyName,
                               java.lang.Object oldValue,
                               java.lang.Object newValue)
                        throws java.beans.PropertyVetoException

Throws:

java.beans.PropertyVetoException

destroy

public void destroy()
             throws IntegrityViolationException,
                    java.beans.PropertyVetoException

Permanently removes this object from the topic map. Depending upon the backend implementation, this method may also free up the memory or other storage space used by the object. An object may only be destroyed after all references to it from other objects have been removed. If the object detects that there is an existing reference still held to it, then an IntegrityViolationException is thrown

Throws:

IntegrityViolationException - If this object is still referenced from one or more other topic map objects.

java.beans.PropertyVetoException - if the removal of the object (or one of its children) from the topic map was vetoed by a listener. Depending upon the back-end implementation used, the object or its children may or may not have been modified.