com.waveset.object
Class FormState

java.lang.Object
  extended bycom.waveset.expression.ExState
      extended bycom.waveset.object.FormState
All Implemented Interfaces:
VariableResolver

public class FormState
extends ExState
implements VariableResolver

A class encapsulating the runtime state associated with Form evaluation.

This extends the ExState object so it can serve as an XPRESS state holder. It also contains the form inputs and outputs, and various evaluation options.


Nested Class Summary
static class FormState.MissingRequiredField
           
 
Nested classes inherited from class com.waveset.expression.ExState
ExState.ExBreakpointContext
 
Field Summary
static java.lang.String code_id
           
 
Constructor Summary
FormState(Form form, ObjectCache cache)
          Build a new FormState object.
 
Method Summary
 void bindVariable(java.lang.String name, java.lang.Object value)
           
 void clearVariables()
           
protected  ExState.ExBreakpointContext createBreakpointContext()
          Override createBreakpointContext to create a FormBreakpointContext instead.
 void cycle(java.util.Map object)
          Convenience method to do a very common derive/expand cycle on a GenericObject.
 void derive()
          Iterate over form fields running Derivation and Default expressions.
 void expand()
          Run form expansion.
 java.lang.String expandVariables(java.lang.String src)
          Expand any variable references in a string.
 void formCycleEnd(com.sun.idm.debugger.common.FormCycle cycle)
           
 com.sun.idm.debugger.common.FormCycle formCycleStart(com.sun.idm.debugger.common.FormCycle.Phase phase)
           
 com.sun.idm.debugger.common.FormCycle formCycleStart(com.sun.idm.debugger.common.FormCycle.Phase phase, int iteration)
           
 Form.Field getField(java.lang.String name)
          Look up a field object, handling inclusions.
 FieldIterator getFieldIterator()
           
 Form getForm()
          Get the Form, exposed only for FieldIterator.
protected  java.util.Map getInputs()
          Get the input variable map, exposed only for FieldIterator.
 java.lang.Object getOutput(java.lang.String name)
          Get one output value.
 java.util.Map getOutputs()
          Return the output map.
 boolean isTolerateInvalid()
           
 FieldIterator iterate()
          Return an iterator for the Form.Field objects in the form.
static void println(java.lang.String msg)
           
 void reset()
          Reset both inputs and outputs.
 void resetOutputs()
          Clear the current outputs.
 Form.Field resolve(Form.FieldRef ref)
          Resolve a field reference.
 Form resolve(Form.FormRef ref)
          Resolve a form reference.
 java.lang.Object resolveCall(java.lang.String name, java.util.List arglist)
          Resolve an external function call.
 void resolveIncludes()
          Load libraries included by the form.
 java.lang.Object resolveReference(java.lang.String name)
          Resolve a reference from within a form expression.
 java.lang.Object resolveRule(java.lang.String name, java.util.Map args)
          Resolve a rule call.
 java.lang.Object resolveVariable(java.lang.String name)
          This is the VariableResolver interface method, called during the expansion of $(var) references.
 void setBaseContext(java.lang.String bc)
           
 void setContext(LighthouseContext lc)
           
 void setExternal(java.lang.String name, java.lang.Object value)
          ExState method to assign an external variable.
 void setFieldIterator(FieldIterator it)
          This will be called as a side effect of the construction of a FieldIterator object so we have a circular reference.
 void setIncludeInputs(boolean b)
          Set a flag that indicates that original input values are to be included in the output values.
 void setIncludeUnknowns(boolean b)
          Set a flag that indicates that any input values that do not correspond to Field names are to be passed through to the outputs.
 void setInput(java.lang.String name, java.lang.Object value)
          Set an input value.
 void setInputs(java.util.Map inputs)
          Assign the set if form input values.
 void setMaxIterations(int i)
          Set the maximum number of iterations we will perform during form expansion.
 void setNullValue(java.lang.String s)
          Option to specify a special string value that is used to represent a null value.
 void setOutputs(java.util.Map map)
          Set the output map.
 void setRuleExecutor(RuleExecutor re)
          Set the optional rule executor.
 void setTolerateInvalid(boolean b)
          Set a flag indicating that values that don't match their constraint list should be tolerated.
 void setTrace(boolean t)
          Enable or disable trace.
 void setVariable(java.lang.String name, java.lang.Object value)
          Should only be called if you have already called bindVariable and just want to change the current value.
 void setView(GenericObject view)
          Assign a view to be proessed by the form.
 void unbindVariable(java.lang.String name)
           
 java.util.List validate()
          Run form validation.
 
