com.jstatcom.model
Class Symbol

java.lang.Object
  com.jstatcom.model.Symbol

All Implemented Interfaces:

JSCDataListener, java.lang.Comparable

public class Symbol
extends java.lang.Object
implements JSCDataListener, java.lang.Comparable

The Symbol class represents a variable with a certain type and name. After initialization it is only possible to store references to JSCData objects of type. Two symbols are considered equal if their names are equal, independent of the case.

SymbolListener can savely use Symbol objects to obtain notification about changes in the underlying JSCData within the Swing EventDispatchingThread. This is not ensured if they register themselves as listeners directly to JSCData objects.

This class is thread-save. All access to mutable data is synchronized.

Subclasses might add new accessor methods for newly declared JSCData types. The main functionality of a symbol should not be changed, therefore all methods are declared final.

Author:

Markus Kraetzig

Field Summary

java.lang.String	name Identifier of this symbol.
java.lang.String	NAME Upper case identifier of this symbol.
static javolution.xml.XmlFormat<Symbol>	Symbol_XML XML format field for (de)serialization.
JSCTypes	type Type of this symbol.

Constructor Summary

Symbol(JSCData data)
Creates a Symbol with data.getName a reference to data.

Symbol(JSCTypeDef def)
Creates a Symbol with an empty object of the given type.

Symbol(java.lang.String name, JSCData data)
Creates a Symbol with name and a reference to data.

Method Summary

void	addSymbolListener(SymbolListener evtListener) Convenience method that adds a listener that is notified when changes of type VALUE_CHANGED occur in this object.
void	addSymbolListener(SymbolListener evtListener, SymbolEventTypes evtType) Adds a listener that is notified when changes of type evtType occur in this object.
void	clear() Clears the underlying JSCData object.
int	compareTo(java.lang.Object obj) Compares two Symbol objects by their uppercase names.
static void	copySymbol(Symbol source, Symbol target) Moves data and listeners from one symbol to the other.
java.lang.String	display() Displays the underlying JSCData object.
boolean	equals(java.lang.Object obj) Returns true if obj is a Symbol and has the same name as this, without regarding the case.
java.lang.String	getDescription() Gets the description of this symbol.
JSCData	getJSCData() Gets a reference to the underlying data object.
JSCDate	getJSCDate() Gets the data as an instance of JSCDate.
JSCDRange	getJSCDRange() Gets the data as an instance of JSCDRange.
JSCInt	getJSCInt() Gets the data as an instance of JSCInt.
JSCNArray	getJSCNArray() Gets the data as an instance of JSCNArray.
JSCNumber	getJSCNumber() Gets the data as an instance of JSCNumber.
JSCSArray	getJSCSArray() Gets the data as an instance of JSCSArray.
JSCString	getJSCString() Gets the data as an instance of JSCString.
JSCVoid	getJSCVoid() Gets the data as an instance of JSCVoid.
java.util.List	getListenersForType(SymbolEventTypes evtType) Gets a list with all registered listeners for evtType.
int	hashCode() Generates a hash code for the receiver.
boolean	isEmpty() Gets whether the underlying JSCData object is empty.
void	removeAllSymbolListeners() Removes all SymbolListener objects from this symbol.
void	removeSymbolListener(SymbolListener evtListener) Removes evtListener from all listener lists.
void	setDescription(java.lang.String newDescription) Sets the description for this symbol.
void	setJSCData(JSCData newData) Sets the reference of this symbol to a new data object.
java.lang.String	toString() Returns a string that represents the value of this object.
void	valueChanged(JSCDataEvent evt) Transforms evt to the respective SymbolEvent and dispatches it to the SymbolListeners.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

name

public final java.lang.String name

Identifier of this symbol.

NAME

public final java.lang.String NAME

Upper case identifier of this symbol.

type

public final JSCTypes type

Type of this symbol.

Symbol_XML

public static final javolution.xml.XmlFormat<Symbol> Symbol_XML

XML format field for (de)serialization.

Constructor Detail

Symbol

public Symbol(JSCData data)

Creates a Symbol with data.getName a reference to data. The type of this Symbol is set to data.type.

Parameters:

data - the JSCData object for this Symbol

Throws:

java.lang.IllegalArgumentException - if (data == null)

Symbol

public Symbol(java.lang.String name,
              JSCData data)

Creates a Symbol with name and a reference to data. The type of this Symbol is set to data.type.

Parameters:

