dd.sim
Class SimObject

java.lang.Object
  dd.sim.SimObject

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

Briefing, ConfigParameter, CostTable, GameRoot, HexCoordinate, Layer, Map, MapCell, Player, Proposal, Scenario

public abstract class SimObject

extends java.lang.Object

implements java.io.Serializable

Base class for simulation objects. SimObject is the class from which all of the other objects in the simulation engine are built. SimObject has some basic behavior and protocol that is useful for all simulation objects, such as logging, simulation execution support, XML reading and writing, and so on.

Every simulation object has an attribute table that makes it possible to associate arbitrary name/value pairs with that object. This makes it possible to add attribute values dynamically and at run time. Attributes by default are float values but can be used to store arbitrary values. Note that simulation attributes are different than layer-specific attributes. Attributes associated directly with a SimObject do not exist within a layer, and therefore should not be used in conjunction with the attribute retrieval calls that use Layer information.

There are four levels of logging provided by this class, in increasing order of severity:

• debug - Debugging messages. These may be very detailed and turned off for production code
• log - Logging messages. These are moderate-priority messages that indicate normal action.
• warning - Warning messages. These are error conditions, but errors which are recoverable (such as caught exceptions).
• error - Major errors. These are unrecoverable error conditions. The program may terminate after logging these errors.

Simulation objects use the JavaBeans property change notification scheme to provide event-based notification when a simulation object changes. This should simplify the process of creating computations that are dependent on an attribute value changing. Setting attribute value will fire a PropertyChangeEvent, and subclasses of SimObject automatically inherit behavior to add and remove event listeners. However, if a non-attribute property changes, it is the responsibility of code to call firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object) where appropriate.

Author:

Eric Scharff

See Also:

Serialized Form

Field Summary

protected java.util.HashMap

attributes stores the name/value attribute table

Constructor Summary

SimObject()
Generic constructor for simulation objects.

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Adds the listener to the list of objects to be notified when this simulation object changes.
void	addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener) Adds a listener to be notified when a specific property changes.
void	debug(java.lang.String debugMessage) Logs a debugging message.
SimObject	duplicate() Makes a new SimObject identical to the current SimObject by serializing it to XML and reading it back in.
void	error(java.lang.String errorMessage) Logs an error message.
void	fatal(java.lang.String errorMessage) Logs an fatal error message.
static java.util.List	filter(java.util.Collection simObjects, java.lang.String name, double value) Queries a collection of SimObjects for a property with the specified value.
static java.util.List	filter(java.util.Collection simObjects, java.lang.String name, java.lang.Object value) Queries a collection of SimObjects for a property with the specified value.
void	firePropertyChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue) Informs listeners that a property has changed.
float	getAttribute(java.lang.String attributeName) Gets the value of a named attribute.
float	getAttribute(java.lang.String attributeName, float defaultValue) Gets the value of a named attribute.
java.util.HashMap	getAttributes() Returns the attributes associated with this object.
java.lang.Object	getGlobalAttribute(java.lang.String attributeName) Gets the value of a named attribute for this simulation.
java.lang.Object	getObjectAttribute(java.lang.String attributeName) Gets the value of a named attribute.
java.lang.Object	getObjectAttribute(java.lang.String attributeName, java.lang.Object defaultValue) Gets the value of a named attribute.
void	incrementAttribute(java.lang.String attributeName) Increments the value of an attribute by one.
void	incrementAttribute(java.lang.String attributeName, float delta) Increments the value of the attribute by the amount specified.
boolean	isSet(java.lang.String attributeName) Returns 'true' if the named attribute has a non-zero floating-point value.
void	log(java.lang.String logMessage) Logs a logging message.
protected static void	out(java.lang.String message)
static SimObject	readFromXML(java.io.Reader reader) Creates a new SimObject from an XML representation.
static SimObject	readFromXML(java.lang.String fileName) Creates a new SimObject from an XML representation.
void	removeAttribute(java.lang.String attributeName) Removes a named attribute.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Removes the listener from the notification list.
void	setAttribute(java.lang.String attributeName, boolean value) Sets the value of a named attribute.
void	setAttribute(java.lang.String attributeName, float value) Sets the value of a named attribute.
void	setAttribute(java.lang.String attributeName, java.lang.Object value) Sets the value of a named attribute.
void	setAttributes(java.util.HashMap attributes) Sets the attributes associated with this object.
void	setGlobalAttribute(java.lang.String attributeName, java.lang.Object value) Sets the value of a named attribute for this simuation.
void	warning(java.lang.String warningMessage) Logs a warning message.
java.lang.String	writeText()
java.lang.String	writeXML() Writes a representation of this SimObject as XML to a String.
void	writeXML(java.lang.String fileName) Writes a representation of this SimObject as XML.

