Package org.javarosa.core.model
Class FormDef
java.lang.Object
org.javarosa.core.model.FormDef
- All Implemented Interfaces:
ActionController.ActionResultProcessor,IFormElement,Localizable,IMetaData,Persistable,Externalizable
public class FormDef extends Object implements IFormElement, Localizable, Persistable, IMetaData, ActionController.ActionResultProcessor
Definition of a form. This has some meta data about the form definition and a
collection of groups together with question branching or skipping rules.
- Author:
- Daniel Kayiwa, Drew Roos
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classFormDef.EvalBehavior -
Field Summary
Fields Modifier and Type Field Description static FormDef.EvalBehaviorrecommendedModestatic StringSTORAGE_KEYstatic intTEMPLATING_RECURSION_LIMIT -
Constructor Summary
Constructors Constructor Description FormDef()FormDef(FormDef.EvalBehavior mode, EventNotifier eventNotifier) -
Method Summary
Modifier and Type Method Description voidaddChild(IFormElement fe)voidaddNonMainInstance(DataInstance instance)Getters and setters for the listsvoidaddParseError(String error)voidaddParseWarning(String warning)voidaddSubmissionProfile(String submissionId, SubmissionProfile profile)TriggerableaddTriggerable(Triggerable t)Adds a Condition to the form's Collection.voidattachControlsToInstanceData()Links a deserialized instance back up with its parent FormDef.FormIndexbuildIndex(List<Integer> indexes, List<Integer> multiplicities, List<IFormElement> elements)booleancanCreateRepeat(TreeReference repeatRef, FormIndex repeatIndex)voidcollapseIndex(FormIndex index, List<Integer> indexes, List<Integer> multiplicities, List<IFormElement> elements)voidcopyItemsetAnswer(QuestionDef q, TreeElement targetNode, IAnswerData data, boolean midSurvey)voidcreateNewRepeat(FormIndex index)FormIndexdeleteRepeat(FormIndex index)Deletes the inner-most repeat that this node belongs to and returns the corresponding FormIndex.FormIndexdescendIntoRepeat(FormIndex index, int repIndex)booleanevaluateConstraint(TreeReference ref, IAnswerData data)List<IFormElement>explodeIndex(FormIndex index)Dereference the form index and return a List of all interstitial nodes (top-level parent first; index target last)StringfillTemplateString(String template, TreeReference contextRef)StringfillTemplateString(String template, TreeReference contextRef, HashMap<String,?> variables)voidfinalizeTriggerables()Finalizes the DAG associated with the form's triggered conditions.static QuestionDeffindQuestionByRef(TreeReference ref, IFormElement fe)Traverses recursively the givenIFormElementnode tree and returns the firstQuestionDefthat matches the binding defined in the givenTreeReference.voidfireEvent()static IDataReferencegetAbsRef(IDataReference ref, TreeReference parentRef)Takes a (possibly relative) reference, and makes it absolute based on its parent.ActionControllergetActionController()StringgetAdditionalAttribute(String namespace, String name)Retrieve the value of an additional attribute on a Question or GroupList<TreeElement>getAdditionalAttributes()Retrieve all additional attributes on a Question or GroupStringgetAppearanceAttr()Appearance isn't a valid attribute for form, but this method must be included as a result of conforming to the IFormElement interface.IDataReferencegetBind()IFormElementgetChild(int i)IFormElementgetChild(FormIndex index)TreeReferencegetChildInstanceRef(List<IFormElement> elements, List<Integer> multiplicities)TreeReferencegetChildInstanceRef(FormIndex index)Finds the instance node a reference refers to (factoring in multiplicities)List<IFormElement>getChildren()IConditionExprgetConditionExpressionForTrueAction(TreeElement instanceNode, int action)Pull this in from FormOverview so that we can make fields private.intgetDeepChildCount()EvaluationContextgetEvaluationContext()EventNotifiergetEventNotifier()<X extends XFormExtension>
XgetExtension(Class<X> extension)HashMap<String,DataInstance>getFormInstances()intgetID()FormInstancegetInstance()StringgetLabelInnerText()Not applicable here.LocalizergetLocalizer()FormInstancegetMainInstance()HashMap<String,Object>getMetaData()StringgetMetaData(String fieldName)String[]getMetaDataFields()StringgetName()DataInstancegetNonMainInstance(String name)Get an instance based on a nameEnumeration<DataInstance>getNonMainInstances()intgetNumRepetitions(FormIndex index)List<IConditionExpr>getOutputFragments()List<String>getParseErrors()List<String>getParseWarnings()QuestionPreloadergetPreloader()SubmissionProfilegetSubmissionProfile()StringgetTextID()Not applicableStringgetTitle()booleanhasAction(String name)Returns true if this form definition includes one or more action of the given name.voidinitialize(boolean newInstance, InstanceInitializationFactory factory)meant to be called after deserialization and initialization of handlersbooleanisRepeatRelevant(TreeReference repeatRef)voidlocaleChanged(String locale, Localizer localizer)Updates the current object with the locate given.static booleanobjectEquals(Object object1, Object object2)Copied from commons-lang 2.6: For reviewing purposes only.voidpopulateDynamicChoices(ItemsetBinding itemset, TreeReference curQRef)Identifies theitemsetin the backend model, and creates a set ofSelectChoiceobjects at the current question reference based on the data in the model.booleanpostProcessInstance()voidpreloadInstance(TreeElement node)Preloads the Data Model with the preload values that are enumerated in the data bindings.voidprintTriggerables(String path)For debuggingvoidprocessResultOfAction(TreeReference refSetByAction, String event)voidreadExternal(DataInputStream dis, PrototypeFactory pf)Reads the form definition object from the supplied stream.voidregisterAction(String actionName)Records that the form definition includes an action of the given name.voidregisterElementWithActionTriggeredByToplevelEvent(IFormElement element)Records that this question or group has a nested action triggered by a top-level event so that the action can be triggered without having to traverse all elements.voidregisterStateObserver(FormElementStateListener qsl)Registers a state observer for this element.voidreportDependencyCycles()Reports any dependency cycles based upon the triggerIndex array.voidseal()Frees all of the components of this form which are no longer needed once it is completed.voidsetAdditionalAttribute(String namespace, String name, String value)Capture additional attributes on a Question or GroupvoidsetAnswer(IAnswerData data, TreeElement node)voidsetAnswer(IAnswerData data, TreeReference ref)voidsetAppearanceAttr(String appearanceAttr)Appearance isn't a valid attribute for form, but this method must be included as a result of conforming to the IFormElement interface.voidsetChildren(List<IFormElement> children)static voidsetDefaultEventNotifier(EventNotifier eventNotifier)voidsetDefaultSubmission(SubmissionProfile profile)static voidsetEvalBehavior(FormDef.EvalBehavior mode)Changes the mode used for evaluationsvoidsetEventNotifier(EventNotifier eventNotifier)voidsetFormXmlPath(String formXmlPath)voidsetID(int id)voidsetInstance(FormInstance fi)voidsetLocalizer(Localizer l)voidsetName(String name)voidsetOutputFragments(List<IConditionExpr> outputFragments)voidsetPreloader(QuestionPreloader preloads)voidsetTextID(String textID)Not applicablevoidsetTitle(String title)voidsetValue(IAnswerData data, TreeReference ref, boolean midSurvey)voidsetValue(IAnswerData data, TreeReference ref, TreeElement node, boolean midSurvey)StringtoString()Collection<QuickTriggerable>triggerTriggerables(TreeReference ref, boolean midSurvey)The entry point for the DAG cascade after a value is changed in the model.voidunregisterStateObserver(FormElementStateListener qsl)Unregisters a state observer for this element.static voidupdateItemsetReferences(List<IFormElement> children)Recursively traverses the main instance and initializes any questions with dynamic ItemsetBindings.ValidateOutcomevalidate(boolean markCompleted)voidwriteExternal(DataOutputStream dos)Writes the form definition object to the supplied stream.
-
Field Details
-
STORAGE_KEY
- See Also:
- Constant Field Values
-
TEMPLATING_RECURSION_LIMIT
public static final int TEMPLATING_RECURSION_LIMIT- See Also:
- Constant Field Values
-
recommendedMode
-
-
Constructor Details
-
Method Details
-
setEvalBehavior
Changes the mode used for evaluations -
setDefaultEventNotifier
-
getAbsRef
Takes a (possibly relative) reference, and makes it absolute based on its parent. Moved from the parser to this class so it can be used more cleanly by ItemsetBinding. -
getEventNotifier
-
setEventNotifier
-
addNonMainInstance
Getters and setters for the lists -
setFormXmlPath
-
getNonMainInstance
Get an instance based on a name- Parameters:
name- string name- Returns:
-
getNonMainInstances
-
setInstance
-
getMainInstance
-
getInstance
-
fireEvent
public void fireEvent() -
addChild
- Specified by:
addChildin interfaceIFormElement- Parameters:
fe- The child element to be added
-
getChild
- Specified by:
getChildin interfaceIFormElement
-
getChild
-
explodeIndex
Dereference the form index and return a List of all interstitial nodes (top-level parent first; index target last) Ignore 'new-repeat' node for now; just return/stop at ref to yet-to-be-created repeat node (similar to repeats that already exist)- Parameters:
index-- Returns:
-
getChildInstanceRef
Finds the instance node a reference refers to (factoring in multiplicities) -
getChildInstanceRef
public TreeReference getChildInstanceRef(List<IFormElement> elements, List<Integer> multiplicities) -
setLocalizer
-
getBind
- Specified by:
getBindin interfaceIFormElement- Returns:
- The data reference for this element
-
setValue
-
setValue
-
objectEquals
Copied from commons-lang 2.6: For reviewing purposes only.Compares two objects for equality, where either one or both objects may be
null.ObjectUtils.equals(null, null) = true ObjectUtils.equals(null, "") = false ObjectUtils.equals("", null) = false ObjectUtils.equals("", "") = true ObjectUtils.equals(Boolean.TRUE, null) = false ObjectUtils.equals(Boolean.TRUE, "true") = false ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false- Parameters:
object1- the first object, may benullobject2- the second object, may benull- Returns:
trueif the values of both objects are the same
-
setAnswer
-
setAnswer
-
deleteRepeat
Deletes the inner-most repeat that this node belongs to and returns the corresponding FormIndex. Behavior is currently undefined if you call this method on a node that is not contained within a repeat.- Parameters:
index-- Returns:
-
createNewRepeat
- Throws:
InvalidReferenceException
-
processResultOfAction
- Specified by:
processResultOfActionin interfaceActionController.ActionResultProcessor- Parameters:
refSetByAction- - the ref that this action targetedevent- - the event that triggered this action
-
isRepeatRelevant
-
canCreateRepeat
-
copyItemsetAnswer
public void copyItemsetAnswer(QuestionDef q, TreeElement targetNode, IAnswerData data, boolean midSurvey) throws InvalidReferenceException- Throws:
InvalidReferenceException
-
addTriggerable
Adds a Condition to the form's Collection.- Parameters:
t- the condition to be set
-
reportDependencyCycles
public void reportDependencyCycles()Reports any dependency cycles based upon the triggerIndex array. (Does not require that the DAG be finalized). -
finalizeTriggerables
Finalizes the DAG associated with the form's triggered conditions. This will create the appropriate ordering and dependencies to ensure the conditions will be evaluated in the appropriate orders.- Throws:
IllegalStateException- - If the trigger ordering contains an illegal cycle and the triggers can't be laid out appropriately
-
triggerTriggerables
The entry point for the DAG cascade after a value is changed in the model.- Parameters:
ref- The full contextualized unambiguous reference of the value that was changed.
-
validate
-
evaluateConstraint
-
getEvaluationContext
-
fillTemplateString
-
fillTemplateString
public String fillTemplateString(String template, TreeReference contextRef, HashMap<String,?> variables) -
populateDynamicChoices
Identifies theitemsetin the backend model, and creates a set ofSelectChoiceobjects at the current question reference based on the data in the model. Modifies theitemsetobject passed by clearing any choices currently on it, and populating with choices based on the question referencecurQRefthat was passed.- Parameters:
itemset- the binding for an itemset, where the choices will be populatedcurQRef- a reference to the current question's element, which will be used to determine the values to be chosen from
-
getPreloader
-
setPreloader
-
localeChanged
Description copied from interface:LocalizableUpdates the current object with the locate given.- Specified by:
localeChangedin interfaceLocalizable
-
toString
-
preloadInstance
Preloads the Data Model with the preload values that are enumerated in the data bindings. -
postProcessInstance
public boolean postProcessInstance() -
readExternal
public void readExternal(DataInputStream dis, PrototypeFactory pf) throws IOException, DeserializationExceptionReads the form definition object from the supplied stream. Requires that the instance has been set to a prototype of the instance that should be used for deserialization.- Specified by:
readExternalin interfaceExternalizable- Parameters:
dis- - the stream to read from- Throws:
IOExceptionInstantiationExceptionIllegalAccessExceptionDeserializationException
-
initialize
meant to be called after deserialization and initialization of handlers- Parameters:
newInstance- true if the form is to be used for a new entry interaction, false if it is using an existing IDataModel
-
writeExternal
Writes the form definition object to the supplied stream.- Specified by:
writeExternalin interfaceExternalizable- Parameters:
dos- - the stream to write to- Throws:
IOException
-
collapseIndex
-
buildIndex
-
getNumRepetitions
-
descendIntoRepeat
-
getDeepChildCount
public int getDeepChildCount()- Specified by:
getDeepChildCountin interfaceIFormElement- Returns:
- A recursive count of how many elements are ancestors of this element.
-
registerStateObserver
Description copied from interface:IFormElementRegisters a state observer for this element.- Specified by:
registerStateObserverin interfaceIFormElement
-
unregisterStateObserver
Description copied from interface:IFormElementUnregisters a state observer for this element.- Specified by:
unregisterStateObserverin interfaceIFormElement
-
getChildren
- Specified by:
getChildrenin interfaceIFormElement- Returns:
- A List containing any children that this element might have. Null if the element is not able to have child elements.
-
setChildren
- Specified by:
setChildrenin interfaceIFormElement- Parameters:
children- the children of this element, if it is capable of having child elements.
-
getTitle
-
setTitle
-
getID
public int getID()- Specified by:
getIDin interfaceIFormElement- Specified by:
getIDin interfacePersistable- Returns:
- The unique ID of this element
-
setID
public void setID(int id)- Specified by:
setIDin interfaceIFormElement- Specified by:
setIDin interfacePersistable- Parameters:
id- The new unique ID of this element
-
getName
-
setName
-
getLocalizer
-
getOutputFragments
-
setOutputFragments
-
getMetaData
- Specified by:
getMetaDatain interfaceIMetaData
-
getMetaData
- Specified by:
getMetaDatain interfaceIMetaData
-
getMetaDataFields
- Specified by:
getMetaDataFieldsin interfaceIMetaData
-
updateItemsetReferences
Recursively traverses the main instance and initializes any questions with dynamic ItemsetBindings. We need to do this late in the process so that we have the entire main instance assembled. -
attachControlsToInstanceData
public void attachControlsToInstanceData()Links a deserialized instance back up with its parent FormDef. This allows select/select1 questions to be internationalizable in chatterbox, and (if using CHOICE_INDEX mode) allows the instance to be serialized to XML. -
findQuestionByRef
Traverses recursively the givenIFormElementnode tree and returns the firstQuestionDefthat matches the binding defined in the givenTreeReference.- Parameters:
ref- reference to a form bindingfe- the recursiveIFormElement. The starting call would typically receive aFormDef- Returns:
- the question definition,
nullif noQuestionDefmatches the given binding
-
getAppearanceAttr
Appearance isn't a valid attribute for form, but this method must be included as a result of conforming to the IFormElement interface.- Specified by:
getAppearanceAttrin interfaceIFormElement- Returns:
-
getActionController
- Specified by:
getActionControllerin interfaceIFormElement
-
setAppearanceAttr
Appearance isn't a valid attribute for form, but this method must be included as a result of conforming to the IFormElement interface.- Specified by:
setAppearanceAttrin interfaceIFormElement
-
getLabelInnerText
Not applicable here.- Specified by:
getLabelInnerTextin interfaceIFormElement- Returns:
- <label> innertext or null (if innertext is not present).
-
getTextID
Not applicable- Specified by:
getTextIDin interfaceIFormElement- Returns:
- the TextID (bare, no ;form appended to it!!)
-
setTextID
Not applicable- Specified by:
setTextIDin interfaceIFormElement- Parameters:
textID- the plain TextID WITHOUT any form specification (e.g. ;long)
-
setDefaultSubmission
-
addSubmissionProfile
-
getSubmissionProfile
-
setAdditionalAttribute
Description copied from interface:IFormElementCapture additional attributes on a Question or Group- Specified by:
setAdditionalAttributein interfaceIFormElement
-
getAdditionalAttribute
Description copied from interface:IFormElementRetrieve the value of an additional attribute on a Question or Group- Specified by:
getAdditionalAttributein interfaceIFormElement- Returns:
-
getAdditionalAttributes
Description copied from interface:IFormElementRetrieve all additional attributes on a Question or Group- Specified by:
getAdditionalAttributesin interfaceIFormElement- Returns:
-
getExtension
-
seal
public void seal()Frees all of the components of this form which are no longer needed once it is completed. Once this is called, the form is no longer capable of functioning, but all data should be retained. -
registerAction
Records that the form definition includes an action of the given name. Clients may need to configure resources accordingly or communicate something to the user (e.g. in the case of setgeopoint). -
hasAction
Returns true if this form definition includes one or more action of the given name. -
registerElementWithActionTriggeredByToplevelEvent
Records that this question or group has a nested action triggered by a top-level event so that the action can be triggered without having to traverse all elements. -
getConditionExpressionForTrueAction
Pull this in from FormOverview so that we can make fields private.- Parameters:
instanceNode-action-- Returns:
-
printTriggerables
For debugging -
getParseWarnings
-
getParseErrors
-
addParseWarning
-
addParseError
-
getFormInstances
-