plugins.adufour.vars.lang
Class Var<T>

java.lang.Object
  plugins.adufour.vars.lang.Var<T>

Type Parameters:

T - The type of the inner (boxed) value

All Implemented Interfaces:

icy.file.xml.XMLPersistent, VarListener<T>

Direct Known Subclasses:

VarBoolean, VarChannel, VarEnum, VarFile, VarGenericArray, VarImagePlus, VarMutable, VarNumber, VarObject, VarPlugin, VarPoint5D, VarSequence, VarString, VarSwimmingObject

public class Var<T>
extends java.lang.Object
implements icy.file.xml.XMLPersistent, VarListener<T>

Top-level class defining a generic variable. A Var object embeds an inner value of generic type T, and offers a number of methods to get/set this value, hide the inner value with a virtual reference to another compatible Var object, and listen to value or reference changes via the VarListener interface.

While many subclasses are available for most common data types (see the direct sub-classes in this package), it is possible to create custom variable types by extending these classes. The most important methods to override are the following:

• The empty parse(String) method should be overridden to provide the ability to read text input (either from a graphical interface or when saving/reading data from XML files).
• The getValueAsString() method returns a pretty-printed version of the variable's value, and is used to display and store the value into XML files. Overriding implementations should make sure that the result of this method is compatible with the parse(String) method to ensure proper reloading from XML files.
• The isAssignableFrom(Var) indicates which types of variables can be used as reference variables. The default implementation relies on the native Class.isAssignableFrom(Class) method, but can be overridden to fine-tune the type of supported data (see the VarGenericArray.isAssignableFrom(Var) method for an example).
• The createVarEditor() method is responsible for generating a VarEditor object that will handle user interaction in a graphical user interface. For each variable type, a default VarEditor is provided, but overriding implementation can provide their own component.

Author:

Alexandre Dufour

See Also:

VarEditor

Field Summary

protected java.util.List<VarListener<T>>	listeners
static java.lang.String	NO_VALUE User-friendly representation of the Java null keyword
protected java.lang.Class<T>	type The Class definition describing the type of the variable value
static java.lang.String	XML_KEY_ID Attribute key defining the unique identifier of a variable.

Constructor Summary

Var(java.lang.String name, java.lang.Class<T> type)
Creates a new Variable with specified name and inner value type (the default value is set to null).

Var(java.lang.String name, java.lang.Class<T> type, T defaultValue)
Creates a new Variable with the specified name, and inner value type and default value (may be null).

Var(java.lang.String name, T defaultValue)
Creates a new Variable with given name and non-null default value.

Var(java.lang.String name, VarEditorModel<T> editorModel)
Creates a new Variable with the specified name and editor model.

Method Summary

void	addListener(VarListener<T> listener) Adds the specified listener to the list of registered listeners
VarEditor<T>	createVarEditor() Creates a new VarEditor object that allows the user to graphically adjust the value of this variable.
VarEditor<T>	createVarViewer() Creates a new VarEditor object that allows the user to view the value of this variable (but not necessarily modify it).
protected void	fireVariableChanged(T oldValue, T newValue)
protected void	fireVariableChanged(Var<? extends T> oldRef, Var<? extends T> newRef)
VarEditorModel<T>	getDefaultEditorModel()
T	getDefaultValue()
java.lang.Iterable<Var<? super T>>	getIterableReferrers()
java.lang.String	getName()
Var<? extends T>	getReference()
VarReferencingPolicy	getReferencingPolicy()
java.util.Iterator<Var<? super T>>	getReferrers()
java.lang.Class<T>	getType()
java.lang.String	getTypeAsString()
T	getValue()
T	getValue(boolean forbidNull)
java.lang.String	getValueAsString()
java.lang.String	getValueAsString(boolean followReference)
boolean	isAssignableFrom(Var<?> source) Checks whether the type of the given variable is equal or extends this variable's type. If the result is true, then the given variable can become a link source for this variable
boolean	isEnabled()
boolean	isOptional()
boolean	isReferenced()
boolean	loadFromXML(org.w3c.dom.Node node)
T	parse(java.lang.String text) Parses the given String into the current type
java.lang.String	prettyPrint(java.lang.String separator)
void	referenceChanged(Var<T> source, Var<? extends T> oldReference, Var<? extends T> newReference) Called when the variable reference changes
void	removeListener(VarListener<T> listener) Removes the specified listener from the list of registered listeners.
void	removeListeners() Removes all listeners currently registered to this variable.
boolean	saveToXML(org.w3c.dom.Node node) Saves the current variable to the specified node
void	setDefaultEditorModel(VarEditorModel<T> model) Sets a default VarEditorModel object which can be used to generate a graphical editor for this variable.
void	setEnabled(boolean enabled) Indicates whether this variable should be used or not by plug-ins.
void	setOptional(boolean optional) Sets a flag indicating whether this variable should be considered "optional".
void	setReference(Var<T> variable) Sets the current variable to reference the specified variable (or null to release the reference).
void	setReferencingPolicy(VarReferencingPolicy policy) Sets whether this variable may or may not reference another one.
void	setValue(T newValue) Sets the value of this variable and notify the listeners.
java.lang.String	toString()
void	valueChanged(Var<T> source, T oldValue, T newValue) Called when this variable has a non-null reference and receives a value-changed event from this reference