Methods inherited from class java.lang.Object

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

Field Detail

attributes

protected java.util.HashMap attributes

stores the name/value attribute table

Constructor Detail

SimObject

public SimObject()

Generic constructor for simulation objects. This method should always be called because it initializes the general-purpose support needed for every simulation object.

Method Detail

filter

public static java.util.List filter(java.util.Collection simObjects,
                                    java.lang.String name,
                                    double value)

Queries a collection of SimObjects for a property with the specified value. This function serves as a filter over a collection of SimObjects. It returns a new collection where each of the SimObjects have a property whose value is the value provided. This method will fail if the collection does not entirely contain SimObjects.

Parameters:

simObjects - a Collection of SimObjects to query

name - the property name to query

value - the value the property shold have

Returns:

a new collection of SimObjects where each SimObjects have a property equal to value.

filter

public static java.util.List filter(java.util.Collection simObjects,
                                    java.lang.String name,
                                    java.lang.Object value)

Queries a collection of SimObjects for a property with the specified value. This function serves as a filter over a collection of SimObjects. It returns a new collection where each of the SimObjects have a property whose value is the value provided. This method will fail if the collection does not entirely contain SimObjects.

Parameters:

simObjects - a Collection of SimObjects to query

name - the property name to query

value - the value the property shold have

Returns:

a new collection of SimObjects where each SimObjects have a property equal to value.

out

protected static void out(java.lang.String message)

getAttributes

public java.util.HashMap getAttributes()

Returns the attributes associated with this object. The attributes are returned as a HashMap whose keys are strings (the name of the attribute) and whose values are Objects (often Float objects).

Returns:

a mapping from attribute names to values

setAttributes

public void setAttributes(java.util.HashMap attributes)

Sets the attributes associated with this object. The attributes are stored in a HashMap where keys are strings (the name of the attribute) and values are Objects. Note that it is rarely necessary to reset the attribute mapping table, but this method is used when new SimObjects are read in from disk.

Parameters:

attributes - new name/value attribute table

getGlobalAttribute

public java.lang.Object getGlobalAttribute(java.lang.String attributeName)

Gets the value of a named attribute for this simulation. A global attribute is shared by all of the SimObjects in the currently running simulation. Note that the current implementation implies one simulation per java virtual machine, but eventually this method will ensure that a SimObject will automatically be associated with the simulation in which it was created. It is important to ALWAYS query global attributes through this method call, and not store copies of global attributes locally, because global attributes may change without warning.

Parameters:

attributeName - name of the global attribute to query

Returns:

the value of the attribute, null if the attribute does not exist.

setGlobalAttribute

public void setGlobalAttribute(java.lang.String attributeName,
                               java.lang.Object value)

Sets the value of a named attribute for this simuation. A global attriubte is shared by all of the SimObjects in a currently running simulation. Note that setting a global attribute does NOT fire any property change events.

Parameters:

attributeName - name of the global attribute to set

value - value to which the attribute should be set

getAttribute

public float getAttribute(java.lang.String attributeName)

Gets the value of a named attribute. This is a convenience method for getObjectAttribute. It returns the value of the attribute specified. Note that attributes (floating point values) and Object attributes share the same name space, so this method will fail if it requests a non-numeric attribute.

Parameters:

attributeName - name of the attribute to query

Returns:

the value of the attribute

Throws:

