com.waveset.expression
Class ExState

java.lang.Object
  extended bycom.waveset.expression.ExState
All Implemented Interfaces:
VariableResolver
Direct Known Subclasses:
ExpressionState, FormState, Interpreter, Rule.RuleState

public class ExState
extends java.lang.Object
implements VariableResolver

A class used to maintain runtime state during expression evaluation.

This may be subclassed by an application to provide implementaions of the methods resolveReference and resolveCall to handle special references to external functions and variables.


Nested Class Summary
protected  class ExState.ExBreakpointContext
           
 
Field Summary
static java.lang.String code_id
           
 
Constructor Summary
ExState()
          Construct a new expression state object.
 
Method Summary
 void addError(java.lang.Object msg)
          Add an error message.
 void addResolver(java.lang.Object res)
          Add a resolver.
protected  void beginTrace(ExNode node)
          Format the beginning of a trace message for a node.
 void beginTrace(java.lang.String context)
          Special trace method used for function calls and variable references, where we may "jump" to a new evaluation context that isn't obvious from the trace unless we wrap it in something.
 void breakpoint()
          Called by the expression.
 void breakpointEnd(com.sun.idm.debugger.common.Locatable locatable)
           
 void breakpointEnd(com.sun.idm.debugger.common.Locatable locatable, java.lang.Object lastValue)
           
protected  void breakpointEndAndTrace(ExNode node, ExValue retval)
          Convenience method which calls endTrace and breakpointEnd
 void breakpointStart(com.sun.idm.debugger.common.Locatable locatable)
           
protected  void breakpointStartAndTrace(ExNode node)
          Convenience method which calls breakpointStart and beginTrace
 boolean checkBreak(java.lang.String name)
          Called by statements that need to support breaking.
 void clearErrors()
          Clear the error list.
 void clearGlobalBindings()
          Clear the global bindings.
 void clearTrace()
          Clears the trace buffer.
protected  ExState.ExBreakpointContext createBreakpointContext()
          Creates a breakpoint context.
protected  void endTrace(ExNode node, ExValue retval)
          Format the end of a trace message for a node.
 void endTrace(java.lang.String context, ExValue retval)
          Special trace method for "called" contexts.
 void endTrace(java.lang.String context, java.lang.Object retval)
          Special trace method for "called" contexts.
protected  void enterScope(ExNode node, ExNode[] arglist)
          Enter a node scope.
protected  java.lang.Object externalCall(java.lang.String name, java.util.List args)
           
protected  java.lang.Object externalReference(ExReference node)
          Resolve a variable reference.
 java.lang.Object externalRule(java.lang.String name, java.util.Map args)
           
protected  java.util.Map externalRuleArguments()
           
 void free()
          Releases a state object back to the pool
static void freeState(ExState s)
          Releases a state object back to the pool.
 void freeValue(ExValue s)
          Return a value object back to the pool.
protected  ExNode getArgInitializer(ExDefvar arg, int psn)
          Locate a function argument initializer.
protected  ExValue getBinding(ExDefvar var)
          Return the bound value of a variable.
 ExState.ExBreakpointContext getBreakpointContext()
          Returns our BreakpointContext
 java.util.List getErrors()
          Get the error list.
 InvokeInterceptor getInvokeInterceptor()
           
protected  ExDefun getLibraryFunction(java.lang.String name)
          Look up the definition of a library function.
 java.util.Locale getLocale()
           
 java.util.Map getRuleArguments()
           
static ExState getState()
          Obtains a pooled state object.
 java.lang.String getTrace()
          Returns the current contents of the trace buffer as a String.
 java.lang.StringBuffer getTraceBuffer()
          Returns the trace buffer.
 void initBindings()
          Tear down all stacked scopes and return them to the pool.
 boolean isAllowExceptions()
          Test the allow exceptions flag.
 boolean isConsoleTraceEnabled()
          Returns true if console tracing is enabled.
 boolean isPrintEnabled()
          Test the option that enables output from expressions.
 boolean isTraceEnabled()
          Tests to see if tracing is enabled.
protected  void leaveScope(ExNode node)
          Leave a node scope.
 void loadLibrary(ExEnvironment env)
          A library loader that accepts an ExEnvironment.
 void loadLibrary(ExNode node)
          Load a library of functions contained within the node.
 void loadLibrary(java.util.List objects)
          Examine a list of objects, and link any ExDefuns we find.
 void markBreakpointStack()
           
 ExValue newValue()
          Obtain a value object from the pool.
 ExValue newValue(int i)
          Convenience method to obtain a new value from the pool and assign it an int.
 ExValue newValue(java.lang.Object o)
          Convenience method to obtain a new value from the pool and assign it an object.
 void print(java.lang.String msg)
          Called by the function when it has something to say.