name - the identifier of the symbol, must satisfy conventions for variable names defined in JSCConstants

data - the JSCData object for this Symbol

Throws:

java.lang.IllegalArgumentException - if (name == null || data == null) or if name is not valid

See Also:

JSCConstants.isValidName(java.lang.String)

Symbol

public Symbol(JSCTypeDef def)

Creates a Symbol with an empty object of the given type.

Parameters:

def - the type definition

Throws:

java.lang.NullPointerException - if (def == null)

See Also:

JSCConstants.isValidName(java.lang.String)

Method Detail

addSymbolListener

public final void addSymbolListener(SymbolListener evtListener)

Convenience method that adds a listener that is notified when changes of type VALUE_CHANGED occur in this object. All other events that are fired by this object are not dispatched to evtListener. This is most common for SymbolListeners.

Parameters:

evtListener - the listener object that gets notified when an event of type evtType gets fired

Throws:

java.lang.IllegalArgumentException - if (evtListener == null)

addSymbolListener

public final void addSymbolListener(SymbolListener evtListener,
                                    SymbolEventTypes evtType)

Adds a listener that is notified when changes of type evtType occur in this object. All other events that are fired by this object are not dispatched to evtListener.

Parameters:

evtListener - the listener object that gets notified when an event of type evtType gets fired

evtType - the type of event that evtListener wants to listen to

Throws:

java.lang.IllegalArgumentException - if (evtListener == null || evtType == null)

clear

public final void clear()

Clears the underlying JSCData object. This fires a EMPTY_STATE and VAL_CHANGED event, if the data was not empty before.

display

public final java.lang.String display()

Displays the underlying JSCData object.

compareTo

public final int compareTo(java.lang.Object obj)

Compares two Symbol objects by their uppercase names.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

obj - the symbol to be compared, must another Symbol

Returns:

0 if equal, < 0 if this smaller, > 0 if this is greater

Throws:

java.lang.IllegalArgumentException - if (!(obj instanceof Symbol))

equals

public final boolean equals(java.lang.Object obj)

Returns true if obj is a Symbol and has the same name as this, without regarding the case. This is to ensure that there is only one Symbol of a given name in a SymbolTable.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object to compare with

Returns:

true if these object are equal, false otherwise.

getDescription

public final java.lang.String getDescription()

Gets the description of this symbol.

Returns:

the descriptive string or "" if no description has been set

getJSCData

public final JSCData getJSCData()

Gets a reference to the underlying data object.

Usage note:
The returned data is a reference to the underlying JSCData object only until a new data object has been set to this symbol. It should be used read only. Changes that should not affect this symbol must be made on a copy of the returned object.

Returns:

JSCData object of type type

getJSCDate

public final JSCDate getJSCDate()

Gets the data as an instance of JSCDate.

Usage note:
The returned data is a reference to the underlying JSCData object only until a new data object has been set to this symbol. It should be used read only. Changes that should not affect this symbol must be made on a copy of the returned object.

Returns:

a JSCDate

Throws:

java.lang.RuntimeException - if (type != JSCTypes.DATE)

getJSCDRange

public final JSCDRange getJSCDRange()

Gets the data as an instance of JSCDRange.

Usage note:
The returned data is a reference to the underlying JSCData object only until a new data object has been set to this symbol. It should be used read only. Changes that should not affect this symbol must be made on a copy of the returned object.

Returns:

a JSCDRange

Throws:

java.lang.RuntimeException - if (type != JSCTypes.DRANGE)

getJSCNArray

public final JSCNArray getJSCNArray()

Gets the data as an instance of JSCNArray. If the data is an instance of JSCNumber or JSCInt a new 1x1 JSCNArray with the single element is returned or an empty JSCNArray.

Usage note:
The returned data is a reference to the underlying JSCData object only until a new data object has been set to this symbol. It should be used read only. Changes that should not affect this symbol must be made on a copy of the returned object.

Returns:

a JSCNArray

Throws:

java.lang.RuntimeException - if (type != JSCTypes.NARRAY && type != JSCTypes.INT && type != JSCTypes.NUMBER)

getJSCNumber

public final JSCNumber getJSCNumber()

Gets the data as an instance of JSCNumber. If the data is of type INT a new JSCNumber with the element is returned.

Usage note:
The returned data is a reference to the underlying JSCData object only until a new data object has been set to this symbol. It should be used read only. Changes that should not affect this symbol must be made on a copy of the returned object.

Returns:

a JSCNumber

Throws:

