com.adobe.xfa.form
Class FormModel

java.lang.Object
  com.adobe.xfa.Obj
      com.adobe.xfa.Node
          com.adobe.xfa.Element
              com.adobe.xfa.Model
                  com.adobe.xfa.form.FormModel

public class FormModel
extends Model

A class to represent the result of joining a template and data.

Nested Class Summary

static interface	FormModel.PostMergeHandler Defines the callback interface that will be invoked immediately after a merge but before any initialize events are fired.
static class	FormModel.Validate A base class that an implementation can derive from to interact with the form validation process.

Nested classes/interfaces inherited from class com.adobe.xfa.Node

Node.ChangeLogger

Field Summary

Fields inherited from class com.adobe.xfa.Node

CREATE_ALWAYS_NEW, CREATE_IF_NOT_EXIST, CREATE_MUST_NOT_EXIST, CREATE_REPLACE

Method Summary

boolean	eventOccurred(java.lang.String sActivity, Obj container) Notifies event listeners that an event has occurred on a container.
boolean	getAdjustData() Determines whether the next FormModel.remerge() operation will adjust the structure of the DataModel to match the TemplateModel.
boolean	getCalculationsEnabled() Determines if calculations are enabled.
FormModel.Validate	getDefaultValidate() Gets the default Validate object.
static FormModel	getFormModel(AppModel appModel, boolean bCreateIfNotFound) Returns the FormModel held within the AppModel.
boolean	getFormStateRemoved() Determines if the formState packet has been removed.
java.lang.String	getFriendlyName(Element formNode) Gets the friendly name (to use in user-facing communication) for a form node
FormModel.PostMergeHandler	getPostMergeHandler() Gets the callback method that is to be invoked after merge but before any initialization scripts are run.
int	getRunScripts() Gets the runAt property that specifies where scripts should be executed (client, server or both).
boolean	getValidationsEnabled() Determines whether validations are enabled.
boolean	initialize() Fires the initialize event on all containers on the form, and fires the indexChange event on all subforms.
void	merge(boolean bEmptyMerge, boolean bAdjustData, boolean bInitialize, boolean bRestoreDeltas, boolean bForceRestore) Merges the TemplateModel and the DataModel to create the FormModel.
boolean	recalculate(boolean bFullRecalculate, FormModel.Validate validate, boolean bIgnoreCalcEnabledFlag) Executes calculation and validation scripts.
void	remerge() Forces the remerging of the DataModel and TemplateModel to recreate this FormModel.
void	reset() Resets this FormModel to its initial state.
void	resetData(Obj container) Resets a container to its template default value.
void	setAdjustData(boolean bAdjustData) Sets whether the next FormModel.remerge() operation will adjust the structure of the DataModel to match the structure of the TemplateModel.
void	setDefaultValidate(FormModel.Validate validate) Sets the default Validate.
void	setEmptyMerge(boolean bEmptyMerge) Sets whether the next FormModel.remerge() operation will do an empty merge.
void	setExcludedActivities(java.lang.String sExclude) Sets event activites that are to be excluded from execution.
void	setPostMergeHandler(FormModel.PostMergeHandler handler, java.lang.Object clientData) Sets the callback method that is to be invoked after merge but before any initialize scripts are run.
void	setRunScripts(int eRunAtSetting) Sets the runAt property that specifies where scripts should be executed (client, server or both).

Methods inherited from class com.adobe.xfa.Model

clearErrorList, createElement, createElement, createElement, createTextNode, getCurrentVersion, getDocument, getErrorContextList, getErrorList, normalizeNameSpaces, resolveNodes

Methods inherited from class com.adobe.xfa.Element

appendChild, assignNode, getAttr, getAttribute, getElement, getFirstXFAChild, getFirstXMLChild, getInstalledLocale, getLastXMLChild, getModel, getName, getNodes, getNS, getNumAttrs, getPrefix, getText, getXFAChild, getXMLChild, isInstalledLocaleAmbient, loadXML, saveXML, setAttribute, setAttribute, setAttribute, setLocalName, setName, setNS, setQName

Methods inherited from class com.adobe.xfa.Node

checkAncestorPerms, checkDescendentPerms, checkPerms, cleanDirtyFlags, compareVersions, getData, getDynamicScriptProp, getNextXFASibling, getNextXMLSibling, getOwnerDocument, getPreviousXMLSibling, getSOMExpression, getXFAChildCount, getXFAParent, getXMLChildCount, getXMLParent, hasChanged, remove, resolveNode, resolveNode, resolveNodes, setNextXMLSibling, setPermsLock, setXMLParent

