jimm.datavision
Class Expression

java.lang.Object
  java.util.Observable
      jimm.datavision.Expression

All Implemented Interfaces:

java.util.Observer, Draggable, Identity, Nameable, Writeable

Direct Known Subclasses:

Formula, UserColumn

public abstract class Expression
extends java.util.Observable
implements Identity, Nameable, Writeable, Draggable, java.util.Observer

The abstract superclass of objects that are evaluated, such as formulas and user columns. An expression contains text that is evaluated. The text may contain database column values, formulas, special values, or other types of objects.

Before being evaluated, the following substitutions are made withing the evaluation string:

• {table_name.column_name} is replaced by the current value of the column table_name.column_name.
• {@id_number} is replaced by the results of evaluating the formula whose id is id_number.
• {%special_value_name} is replaced by a special value (report title, report run date, page number, or record number).
• {?id_number} is replaced by a parameter value (string, number, or date).
• {!id_number} is replaced by a user column's value (string, number, or date).

Author:

Jim Menard, jimm@io.com

Field Summary

protected java.lang.String	exceptAfter
protected java.lang.String	expr
protected java.lang.Long	id
protected java.lang.String	name
protected java.util.ArrayList	observedContents
protected Report	report

Constructor Summary

protected

Expression(java.lang.Long id, Report report, java.lang.String name, java.lang.String expression, java.lang.String exceptAfter) Constructor.

Method Summary

java.util.Collection	columnsUsed() Returns a collection of the columns used in the expression.
abstract java.lang.String	designLabel()
static java.lang.String	displayToExpression(Report report, java.lang.String str) Given a string, returns a string with all instances of formula, parameter, and user column "display names" replaced by "formula strings".
abstract java.lang.String	dragString() Returns the string used to identify the object when dragging it.
static java.lang.String	expressionToDisplay(Report report, java.lang.String str) Given a string, returns a string with all instances of formula, parameter, and user column "formula strings" replaced by "display name" strings.
protected void	finalize()
abstract java.lang.String	formulaString()
java.lang.String	getEditableExpression() Returns the expression string fit for human consumption.
java.lang.String	getExpression() Returns the expression string.
java.lang.Object	getId() Returns the identity.
java.lang.String	getName() Returns the name for this expression.
boolean	refersTo(Expression expression) Returns true if this expression contains a reference to the specified expression (formula or user column).
boolean	refersTo(Field f) Returns true if this expression contains a reference to the specified field.
boolean	refersTo(Parameter p) Returns true if this expression contains a reference to the specified parameter.
void	setEditableExpression(java.lang.String newExpression) Sets the eval string after replacing formula, parameter, and user column names with their id numbers.
void	setExpression(java.lang.String newExpression) Sets the eval string.
void	setName(java.lang.String newName) Sets the name.
protected void	startObservingContents() Starts observing all observables referenced by this expression: formulas, parameters, and user columns.
protected void	stopObservingContents() Stops observing that which we were observing.
void	update(java.util.Observable o, java.lang.Object arg)
java.util.Collection	userColumnsUsed() Returns a collection of the user columns used in the expression.
protected void	writeAdditionalAttributes(XMLWriter out) Writes additional attributes.
abstract void	writeXML(XMLWriter out) Writes this expression as an XML tag.
protected void	writeXML(XMLWriter out, java.lang.String elementName)

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

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

Field Detail

id

protected java.lang.Long id

report

protected Report report

name

protected java.lang.String name

expr

protected java.lang.String expr

exceptAfter

protected java.lang.String exceptAfter

observedContents

protected java.util.ArrayList observedContents

Constructor Detail

Expression

protected Expression(java.lang.Long id,
                     Report report,
                     java.lang.String name,
                     java.lang.String expression,
                     java.lang.String exceptAfter)

Constructor. If id is null, throws an IllegalArgumentException. This is because subclasses are responsible for generating their id number. For example, formulas call Report.generateNewFormulaId.

Parameters:

id - the unique identifier for the new expression; may not be null

report - the report containing this expression

name - the expression name

expression - the string to evaulate at runtime; may be null

exceptAfter - when looking for things inside "{}" braces, ignore braces immediately after this string

Method Detail

