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.