Methods inherited from class com.waveset.expression.ExState
addError, addResolver, beginTrace, beginTrace, breakpoint, breakpointEnd, breakpointEnd, breakpointEndAndTrace, breakpointStart, breakpointStartAndTrace, checkBreak, clearErrors, clearGlobalBindings, clearTrace, endTrace, endTrace, endTrace, enterScope, externalCall, externalReference, externalRule, externalRuleArguments, free, freeState, freeValue, getArgInitializer, getBinding, getBreakpointContext, getErrors, getInvokeInterceptor, getLibraryFunction, getLocale, getRuleArguments, getState, getTrace, getTraceBuffer, initBindings, isAllowExceptions, isConsoleTraceEnabled, isPrintEnabled, isTraceEnabled, leaveScope, loadLibrary, loadLibrary, loadLibrary, markBreakpointStack, newValue, newValue, newValue, print, printTrace, promoteValue, removeResolver, resolveObject, setAllowExceptions, setBinding, setConsoleTraceEnable, setConsoleTraceEnable, setInvokeInterceptor, setLocale, setPrimaryResolver, setPrintEnable, setPrintStream, setTraceEnable, setTraceEnable, signalBreak, trace, 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

FormState

public FormState(Form form,
                 ObjectCache cache)
          throws WavesetException
Build a new FormState object. We originally needed a cache in order to resolve form includes, that isn't necessary now, we expect includes to have been resolved by a higher power. It is now used to resolve references to Rules as external XPRESS calls.

Method Detail

setRuleExecutor

public void setRuleExecutor(RuleExecutor re)
Set the optional rule executor.


setContext

public void setContext(LighthouseContext lc)

setNullValue

public void setNullValue(java.lang.String s)
Option to specify a special string value that is used to represent a null value. When this is set, if an expansion expression returns null, the expansion is NOT included in the output map. Instead, if you want an expansion to result in a null value being output, you must arrange for the expansion to return the value of this string. This is used in cases where the input map may be "sparse" and not contain values for everything that will be referenced in an expansion. Such is the case in the web services interfaces where an update request can come in with a few attributes that are to be assimilated into a view. The attributes are usually processed by a form to convert external names into view paths. But unless the values for all attributes referenced in an expansion are provided, when the expansions are run we may end up trashing things that were not specified in the update since the expansion will be null. But we can't just ignore null expansions since it has to be possible for an expansion to set something to null. If you need to support sparse input maps, and also need to be able to set things to null, you must use this option.


setInputs

public void setInputs(java.util.Map inputs)
Assign the set if form input values. Note that changing the form inputs, may affect the cached values for any global variables in the XPRESS state since they're values may have been derived from the previous inputs. For consistency, we have to initialize the XPRESS state.


setOutputs

public void setOutputs(java.util.Map map)
Set the output map. You might want to assign a target GenericObject here, this may also be the same as the _inputs map. That way, expansion circles back and modifies the soruce object which is usually what you want.


setView

public void setView(GenericObject view)
Assign a view to be proessed by the form. This is the way forms are normally used, the view serves as both the input and output map.


resetOutputs

public void resetOutputs()
Clear the current outputs.


reset

public void reset()
Reset both inputs and outputs.


setTrace

public void setTrace(boolean t)
Enable or disable trace.


setIncludeInputs

public void setIncludeInputs(boolean b)
Set a flag that indicates that original input values are to be included in the output values.


setIncludeUnknowns

public void setIncludeUnknowns(boolean b)
Set a flag that indicates that any input values that do not correspond to Field names are to be passed through to the outputs.


setTolerateInvalid

public void setTolerateInvalid(boolean b)
Set a flag indicating that values that don't match their constraint list should be tolerated.


setMaxIterations

public void setMaxIterations(int i)
Set the maximum number of iterations we will perform during form expansion.


setBaseContext

public void setBaseContext(java.lang.String bc)

clearVariables

public void clearVariables()

bindVariable

public void bindVariable(java.lang.String name,
                         java.lang.Object value)

setVariable

public void setVariable(java.lang.String name,
                        java.lang.Object value)
Should only be called if you have already called bindVariable and just want to change the current value. Used in loops.


unbindVariable

public void unbindVariable(java.lang.String name)

getOutputs

public java.util.Map getOutputs()
Return the output map.


getOutput

public java.lang.Object getOutput(java.lang.String name)
Get one output value.


isTolerateInvalid

public boolean isTolerateInvalid()

getInputs

protected java.util.Map getInputs()
Get the input variable map, exposed only for FieldIterator.


getForm

public Form getForm()
Get the Form, exposed only for FieldIterator. Also now used by Loader, though we could work around not having it.


iterate

public FieldIterator iterate()
                      throws WavesetException
Return an iterator for the Form.Field objects in the form. This will handle flattening of nested fields and loops.

Throws:
WavesetException

expandVariables

public java.lang.String expandVariables(java.lang.String src)
                                 throws WavesetException
Expand any variable references in a string. Currently necessary because the mechanics of handling are done outside.

VariableExpander takes a VariableResolver interface, which we implement.