Methods inherited from class java.lang.Object

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

Method Detail

getFormModel

public static FormModel getFormModel(AppModel appModel,
                                     boolean bCreateIfNotFound)

Returns the FormModel held within the AppModel.

Parameters:

appModel - the AppModel to search

bCreateIfNotFound - if true, and the FormModel does not exist, then one will be created and returned; if false and the FormModel does not exist, null is returned

Returns:

the FormModel contained within appModel; null if not found and bCreateIfNotFound is false.

eventOccurred

public boolean eventOccurred(java.lang.String sActivity,
                             Obj container)

Notifies event listeners that an event has occurred on a container. This method may fire additional events before and/or after firing the event.

Parameters:

sActivity - the name of the event

container - the container on which the event occurs

Returns:

true if one or more events were dispatched.

getAdjustData

public boolean getAdjustData()

Determines whether the next FormModel.remerge() operation will adjust the structure of the DataModel to match the TemplateModel. The default value is false.

Returns:

true if the next FormModel.remerge() operation will adjust the structure of the DataModel to match the TemplateModel.

See Also:

FormModel.remerge(), FormModel.setAdjustData(boolean)

getCalculationsEnabled

public boolean getCalculationsEnabled()

Determines if calculations are enabled.

Returns:

true if calculations are enabled.

getDefaultValidate

public FormModel.Validate getDefaultValidate()

Gets the default Validate object. The default Validate object is used whenever validation is initiated by some method that does not use a Validate parameter, or when validation is initiated by FormModel.validate(Validate, Element, boolean, boolean) or FormModel.recalculate(boolean, Validate, boolean) and null is passed to the validate parameter. For example, the default Validate object is used when validation is initiated by the execValidate scripting method of the FormModel.

Returns:

a reference to an object derived from Validate, or null if no default Validate object has been set.

See Also:

FormModel.setDefaultValidate(Validate), FormModel.validate(Validate, Element, boolean, boolean), FormModel.recalculate(boolean, Validate, boolean)

getFormStateRemoved

public boolean getFormStateRemoved()

Determines if the formState packet has been removed.

Returns:

true if the formState packet has been removed

getFriendlyName

public java.lang.String getFriendlyName(Element formNode)

Gets the friendly name (to use in user-facing communication) for a form node

Parameters:

formNode - a FormSubform, FormField or FormExclGroup to get a user-friendly name for.

Returns:

a string containing a user-friendly name for the form node.

getPostMergeHandler

public FormModel.PostMergeHandler getPostMergeHandler()

Gets the callback method that is to be invoked after merge but before any initialization scripts are run.

See Also:

FormModel.setPostMergeHandler(PostMergeHandler, Object)

getRunScripts

public int getRunScripts()

Gets the runAt property that specifies where scripts should be executed (client, server or both). The default is both.

Returns:

one of: EnumAttr.RUNSCRIPTS_CLIENT, EnumAttr.RUNSCRIPTS_SERVER, EnumAttr.RUNSCRIPTS_BOTH or EnumAttr.RUNSCRIPTS_NONE

See Also:

FormModel.setRunScripts(int)

getValidationsEnabled

public boolean getValidationsEnabled()

Determines whether validations are enabled.

Returns:

true if validations are enabled.

initialize

public boolean initialize()

Fires the initialize event on all containers on the form, and fires the indexChange event on all subforms.

Returns:

true if one or more events were dispatched.

merge

public void merge(boolean bEmptyMerge,
                  boolean bAdjustData,
                  boolean bInitialize,
                  boolean bRestoreDeltas,
                  boolean bForceRestore)

Merges the TemplateModel and the DataModel to create the FormModel. The first two parameters are implicitly used to call FormModel.setEmptyMerge(boolean) and FormModel.setAdjustData(boolean) respectively.

Parameters:

bEmptyMerge - if true then merge against an empty DataModel, if false use the DataModel found in the AppModel

bAdjustData - if true adjust the structure of the DataModel to match the structure of the TemplateModel; if false don't modify the DataModel.

bInitialize - if true all the initialize events will be fired; if false no initialization is performed

bRestoreDeltas - if true and if the restoreState property on the form's root subform is "auto" (the default is "manual"), all deltas are restored from the form packet. The locale attribute is always restored from the form packet, regardless of the value of this parameter.

bForceRestore - if true, restore the state regardless of the the restoreState property on the form's root subform.

recalculate