java.util.NoSuchElementException - if there is no attribute with the specified name

getAttribute

public float getAttribute(java.lang.String attributeName,
                          float defaultValue)

Gets the value of a named attribute. This is a convenience method for getObjectAttribute. It returns the value of the attribute specified. If that attribute does not exist, then the default value is returned. Note that attributes (floating point values) and Object attributes share the same name space, so this method will fail if it requests a non-numeric attribute.

Parameters:

attributeName - name of the attribute to query

defaultValue - value to return if the attribute does not exist

Returns:

the value of the attribute, or defaultValue if the attribute does not exist.

getObjectAttribute

public java.lang.Object getObjectAttribute(java.lang.String attributeName)

Gets the value of a named attribute. Note that attributes (floating point values) and Object attributes share the same name space.

Parameters:

attributeName - name of the attribute to query

Returns:

the value of the attribute, null if the attribute does not exist

getObjectAttribute

public java.lang.Object getObjectAttribute(java.lang.String attributeName,
                                           java.lang.Object defaultValue)

Gets the value of a named attribute. Note that attributes (floating point values) and Object attributes share the same name space.

Parameters:

attributeName - name of the attribute to query

defaultValue - value to return if the attribute does not exist

Returns:

the value of the attribute, or defaultValue if the attribute does not exist.

setAttribute

public void setAttribute(java.lang.String attributeName,
                         float value)

Sets the value of a named attribute. This creates a new attribute (or overwrites an existing attribute) associated with the name specified. An appropriate property change event is fired when the attribute is set.

Parameters:

attributeName - name of the attribute to set

value - value to which the attribute should be set

See Also:

PropertyChangeEvent

setAttribute

public void setAttribute(java.lang.String attributeName,
                         boolean value)

Sets the value of a named attribute. This creates a new attribute (or overwrites an existing attribute) associated with the name specified. An appropriate property change event is fired when the attribute is set.

Parameters:

attributeName - name of the attribute to set

value - value to which the attribute should be set

See Also:

PropertyChangeEvent

setAttribute

public void setAttribute(java.lang.String attributeName,
                         java.lang.Object value)

Sets the value of a named attribute. This creates a new attribute (or overwrites an existing attribute) associated with the name specified. An appropriate property change event is fired when the attribute is set.

Parameters:

attributeName - name of the attribute to set

value - value to which the attribute should be set

See Also:

PropertyChangeEvent

removeAttribute

public void removeAttribute(java.lang.String attributeName)

Removes a named attribute. The attribute should exist if it is going to be removed. No property change is fired.

Parameters:

attributeName - name of the attribute to remove

isSet

public boolean isSet(java.lang.String attributeName)

Returns 'true' if the named attribute has a non-zero floating-point value. Not sure what it'll do if called on an ObjectAttribute, but probably it won't be what you want. Kind of kludgy, but will work until we have better support for storing different types of attributes.

incrementAttribute

public void incrementAttribute(java.lang.String attributeName)

Increments the value of an attribute by one. Calls incrementAttribute(attributeName, 1), so if the attribute is unset, it will be set after the call.

Parameters:

attributeName - name of the attribute to increment

incrementAttribute

public void incrementAttribute(java.lang.String attributeName,
                               float delta)

Increments the value of the attribute by the amount specified. The amount need not be an "increment." This method merely adds delta to the current value of the attribute. If the attribute is unset, it is set to the value delta.

Parameters:

attributeName - name of the attribute to set

delta - amount (positive or negative) to add to the attribute)

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Adds the listener to the list of objects to be notified when this simulation object changes. This simulation object is the source of a property change event when attributes and other values of the simulation object change. The listener will be notified whenever any property of this simulation object changes.

Parameters:

listener - object to notify when properties change

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Removes the listener from the notification list. This removes a registered listener from the list of object to be informed when this simulation object changes.

Parameters:

listener - object to no longer receive notifications

addPropertyChangeListener

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

Adds a listener to be notified when a specific property changes. This is a more refined method than requesting notification of all property changes. The listener is called only when the requested property changes. By convention, property names are the same as attribute names.