static void println(java.lang.String msg)
           
 void printTrace()
          Flush the trace buffer to the console.
protected  ExValue promoteValue(ExValue src)
          Return a value that can be modified and returned.
 void removeResolver(java.lang.Object res)
          Remove a resolver.
 java.lang.Object resolveCall(java.lang.String name, java.util.List args)
           
 java.lang.Object resolveObject(java.lang.String path)
          Implement this if you want to resolve elements.
 java.lang.Object resolveReference(java.lang.String name)
           
 java.lang.Object resolveRule(java.lang.String name, java.util.Map args)
           
 java.lang.Object resolveVariable(java.lang.String name)
          This is the VariableResolver interface method.
 void setAllowExceptions(boolean b)
          Set the exception propagation flag.
protected  void setBinding(ExDefvar var, ExValue value)
          Set the binding of variable.
 void setConsoleTraceEnable(boolean t)
          Enable or disable tracing to the console.
 void setConsoleTraceEnable(boolean t, boolean force)
          Enable or disable tracing to the console.
 void setExternal(java.lang.String name, java.lang.Object value)
           
 void setInvokeInterceptor(InvokeInterceptor i)
           
 void setLocale(java.util.Locale l)
          Set the locale for Message rendering.
 void setPrimaryResolver(ExResolver re)
          Set the primary resolver.
 void setPrintEnable(boolean b)
          Enable or disable output from expressions.
 void setPrintStream(java.io.PrintStream ps)
          Set the output stream for messages.
 void setTraceEnable(boolean t)
          Enable or diable evaluation tracing.
 void setTraceEnable(boolean t, boolean force)
          Enable or diable evaluation tracing.
 void signalBreak(java.lang.String name)
          Signal an execution break.
protected  void trace(java.lang.String msg)
          Append something to the trace buffer.
 void unwindBreakpointStack()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

code_id

public static final java.lang.String code_id
See Also:
Constant Field Values
Constructor Detail

ExState

public ExState()
Construct a new expression state object.

Method Detail

resolveReference

public java.lang.Object resolveReference(java.lang.String name)
                                  throws WavesetException
Throws:
WavesetException

resolveCall

public java.lang.Object resolveCall(java.lang.String name,
                                    java.util.List args)
                             throws WavesetException
Throws:
WavesetException

resolveRule

public java.lang.Object resolveRule(java.lang.String name,
                                    java.util.Map args)
                             throws WavesetException
Throws:
WavesetException

resolveObject

public java.lang.Object resolveObject(java.lang.String path)
                               throws WavesetException
Implement this if you want to resolve elements. This shouldn't be necessary any more, but older workflows used it.

Throws:
WavesetException

setExternal

public void setExternal(java.lang.String name,
                        java.lang.Object value)
                 throws WavesetException
Throws:
WavesetException

getRuleArguments

public java.util.Map getRuleArguments()

getState

public static ExState getState()
Obtains a pooled state object.


freeState

public static void freeState(ExState s)
Releases a state object back to the pool.


free

public void free()
Releases a state object back to the pool


setLocale

public void setLocale(java.util.Locale l)
Set the locale for Message rendering.


getLocale

public java.util.Locale getLocale()

setPrimaryResolver

public void setPrimaryResolver(ExResolver re)
Set the primary resolver.


addResolver

public void addResolver(java.lang.Object res)
Add a resolver. These are "pushed" on a stack so that the more recently added resolvers are consulted first.


removeResolver

public void removeResolver(java.lang.Object res)
Remove a resolver. Ordinarilly these will be popped in the same order that they were added, but I suppose you might want to remove one out of the middle of the stack?


setInvokeInterceptor

public void setInvokeInterceptor(InvokeInterceptor i)

getInvokeInterceptor

public InvokeInterceptor getInvokeInterceptor()

resolveVariable

public java.lang.Object resolveVariable(java.lang.String name)
                                 throws WavesetException
This is the VariableResolver interface method. We implement this so the ExState can be used to expand $(var) references in strings. Primarily this was for Property objects. We can't actually do anything here since we have no ExNode to provide context for the reference. I suppose we could check the _globalBindings map, but since that is built up on demand, it is unreliable. Assume that the subclass will overload this as appropriate. UPDATE: If not overloaded by the subclass, we will assume this is the same as an external variable reference.