public boolean recalculate(boolean bFullRecalculate,
                           FormModel.Validate validate,
                           boolean bIgnoreCalcEnabledFlag)

Executes calculation and validation scripts. After a merge operation, a full recalculate must be done to ensure that all calculations and validations are done using current data values. If data values are changed, this should be called to re-run the calculations.

The FormModel tracks changes to data values, so recalculation efficiency can be improved by setting the bFullRecalculate parameter to false to perform only those calculations and validations that are dependent on the changed data values.

Parameters:

bFullRecalculate - if true all calculations and validations are run. If false calculations and validations are run as needed (i.e. if values that the validate or calculate script are dependent on have changed since the last recalculate).

validate - an object derived from Validate. If null the default Validate is used, and if the default Validate is also null, no validations are performed.

bIgnoreCalcEnabledFlag - if true the calculations will be performed even if they are disabled on the host.

Returns:

true if any calculations were performed

See Also:

FormModel.setDefaultValidate(Validate), FormModel.getDefaultValidate()

remerge

public void remerge()

Forces the remerging of the DataModel and TemplateModel to recreate this FormModel. This is equivalent to calling FormModel.merge(boolean, boolean, boolean, boolean, boolean), and specifying FormModel.getEmptyMerge() and FormModel.getAdjustData() for the bEmptyMerge and bAdjustData parameters, and specifying true, false, false for the bInitialize, bRestoreDeltas and bForceRestore parameters.

See Also:

FormModel.merge(boolean, boolean, boolean, boolean, boolean), FormModel.getAdjustData(), FormModel.setAdjustData(boolean), FormModel.getEmptyMerge(), FormModel.setEmptyMerge(boolean)

reset

public void reset()

Resets this FormModel to its initial state. All children are removed.

resetData

public void resetData(Obj container)

Resets a container to its template default value. If container is a field it will reset it. If container is a subform it will recursively reset all the containers it contains. If container is null then it will reset the root subform, and therefore all fields in the form.

Parameters:

container - the container to be reset

setAdjustData

public void setAdjustData(boolean bAdjustData)

Sets whether the next FormModel.remerge() operation will adjust the structure of the DataModel to match the structure of the TemplateModel.

Parameters:

bAdjustData - if true the next FormModel.remerge() operation will adjust the structure of the DataModel to match the structure of the TemplateModel.

See Also:

FormModel.getAdjustData(), FormModel.remerge(), FormModel.merge(boolean, boolean, boolean, boolean, boolean)

setDefaultValidate

public void setDefaultValidate(FormModel.Validate validate)

Sets the default Validate. The default Validate is used during validation when validation is initiated by some method other than FormModel.recalculate(boolean, Validate, boolean) or FormModel.validate(Validate, Element, boolean, boolean), or when validate or recalculate are called and null is passed to the validate parameter. If no Validate instance is available, then no validations are performed.

Parameters:

validate - a reference to an object derived from Validate.

See Also:

FormModel.getDefaultValidate()

setEmptyMerge

public void setEmptyMerge(boolean bEmptyMerge)

Sets whether the next FormModel.remerge() operation will do an empty merge. This property is also set implicity from the first parameter of any call to FormModel.merge(boolean, boolean, boolean, boolean, boolean).

See Also:

FormModel.merge(boolean, boolean, boolean, boolean, boolean), FormModel.remerge(), FormModel.getEmptyMerge()

setExcludedActivities

public void setExcludedActivities(java.lang.String sExclude)

Sets event activites that are to be excluded from execution.

Parameters:

sExclude - a space-delimited list of activities.

setPostMergeHandler

public void setPostMergeHandler(FormModel.PostMergeHandler handler,
                                java.lang.Object clientData)

Sets the callback method that is to be invoked after merge but before any initialize scripts are run.

Parameters:

handler - the PostMergeHandler implementation to be invoked after merge but before any initialize scripts are run.

clientData - this value will be passed as the parameter to FormModel.PostMergeHandler.handlePostMerge(Object) when the callback method is invoked.

See Also:

FormModel.getPostMergeHandler()

setRunScripts

public void setRunScripts(int eRunAtSetting)

Sets the runAt property that specifies where scripts should be executed (client, server or both). The default is both.

Parameters:

eRunAtSetting - one of: EnumAttr.RUNSCRIPTS_CLIENT, EnumAttr.RUNSCRIPTS_SERVER, EnumAttr.RUNSCRIPTS_BOTH or EnumAttr.RUNSCRIPTS_NONE

See Also:

FormModel.getRunScripts()