Throws:
WavesetException

println

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

resolveIncludes

public void resolveIncludes()
                     throws WavesetException
Load libraries included by the form.

Throws:
WavesetException

resolve

public Form.Field resolve(Form.FieldRef ref)
                   throws WavesetException
Resolve a field reference.

Throws:
WavesetException

getField

public Form.Field getField(java.lang.String name)
                    throws WavesetException
Look up a field object, handling inclusions. // * Hmm, not sure if we should build an optimized search structure // * up front, or build it on the fly. Assuming that form libraries // * might be large and we may only reference a few things, lets // * do it on the fly.

Throws:
WavesetException

resolve

public Form resolve(Form.FormRef ref)
             throws WavesetException
Resolve a form reference.

Throws:
WavesetException

setInput

public void setInput(java.lang.String name,
                     java.lang.Object value)
Set an input value. Exposed in case you need to incrementally add things.


validate

public java.util.List validate()
                        throws WavesetException
Run form validation. Originally part of expansion, split out when we added support for validation expressions. This does two things, it checks for required fields, and runs validation expressions. We're assuming now that validation can be done before expansion, which means you can't use an expansion to satisfy a required field, or as an input into a validation function. Can we move confirmation checking in here? !! Should we try to determine ALL of the errors or do them one at a time?

Throws:
WavesetException

cycle

public void cycle(java.util.Map object)
           throws WavesetException
Convenience method to do a very common derive/expand cycle on a GenericObject.

Throws:
WavesetException

expand

public void expand()
            throws FormState.MissingRequiredField,
                   WavesetException
Run form expansion.

Throws:
FormState.MissingRequiredField
WavesetException

derive

public void derive()
            throws WavesetException
Iterate over form fields running Derivation and Default expressions. The two are almost always wanted so it saves an iteration doing them at the same time.

Derivation and Default are similar, but Default will not overwrite an existing non-null value, Derivation always overwrites.

Derivation expressions are typically used to calculate abstract attributes for display that may correspond to several physical attributes, or may be a transformation on the physical attribute. In such cases, there is usually a hidden field representing the physical attribute that uses an Expansion expression to generate its value from the derived values.

Throws:
WavesetException

setExternal

public void setExternal(java.lang.String name,
                        java.lang.Object value)
                 throws WavesetException
ExState method to assign an external variable. Too much similarity with resolveReference, factor it out.

Overrides:
setExternal in class ExState
Throws:
WavesetException

resolveReference

public java.lang.Object resolveReference(java.lang.String name)
                                  throws WavesetException
Resolve a reference from within a form expression.

We have three scopes, iteration variables, output variables and input variables. They are consulted in that order.

// We need to keep a bitmap of Field's whose defaults // have not yet been expanded so we can expand the defaults // dynamically!!

Overrides:
resolveReference in class ExState
Throws:
WavesetException

resolveVariable

public java.lang.Object resolveVariable(java.lang.String name)
                                 throws WavesetException
This is the VariableResolver interface method, called during the expansion of $(var) references. Usually this is used to reference loop iteration variables kept in the _variables map, but we'll also allow references to input & output field values.

Specified by:
resolveVariable in interface VariableResolver
Overrides:
resolveVariable in class ExState
Throws:
WavesetException

resolveCall

public java.lang.Object resolveCall(java.lang.String name,
                                    java.util.List arglist)
                             throws WavesetException
Resolve an external function call. We implement this as the evaluation of a Rule object. This is the original implementation that expects the argument to be either a Map or a list of String/Object pairs. You should be using now instead.

Overrides:
resolveCall in class ExState
Throws:
WavesetException

resolveRule

public java.lang.Object resolveRule(java.lang.String name,
                                    java.util.Map args)
                             throws WavesetException
Resolve a rule call. If we have been given a RuleExecutor, pass the request along to it, otherwise the default implementation is to get the rule out of the cache.

Overrides:
resolveRule in class ExState
Throws:
WavesetException

setFieldIterator

public void setFieldIterator(FieldIterator it)
This will be called as a side effect of the construction of a FieldIterator object so we have a circular reference. We need to be able to get to the iteration state in order to process base contexts and other things.


getFieldIterator

public FieldIterator getFieldIterator()

formCycleStart

public com.sun.idm.debugger.common.FormCycle formCycleStart(com.sun.idm.debugger.common.FormCycle.Phase phase)

formCycleStart

public com.sun.idm.debugger.common.FormCycle formCycleStart(com.sun.idm.debugger.common.FormCycle.Phase phase,
                                                            int iteration)

formCycleEnd

public void formCycleEnd(com.sun.idm.debugger.common.FormCycle cycle)

createBreakpointContext

protected ExState.ExBreakpointContext createBreakpointContext()
Override createBreakpointContext to create a FormBreakpointContext instead.

Overrides:
createBreakpointContext in class ExState