Parameters:

propertyName - name of the property to monitor

listener - object to notify when the property changes

firePropertyChange

public void firePropertyChange(java.lang.String propertyName,
                               java.lang.Object oldValue,
                               java.lang.Object newValue)

Informs listeners that a property has changed. This method is currently called immediately after the specified property is set (in case a listener wishes to revert to the earlier value.) This method is called automatically when an attribute value is set. If a subclass has additional properties that require notification, they should call this method immediately after setting the property in order to inform any listeners. By convention, property names are the names of instance variables or attributes.

Parameters:

propertyName - name of the property that is changing

oldValue - former value of the property

newValue - new (probably current) value of the property

debug

public void debug(java.lang.String debugMessage)

Logs a debugging message. This is the lowest priority logging message and is used as an aid to debugging. Using SimObject logging mechanisms is preferable to other techniques because they provide built in support for filtering different error classes. The SimObject itself is included as part of the logged message.

Parameters:

debugMessage - descriptive text for the log

log

public void log(java.lang.String logMessage)

Logs a logging message. This is a moderate priority message that is used to log normal behavior. Using SimObject logging mechanisms is preferable to other techniques because they provide built in support for filtering different error classes. The SimObject itself is included as part of the logged message.

Parameters:

logMessage - descriptive text for the log

warning

public void warning(java.lang.String warningMessage)

Logs a warning message. this is a high priority message that indicates that an unexpected condition (error) occurred, but that the system is attempting to recover from the error. An example would be a caught exception. Using SimObject logging mechanisms is preferable to other techniques because they provide built in support for filtering different error messages. The SimObject itself is included as part of the logged message.

Parameters:

warningMessage - descriptive text for the log

error

public void error(java.lang.String errorMessage)

Logs an error message. This is the highest priority message and indicates that an unrecoverable error has occurred. Execution may terminate shortly after a call to this method. Using SimObject logging mechanisms is preferable to other techniques because they provide built int support for filtering different error messages. The SimObject itself is included as part of the logged message.

Parameters:

errorMessage - descriptive text for the log

fatal

public void fatal(java.lang.String errorMessage)

Logs an fatal error message. This is the highest priority message and indicates that an unrecoverable error has occurred. Execution will terminate shortly after a call to this method. Using SimObject logging mechanisms is preferable to other techniques because they provide built int support for filtering different error messages. The SimObject itself is included as part of the logged message.

Parameters:

errorMessage - descriptive text for the log

readFromXML

public static SimObject readFromXML(java.lang.String fileName)

Creates a new SimObject from an XML representation. This factory method accepts the name of an XML file and returns a SimObject as read in from that XML file.

Parameters:

fileName - name of the XML file to parse

Returns:

the parsed SimObject, null if an error occurs

readFromXML

public static SimObject readFromXML(java.io.Reader reader)

Creates a new SimObject from an XML representation. This factory method accepts the name of an input reader and returns a SimObject as red in from that reader. Note that because of limitations in the underlying XML parser, the Reader must return end-of-input at the end of the XML input.

Parameters:

reader - character stream from which XML will be read

Returns:

the parsed SimObject, null if an error occurs

writeXML

public void writeXML(java.lang.String fileName)

Writes a representation of this SimObject as XML. Subclasses can override this method to provide more readable XML output, but most of the work is now handled by the SimXMLWriter class. The description returned by this method should be a complete enough description so that an object can be read in at a future time from this representation.

Parameters:

fileName - file upon which the object should be written

writeXML

public java.lang.String writeXML()

Writes a representation of this SimObject as XML to a String. Subclasses can override this method to provide more readable XML output, but most of the work is now handled by the SimXMLWriter class. The description returned by this method should be a complete enough description so that an object can be read in at a future time from this representation.

Returns:

the XML representation of this object.

writeText

public java.lang.String writeText()

duplicate

public SimObject duplicate()

Makes a new SimObject identical to the current SimObject by serializing it to XML and reading it back in. This guarantees that the two SimObjects are identical, but refer to different objects.

Returns:

a new SimObject identical to this one.