Specified by:
resolveVariable in interface VariableResolver
Throws:
WavesetException

externalReference

protected java.lang.Object externalReference(ExReference node)
                                      throws WavesetException
Resolve a variable reference. This is the method that should be called internally, we will first consult the list of resolver objects before passing control to the overloaded resolveReference method

Throws:
WavesetException

externalCall

protected java.lang.Object externalCall(java.lang.String name,
                                        java.util.List args)
                                 throws WavesetException
Throws:
WavesetException

externalRule

public java.lang.Object externalRule(java.lang.String name,
                                     java.util.Map args)
                              throws WavesetException
Throws:
WavesetException

externalRuleArguments

protected java.util.Map externalRuleArguments()
                                       throws WavesetException
Throws:
WavesetException

isAllowExceptions

public boolean isAllowExceptions()
Test the allow exceptions flag.


setAllowExceptions

public void setAllowExceptions(boolean b)
Set the exception propagation flag.


clearErrors

public void clearErrors()
Clear the error list.


getErrors

public java.util.List getErrors()
Get the error list. These will be String objects.


addError

public void addError(java.lang.Object msg)
Add an error message. Normally a String or Message.


newValue

public ExValue newValue()
Obtain a value object from the pool.


newValue

public ExValue newValue(java.lang.Object o)
Convenience method to obtain a new value from the pool and assign it an object. Since setValue throws an exception if the value was interned, we catch that here.


newValue

public ExValue newValue(int i)
Convenience method to obtain a new value from the pool and assign it an int. Since setValue throws an exception if the value was interned, we catch that here.


freeValue

public void freeValue(ExValue s)
Return a value object back to the pool.


promoteValue

protected ExValue promoteValue(ExValue src)
Return a value that can be modified and returned.

If the value is interned, or has a a reference count more than one, we have to copy the value.


initBindings

public void initBindings()
Tear down all stacked scopes and return them to the pool. Used to cleanup evaluation state on termination. Also now used to clear the global bindings.


enterScope

protected void enterScope(ExNode node,
                          ExNode[] arglist)
Enter a node scope.


leaveScope

protected void leaveScope(ExNode node)
Leave a node scope.


getBinding

protected ExValue getBinding(ExDefvar var)
                      throws WavesetException
Return the bound value of a variable.

Throws:
WavesetException

clearGlobalBindings

public void clearGlobalBindings()
Clear the global bindings.


setBinding

protected void setBinding(ExDefvar var,
                          ExValue value)
                   throws WavesetException
Set the binding of variable.

Throws:
WavesetException

getArgInitializer

protected ExNode getArgInitializer(ExDefvar arg,
                                   int psn)
                            throws WavesetException
Locate a function argument initializer. ExDefvar is the argument we're trying to resolve, locate the ExScope associated with the ExDefun that contains it. Then use the argument position to locate the initializer.

Throws:
WavesetException

setPrintEnable

public void setPrintEnable(boolean b)
Enable or disable output from expressions. This is normally on, but there may be occasions where you want to turn it off and leave debugging statements in an expression.


isPrintEnabled

public boolean isPrintEnabled()
Test the option that enables output from expressions.


setPrintStream

public void setPrintStream(java.io.PrintStream ps)
Set the output stream for messages. If this is null, messages are sent to System.out.


setTraceEnable

public void setTraceEnable(boolean t)
Enable or diable evaluation tracing.

The trace messages are accumulated in an internal StringBuffer that may be accessed with the getTrace or getTraceBuffer methods. Setting this true does not cause the trace messages to be sent to the console, they are only accumulated in the trace buffer. The host application must call getTrace to retrieve the contents of the trace buffer and display it in an appropriate way.

If Waveset.properties turns on trace, this is ignored.


setTraceEnable

public void setTraceEnable(boolean t,
                           boolean force)
Enable or diable evaluation tracing.

The trace messages are accumulated in an internal StringBuffer that may be accessed with the getTrace or getTraceBuffer methods. Setting this true does not cause the trace messages to be sent to the console, they are only accumulated in the trace buffer. The host application must call getTrace to retrieve the contents of the trace buffer and display it in an appropriate way.

If force is set to true, it will override whatever is specified in Waveset.properties and override whatever is specified by the block element's trace attribute.


setConsoleTraceEnable

public void setConsoleTraceEnable(boolean t)
Enable or disable tracing to the console.

Unlike setTraceEnable, setting this option will cause trace messages to be sent immediately to the console. They will not accumulate in the trace buffer.

If Waveset.properties turns on trace, this is ignored.


setConsoleTraceEnable