expressionToDisplay

public static java.lang.String expressionToDisplay(Report report,
                                                   java.lang.String str)

Given a string, returns a string with all instances of formula, parameter, and user column "formula strings" replaced by "display name" strings. If there are no such strings, the original string is returned.

Returns:

a string with all formula strings replaced by display name strings

displayToExpression

public static java.lang.String displayToExpression(Report report,
                                                   java.lang.String str)

Given a string, returns a string with all instances of formula, parameter, and user column "display names" replaced by "formula strings". If there are no such strings, the original string is returned.

Parameters:

report - a report

str - a string with display names

Returns:

a string with all display names replaced by formula strings

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

update

public void update(java.util.Observable o,
                   java.lang.Object arg)

Specified by:

update in interface java.util.Observer

getId

public java.lang.Object getId()

Description copied from interface: Identity

Returns the identity.

Specified by:

getId in interface Identity

getName

public java.lang.String getName()

Returns the name for this expression.

Specified by:

getName in interface Nameable

Returns:

the name

setName

public void setName(java.lang.String newName)

Sets the name.

Specified by:

setName in interface Nameable

Parameters:

newName - the new name

getExpression

public java.lang.String getExpression()

Returns the expression string.

Returns:

the eval string

setExpression

public void setExpression(java.lang.String newExpression)

Sets the eval string.

Parameters:

newExpression - the new eval string

startObservingContents

protected void startObservingContents()

Starts observing all observables referenced by this expression: formulas, parameters, and user columns.

stopObservingContents

protected void stopObservingContents()

Stops observing that which we were observing.

getEditableExpression

public java.lang.String getEditableExpression()

Returns the expression string fit for human consumption. This mainly means that we substitute formula, parameter, and user column numbers with names. Called from any expression editor. This code assumes that curly braces are never nested.

Returns:

the eval string with formula, parameter, and user column id numbers replaced with names

setEditableExpression

public void setEditableExpression(java.lang.String newExpression)

Sets the eval string after replacing formula, parameter, and user column names with their id numbers. Called from a editor.

This method will throw an IllegalArgumentException if any formula, parameter, or user column name is not the name of some existing object.

Parameters:

newExpression - the new eval string

Throws:

java.lang.IllegalArgumentException

dragString

public abstract java.lang.String dragString()

Description copied from interface: Draggable

Returns the string used to identify the object when dragging it.

Specified by:

dragString in interface Draggable

Returns:

a string used to identify the object when dragging it

designLabel

public abstract java.lang.String designLabel()

formulaString

public abstract java.lang.String formulaString()

refersTo

public boolean refersTo(Field f)

Returns true if this expression contains a reference to the specified field.

Parameters:

f - a field

Returns:

true if this field contains a reference to the specified field

refersTo

public boolean refersTo(Expression expression)

Returns true if this expression contains a reference to the specified expression (formula or user column).

Parameters:

expression - an expression

Returns:

true if this field is the same as or contains a reference to the specified expression

refersTo

public boolean refersTo(Parameter p)

Returns true if this expression contains a reference to the specified parameter.

Parameters:

p - a parameter

Returns:

true if this field contains a reference to the specified parameter

columnsUsed

public java.util.Collection columnsUsed()

Returns a collection of the columns used in the expression. This is used by the report's query when it is figuring out what columns and tables are used by the report.

Returns:

a possibly empty collection of database columns

See Also:

Query.findSelectablesUsed()

userColumnsUsed

public java.util.Collection userColumnsUsed()

Returns a collection of the user columns used in the expression. This is used by the report's query when it is figuring out what columns, tables, and user columns are used by the report.

Returns:

a possibly empty collection of user columns

See Also:

Query.findSelectablesUsed()

writeXML

public abstract void writeXML(XMLWriter out)

Writes this expression as an XML tag.

Specified by:

writeXML in interface Writeable

Parameters:

out - a writer that knows how to write XML

writeXML

protected void writeXML(XMLWriter out,
                        java.lang.String elementName)

writeAdditionalAttributes

protected void writeAdditionalAttributes(XMLWriter out)

Writes additional attributes. Default behavior is to do nothing.

Parameters:

out - a writer that knows how to write XML