Methods inherited from class java.lang.Object

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

Field Detail

XML_KEY_ID

public static final java.lang.String XML_KEY_ID

Attribute key defining the unique identifier of a variable. This key is used by the XMLPersistent mechanism to save/load the variable value to/from XML files.

See Also:

Constant Field Values

NO_VALUE

public static final java.lang.String NO_VALUE

User-friendly representation of the Java null keyword

See Also:

Constant Field Values

type

protected java.lang.Class<T> type

The Class definition describing the type of the variable value

listeners

protected final java.util.List<VarListener<T>> listeners

Constructor Detail

Var

public Var(java.lang.String name,
           T defaultValue)
    throws java.lang.NullPointerException

Creates a new Variable with given name and non-null default value.

Parameters:

name - the name of this variable

defaultValue - the non-null default value of this variable

Throws:

java.lang.NullPointerException - if defaultValue is null

Var

public Var(java.lang.String name,
           java.lang.Class<T> type)

Creates a new Variable with specified name and inner value type (the default value is set to null).

Parameters:

name - the name of this variable

type - the type of this variable

Var

public Var(java.lang.String name,
           VarEditorModel<T> editorModel)

Creates a new Variable with the specified name and editor model.

Parameters:

name - the name of this variable

editorModel - the default editor model of this variable (can be changed later via the setDefaultEditorModel(VarEditorModel) method

Var

public Var(java.lang.String name,
           java.lang.Class<T> type,
           T defaultValue)

Creates a new Variable with the specified name, and inner value type and default value (may be null).

Parameters:

name - the name of this variable

type - the type of this variable

Method Detail

addListener

public void addListener(VarListener<T> listener)

Adds the specified listener to the list of registered listeners

Parameters:

listener - the listener to register

createVarEditor

public VarEditor<T> createVarEditor()

Creates a new VarEditor object that allows the user to graphically adjust the value of this variable. By default this editor is an empty label for generic types, but this method can be overridden to provide a custom editor.

Returns:

the variable editor embarking the graphical component

createVarViewer

public VarEditor<T> createVarViewer()

Creates a new VarEditor object that allows the user to view the value of this variable (but not necessarily modify it). By default this editor is an empty label for generic types, but this method can be overridden to provide a custom viewer

Returns:

the variable editor embarking the graphical component

fireVariableChanged

protected void fireVariableChanged(Var<? extends T> oldRef,
                                   Var<? extends T> newRef)

fireVariableChanged

protected void fireVariableChanged(T oldValue,
                                   T newValue)

getDefaultEditorModel

public VarEditorModel<T> getDefaultEditorModel()

Returns:

the default editor model

getDefaultValue

public T getDefaultValue()

getName

public java.lang.String getName()

getReference

public Var<? extends T> getReference()

Returns:

The variable referenced by the current variable (or null if no variable is referenced)

See Also:

getValue()

getReferrers

public java.util.Iterator<Var<? super T>> getReferrers()

Returns:

A list of all the variables currently pointing to this variable

getIterableReferrers

public java.lang.Iterable<Var<? super T>> getIterableReferrers()

Returns:

An iterable list of all the variables currently pointing to this variable

isEnabled

public boolean isEnabled()

Returns:

true if this variable should be used by plug-ins, or false if it should not be used

isOptional

public boolean isOptional()

Returns:

true if this variable has been flagged as "optional" by the user, e.g. optional parameters

isReferenced

public boolean isReferenced()

Returns:

true if at least one variable is referencing this variable, false otherwise

getType

public java.lang.Class<T> getType()

Returns:

a Class object defining the type of the variable's value.

getTypeAsString

public java.lang.String getTypeAsString()

Returns:

a user-friendly text describing the type of this variable. By default the returned string is the simple class name of this variable's value (as defined by the Class.getSimpleName() method).

getValue

public T getValue()

Returns:

the value stored in this variable, or the value in the referenced variable if the reference is not null. Note that this method may return null. To forbid null values, use the getValue(boolean) method instead.

See Also:

getReference()

getValue

public T getValue(boolean forbidNull)
           throws VarException

Parameters:

forbidNull - true to throw an exception if the underlying value is null

Returns:

the value stored in this variable, or the value in the referenced variable if the reference is not null. Note that this method will throw a VarException if the forbidNull argument is true

Throws:

VarException

See Also:

getReference()

getValueAsString

public java.lang.String getValueAsString(boolean followReference)

Parameters:

followReference - set to true to return the String representation of the reference variable (if any)

Returns:

a pretty-printed text representation of the variable's value. This text is used to display the value (e.g. in a graphical interface) or store the value into XML files. Overriding implementations should make sure that the result of this method is compatible with the parse(String) method to ensure proper reloading from XML files.

getValueAsString

public java.lang.String getValueAsString()

Returns:

a pretty-printed text representation of the variable's local value (referenced variables are not followed). This text is used to display the value (e.g. in a graphical interface) or store the value into XML files. Overriding implementations should make sure that the result of this method is compatible with the parse(String) method to ensure proper reloading from XML files.

isAssignableFrom

public boolean isAssignableFrom(Var<?> source)

Checks whether the type of the given variable is equal or extends this variable's type.
If the result is true, then the given variable can become a link source for this variable

Parameters:

source -

Returns:

true if the source type is equal or wider than this variable's type, false otherwise (including if source has null type)

loadFromXML

public boolean loadFromXML(org.w3c.dom.Node node)

Specified by:

loadFromXML in interface icy.file.xml.XMLPersistent

parse

public T parse(java.lang.String text)

Parses the given String into the current type

Parameters:

text -

Returns:

The variable value corresponding to the given string

Throws:

java.lang.UnsupportedOperationException - if the parser has not been implemented for the current type

prettyPrint

public java.lang.String prettyPrint(java.lang.String separator)

Parameters:

separator - Separator character used if value is an array

Returns:

A user-friendly representation of the specified value.

removeListener

public void removeListener(VarListener<T> listener)

Removes the specified listener from the list of registered listeners.

Parameters:

listener - the listener to remove

removeListeners

public void removeListeners()

Removes all listeners currently registered to this variable.

saveToXML

public boolean saveToXML(org.w3c.dom.Node node)
                  throws java.lang.UnsupportedOperationException

Saves the current variable to the specified node

Specified by:

saveToXML in interface icy.file.xml.XMLPersistent

Throws:

java.lang.UnsupportedOperationException - if the functionality is not supported by the current variable type

setDefaultEditorModel

public void setDefaultEditorModel(VarEditorModel<T> model)

Sets a default VarEditorModel object which can be used to generate a graphical editor for this variable. This default model is used by the createVarEditor() method is overridden to provide a custom editor

Parameters:

model - the model used by the createVarEditor() method to generate the appropriate graphical component

See Also:

VarEditorModel

setOptional

public void setOptional(boolean optional)

Sets a flag indicating whether this variable should be considered "optional". This flag is typically used to mark a plug-in parameter as optional, allowing plug-ins to react accordingly and save potentially unnecessary computations. Setting a variable as optional will add a check-box next to the variable editor to provide visual feedback

Parameters:

optional - true to indicate that this variable is optional

setEnabled

public void setEnabled(boolean enabled)

Indicates whether this variable should be used or not by plug-ins. It is up to the responsibility of plug-ins to take this flag into account. See also setOptional(boolean)

Parameters:

enabled - true if this variable can be used by plug-ins, and false if the variable should not be used by plug-ins during computations

setReference

public void setReference(Var<T> variable)
                  throws java.lang.ClassCastException

Sets the current variable to reference the specified variable (or null to release the reference). If the reference is non-null, the getValue() method will disregard the local value and return the value of the referenced variable

Parameters:

variable - the variable to reference

Throws:

java.lang.ClassCastException - if the two arguments are incompatible and cannot be linked

setReferencingPolicy

public void setReferencingPolicy(VarReferencingPolicy policy)

Sets whether this variable may or may not reference another one. By default, this value is true

Parameters:

policy - the new referencing policy

See Also:

VarReferencingPolicy

getReferencingPolicy

public VarReferencingPolicy getReferencingPolicy()

Returns:

the referencing policy for this variable

setValue

public void setValue(T newValue)
              throws java.lang.IllegalAccessError,
                     java.lang.IllegalArgumentException

Sets the value of this variable and notify the listeners. This method can only be called if this variable is not referencing another one.

Parameters:

newValue -

Throws:

java.lang.IllegalAccessError - if this variable is already linked to another one

java.lang.IllegalArgumentException - if this variable has a non-null editor model and the specified value is not valid for this model

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

valueChanged

public void valueChanged(Var<T> source,
                         T oldValue,
                         T newValue)

Called when this variable has a non-null reference and receives a value-changed event from this reference

Specified by:

valueChanged in interface VarListener<T>

Parameters:

source - the variable sending the event. This should be equal to the result of getReference()

oldValue - the old variable value

newValue - the new variable value

referenceChanged

public void referenceChanged(Var<T> source,
                             Var<? extends T> oldReference,
                             Var<? extends T> newReference)

Description copied from interface: VarListener

Called when the variable reference changes

Specified by:

referenceChanged in interface VarListener<T>

Parameters:

source - the variable firing the listener

oldReference - the old variable reference

newReference - the new variable reference