jApp
Class Variable

java.lang.Object
  jApp.Changeable
      jApp.Variable

All Implemented Interfaces:

ValueInterface

Direct Known Subclasses:

BooleanVariable, DoubleVariable, LongVariable, StringVariable

public class Variable
extends Changeable
implements ValueInterface

This class provides a way to create named variables that are persitently stored into a Document.

Features

Upwards/downwards compatible persistent storage

Variables are run-time objects that as such are not persitent. Instead they are explicitly created and named at run-time. The name is used in storing/retrieving the values of the variables from the Document file and the run-time object is used to refer to the value. This makes it possible to add named variables to documents in a non-fragile way, as new variables can be easily introduced as the application develops. When a Document is loaded from a file, the names are used to find the correct run-time variable into which the value is loaded. For variables that do not exist in a Document file, the variable retains the default value passed to its constructor. Note that Document does not remove variable values during save/load even if they values have not been associated with variable, which makes the system also downwards compatible.

Variables are usually created either in Document or ModalDialog initializers/constructors and associated with a document by calling Document.addVariable(String,Variable).

The objects that are used as Variable values need to implement Serializable interface.

Automatic OK/Cancel behaviour in modal dialogs

If variable values are changed while a Modal dialog is visible on the screen, the old values for the variables are saved for restoring, in case the user 'Cancel's the dialog. This happens automatically. Note that this value store/restore is done directly on variable values, so if the object that is the variable value is changed then there is no way the system can no about this and thus cannot save/restore the value. So this mechanism works best for conceptually immutable objects like String's and base type wrappers, like Integer's.

Observable value interface

Variables maintain a list of ChangeListener objects that are notified whenever the value of the object changes. This makes it very easy and bug free to associate widgets with variables. For example if a check box is created and associated with a varible by calling one of the createCheckBox methods of PartFactory, then whenever the value of that variable changes the check box will correctly reflect the state of the variable and the value of that variable can be changed by clicking that checkbox.

Use Pattern

Typically variables are created and refered to in dialogs, because in most cases they are used to store some value that is show/manipulated through that dialog:

   public class ExampleDialog extends ModalDialog
  
   {
        private ExampleDocument document;
        .... 
        private DoubleVariable exampleVariable;
        ....
  
        public ExampleDialog(ExampleDocument doc) {
            super(null, "Dialog Title");
            document = doc;
            <b>document.addVariable("EXAMPLE_VARIABLE",exampleVariable = new Variable(defaultValue));</b>
                ....
  
 

Typically the dialog object is created in an initialzer of the document member that is used to refer to the dialog:

   public class ExampleDocumentsh
        extends Document {
        public ExampleDialog exampleDialog = new ExampleDialog(this);
 

Version:

1.0

Author:

Kustaa Nyholm

See Also:

Document

Field Summary

protected java.lang.Object

m_Value

Fields inherited from interface jApp.ValueInterface

VALUE_VALID

Constructor Summary

Variable()
Constructs a variable with the initial (default) value of null

Variable(java.lang.Object value)
Constructs a variable with the given default value.

Method Summary

boolean	booleanValue() Casts the value of the variable to boolean and returns the boolean value.
double	doubleValue() Casts the value of the variable to Number and returns the long value.
java.lang.Object	getValue()
int	intValue() Casts the value of the variable to Number and returns the int value.
boolean	isEnabled()
long	longValue() Casts the value of the variable to Number and returns the long value.
int	numberOfValues()
static void	readVariables(java.io.ObjectInputStream stream, java.util.Hashtable variables) Reads in variable values from a stream.
void	setEnabled(boolean e)
void	setValue(java.lang.Object value)
void	showAlertDialog(int cause, Unit unit) Provided so that derived classes can provide their own specic alert dialogs in case an attempt is made to set the variable to an unacceptable value.
java.lang.String	stringValue() Converts the value of the variable to String by calling the Object.toString() method.
int	validate(java.lang.Object value) Validates the value and returns a constant describing the result
boolean	valueEquals(java.lang.Object value) Compares the equality of the variables value.
static void	writeVariables(java.io.ObjectOutputStream stream, java.util.Hashtable variables) Writes variable values to a stream.

Methods inherited from class jApp.Changeable

addChangeListener, fireChangeEvent, removeChangeListener

Methods inherited from class java.lang.Object

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

Methods inherited from interface jApp.ValueInterface

addChangeListener, removeChangeListener

Field Detail

m_Value

protected java.lang.Object m_Value

Constructor Detail

Variable

public Variable()

Constructs a variable with the initial (default) value of null

Variable

public Variable(java.lang.Object value)

Constructs a variable with the given default value.

Parameters:

value - the devault value.

Method Detail

writeVariables

public static void writeVariables(java.io.ObjectOutputStream stream,
                                  java.util.Hashtable variables)
                           throws java.lang.Exception

Writes variable values to a stream. This is mainly used by the Document class objects to store variable values, but has been made public because it is conceivable that it has other uses. This method presumes that the keys of the hashtable are the names of the variables String and the values are the variables.

Parameters:

stream - the stream to store the values to.

variables - a hashtable containing name/variable pairs.

Throws:

java.lang.Exception

readVariables

public static void readVariables(java.io.ObjectInputStream stream,
                                 java.util.Hashtable variables)
                          throws java.lang.Exception

Reads in variable values from a stream. This is mainly used by the Document class objects to store variable values, but has been made public because it is conceivable that it has other uses. This method presumes that the keys of the hashtable are the names of the variables String and the values are the variables.

Parameters:

stream - the stream to read the values from.

variables - a hashtable of name/variable pairs.

Throws:

java.lang.Exception

valueEquals

public boolean valueEquals(java.lang.Object value)

Compares the equality of the variables value.

Parameters:

value - the value to compare to the varible value.

Returns:

true if the values are equal

booleanValue

public boolean booleanValue()

Casts the value of the variable to boolean and returns the boolean value.

Returns:

the boolean value of the variable.

intValue

public int intValue()

Casts the value of the variable to Number and returns the int value.

Returns:

the int value of the variable.

longValue

public long longValue()

Casts the value of the variable to Number and returns the long value.

Returns:

the long value of the variable.

stringValue

public java.lang.String stringValue()

Converts the value of the variable to String by calling the Object.toString() method.

Returns:

the String value of the variable.

doubleValue

public double doubleValue()

Casts the value of the variable to Number and returns the long value.

Returns:

the double value of the variable.

showAlertDialog

public void showAlertDialog(int cause,
                            Unit unit)

Provided so that derived classes can provide their own specic alert dialogs in case an attempt is made to set the variable to an unacceptable value. s * @param cause an int value (defined by a derived class) that is the cause of the aler

Specified by:

showAlertDialog in interface ValueInterface

Parameters:

unit - the unit in which to express the variable value or the value range.

validate

public int validate(java.lang.Object value)

Validates the value and returns a constant describing the result

Specified by:

validate in interface ValueInterface

Parameters:

value - the value to validate

Returns:

by default returns ValueInterface.VALUE_VALID

setValue

public void setValue(java.lang.Object value)

Specified by:

setValue in interface ValueInterface

getValue

public java.lang.Object getValue()

Specified by:

getValue in interface ValueInterface

setEnabled

public void setEnabled(boolean e)

isEnabled

public boolean isEnabled()

Specified by:

isEnabled in interface ValueInterface

numberOfValues

public int numberOfValues()

Specified by:

numberOfValues in interface ValueInterface