public void setConsoleTraceEnable(boolean t,
                                  boolean force)
Enable or disable tracing to the console.

Unlike setTraceEnable, setting this option will cause trace messages to be sent immediately to the console. They will not accumulate in the trace buffer.

If force is set to true, it will override the settings in Waveset.properties and override whatever is specified by the block element's trace attribute.


isTraceEnabled

public boolean isTraceEnabled()
Tests to see if tracing is enabled.


isConsoleTraceEnabled

public boolean isConsoleTraceEnabled()
Returns true if console tracing is enabled.


getTrace

public java.lang.String getTrace()
Returns the current contents of the trace buffer as a String.


getTraceBuffer

public java.lang.StringBuffer getTraceBuffer()
Returns the trace buffer.

This might be used by host applications that want to add things to the trace buffer.


clearTrace

public void clearTrace()
Clears the trace buffer.


printTrace

public void printTrace()
Flush the trace buffer to the console.


beginTrace

protected void beginTrace(ExNode node)
Format the beginning of a trace message for a node.


breakpointStartAndTrace

protected final void breakpointStartAndTrace(ExNode node)
Convenience method which calls breakpointStart and beginTrace


beginTrace

public void beginTrace(java.lang.String context)
Special trace method used for function calls and variable references, where we may "jump" to a new evaluation context that isn't obvious from the trace unless we wrap it in something.


endTrace

protected void endTrace(ExNode node,
                        ExValue retval)
Format the end of a trace message for a node.


breakpointEndAndTrace

protected final void breakpointEndAndTrace(ExNode node,
                                           ExValue retval)
Convenience method which calls endTrace and breakpointEnd


endTrace

public void endTrace(java.lang.String context,
                     ExValue retval)
Special trace method for "called" contexts.


endTrace

public void endTrace(java.lang.String context,
                     java.lang.Object retval)
Special trace method for "called" contexts.


trace

protected void trace(java.lang.String msg)
Append something to the trace buffer. Added for Javascript trace.


signalBreak

public void signalBreak(java.lang.String name)
Signal an execution break. This is like a break statement within looping statements in Java, but here it applies to any function that takes a variable length argument list. Among other things, this can be used to simulate a "switch" statement using the function. This method is ordinarilly only called by the f_break object, but it is concievable that an application might want to signal a break during a callback.

The name is optional, if specified, we will unwind until we locate an expression with the name.


checkBreak

public boolean checkBreak(java.lang.String name)
Called by statements that need to support breaking. If the statement has a name it is passed in. Returns true if a break should be taken. The break is cleared if it is not named, or of the given name matches.


getLibraryFunction

protected ExDefun getLibraryFunction(java.lang.String name)
Look up the definition of a library function. This will be called by ExCall when if finds an unresolved function, but before it calls the abstract resolveCall method to let the host application handle the function.

Here, we look to see if a function with this name has been registered in our "link map".


loadLibrary

public void loadLibrary(ExEnvironment env)
A library loader that accepts an ExEnvironment. Most libraries will have one of these in order to resolve inter-library references.


loadLibrary

public void loadLibrary(ExNode node)
Load a library of functions contained within the node.


loadLibrary

public void loadLibrary(java.util.List objects)
Examine a list of objects, and link any ExDefuns we find.


breakpoint

public void breakpoint()
Called by the expression.

This is a convenient place to park a debugger breakpoint, then insert statements at interesting places in the expression source code.


print

public void print(java.lang.String msg)
Called by the function when it has something to say. By default we send messages to System.out. The output stream can be set by the application.


println

public static void println(java.lang.String msg)

getBreakpointContext

public final ExState.ExBreakpointContext getBreakpointContext()
Returns our BreakpointContext


breakpointStart

public void breakpointStart(com.sun.idm.debugger.common.Locatable locatable)

breakpointEnd

public void breakpointEnd(com.sun.idm.debugger.common.Locatable locatable)

breakpointEnd

public void breakpointEnd(com.sun.idm.debugger.common.Locatable locatable,
                          java.lang.Object lastValue)

markBreakpointStack

public void markBreakpointStack()

unwindBreakpointStack

public void unwindBreakpointStack()

createBreakpointContext

protected ExState.ExBreakpointContext createBreakpointContext()
Creates a breakpoint context. Subclasses may override this method to return their own implementations of BreakpointContext. I went this route rather than having ExState implement BreakpointContext cause I wanted to be able to extend AbstractBreakpointContext and felt it was too messy to polute the type hierarchy with a new base class. Also ExBreakpointContext is pretty big so this helps to keep it separated.