java.lang.RuntimeException - if (type != JSCTypes.NUMBER && type != JSCTypes.INT)

getJSCInt

public final JSCInt getJSCInt()

Gets the data as an instance of JSCInt.

Usage note:
The returned data is a reference to the underlying JSCData object only until a new data object has been set to this symbol. It should be used read only. Changes that should not affect this symbol must be made on a copy of the returned object.

Returns:

a JSCInt

Throws:

java.lang.RuntimeException - if (type != JSCTypes.INT)

getJSCSArray

public final JSCSArray getJSCSArray()

Gets the data as an instance of JSCSArray. If the data is an instance of JSCString, a new 1x1 JSCSArray with the single element is returned or an empty JSCSArray.

Usage note:
The returned data is a reference to the underlying JSCData object only until a new data object has been set to this symbol. It should be used read only. Changes that should not affect this symbol must be made on a copy of the returned object.

Returns:

a JSCSArray

Throws:

java.lang.RuntimeException - if (type != JSCTypes.SARRAY && type != JSCTypes.STRING)

getJSCString

public final JSCString getJSCString()

Gets the data as an instance of JSCString. If the data is an instance of JSCSArray, a JSCString with the 0:0 element is returned or an empty JSCString.

Usage note:
The returned data is a reference to the underlying JSCData object only until a new data object has been set to this symbol. It should be used read only. Changes that should not affect this symbol must be made on a copy of the returned object.

Returns:

a JSCString

Throws:

java.lang.RuntimeException - if (type != JSCTypes.STRING && type != JSCTypes.SARRAY)

getJSCVoid

public final JSCVoid getJSCVoid()

Gets the data as an instance of JSCVoid.

Usage note:
The returned data is a reference to the underlying JSCData object only until a new data object has been set to this symbol. It should be used read only. Changes that should not affect this symbol must be made on a copy of the returned object.

Returns:

a JSCVoid

Throws:

java.lang.RuntimeException - if (type != JSCTypes.VOID)

hashCode

public final int hashCode()

Generates a hash code for the receiver. This method is supported primarily for hash tables, such as those provided in java.util.

Overrides:

hashCode in class java.lang.Object

Returns:

an integer hash code for the receiver

isEmpty

public final boolean isEmpty()

Gets whether the underlying JSCData object is empty.

Returns:

true if empty, false otherwise

removeAllSymbolListeners

public void removeAllSymbolListeners()

Removes all SymbolListener objects from this symbol.

removeSymbolListener

public final void removeSymbolListener(SymbolListener evtListener)

Removes evtListener from all listener lists.

Parameters:

evtListener - the listener to remove

getListenersForType

public java.util.List getListenersForType(SymbolEventTypes evtType)

Gets a list with all registered listeners for evtType.

Parameters:

evtType - the event type

Returns:

a copy of the respective list or an initialized list instance with size == 0 if no listeners are registered for evtType

setDescription

public final void setDescription(java.lang.String newDescription)

Sets the description for this symbol.

Parameters:

newDescription - a descriptive string

Throws:

java.lang.IllegalArgumentException - if description contains / * or * /

setJSCData

public final void setJSCData(JSCData newData)

Sets the reference of this symbol to a new data object. SymbolListener objects are notified via the events:

• SymbolEventTypes.REF_CHANGED
• SymbolEventTypes.VAL_CHANGED only if (!newData.isEqual(oldData))

The REF_CHANGED event is necessary for tables that listen to changes in a certain Symbol. They need to change their model data to newData, otherwise they would continue to listen to changes in the old data object.

This symbol is removed from the listener list of the previous data object.

Parameters:

newData - reference to the new data object, which must be of type type

Throws:

java.lang.IllegalArgumentException - if (newData == null) or if (newData.type() != type)

toString

public final java.lang.String toString()

Returns a string that represents the value of this object.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the receiver

valueChanged

public final void valueChanged(JSCDataEvent evt)

Transforms evt to the respective SymbolEvent and dispatches it to the SymbolListeners.

Specified by:

valueChanged in interface JSCDataListener

Parameters:

evt - the data event

copySymbol

public static void copySymbol(Symbol source,
                              Symbol target)

Moves data and listeners from one symbol to the other. The data is ONLY copied, if the source is not empty. The source will be cleared and all listeners will be removed. Nothing happens if (source == target).

Parameters:

source - to copy from

target - to copy to

Throws:

java.lang.IllegalArgumentException - if an argument is null