Package org.javarosa.core.model

Class FormIndex

java.lang.Object
org.javarosa.core.model.FormIndex
All Implemented Interfaces:
Serializable
public class FormIndex
extends Object
implements Serializable
FormIndex is an immutable index which is structured to provide quick access to a specific node in a FormDef (tree of IFormElement representing a blank form) or a FormInstance (tree of TreeElement representing a form instance that can be filled). It also includes a TreeReference representing the XPath path of that node. The XML node referred to by a FormIndex can correspond to either a question or a group. The index is constructed as a linked list of levels. A FormIndex can refer to: - a node at the top level of the form (only localIndex is used) - a node nested in a group hierarchy (localIndex and nextLevel are used) - a node nested in a repeat (localIndex, nextLevel and instanceIndex are all used) When a FormIndex list refers to a nested node, that root FormIndex represents the path root and links to subsequent levels using the nextLevel field. The @{link #getReference} method returns the reference of the FormIndex at the end of the list. Consider the following instance from a blank form with friends as a repeat group and school_info as a non-repeat group: 

  <instance>
    <data id="my_form">
      <address/>
      <dob/>
      <school_info>
        <favorite_class/>
        <favorite_teacher/>
      </school_info>
      <friends>
        <firstname/>
      </friends>
    </data>
  </instance>
 </pre>

 The dob question's path is /data/dob. The index that refers to it has a localIndex of 1.

 The friends group's path is /data/friends. The index that refers to it has a localIndex of 3.

 The favorite_teacher question's path is /data/school_info/favorite_teacher. The index that refers to
 it has a localIndex of 2 which is school_info's index at the form root. It also has a
 nextLevel set which itself has a localIndex of 1 because it is the second node in the school_info group.

 The firstname question's path is /data/friends[N]/firstname where @{N} is a 0-based index representing
 which of potentially several friends repeat group instances' firstname is desired (also referred to as
 multiplicity). Since friends is a repeat group, the filled instance can contain several instances of the
 friends node. The index that refers to it always starts with a localIndex of 3 which is
 friends's index at the form root. It also has an instanceIndex which represents which of the
 potentially several friends to use. To index a firstname node, a nextLevel is added which
 always has a @{code localIndex} of 0.

 To go from a FormIndex to a form element in a blank form, FormDef.getChild(FormIndex) can be used.
 To go from a FormIndex to a node in a filled form, 
 DataInstance.resolveReference(TreeReference) can
 be used along with getReference().

 No circularity is allowed. That is, no FormIndex's ancestor can be itself.

 Datatype Productions:
 FormIndex = BOF | EOF | CompoundIndex(nextIndex:FormIndex,Location)
 Location = Empty | Simple(localLevel:int) | WithMult(localLevel:int, multiplicity:int)
Author:
Clayton Sims
See Also:
Serialized Form

  • Constructor Details

    • FormIndex

      public FormIndex​(int localIndex, TreeReference reference)
      Constructs a @{code FormIndex} for a node that does not have any children.
      Parameters:
      localIndex - An integer index into a flat list of elements
      reference - A reference to the instance element identified by this index

    • FormIndex

      public FormIndex​(int localIndex, int instanceIndex, TreeReference reference)
      Constructs a @{code FormIndex} for a node that does not have any children but that may have repeat instances in a filled form. The instanceIndex identifies which of these instances should be referred to.
      Parameters:
      localIndex - An integer index into a flat list of elements
      instanceIndex - An integer index expressing the multiplicity of the current level
      reference - A reference to the instance element identified by this index

    • FormIndex

      public FormIndex​(FormIndex nextLevel, int localIndex, TreeReference reference)
      Constructs a @{code FormIndex} for a node that has children.
      Parameters:
      nextLevel - An index into the referenced element's index
      localIndex - An index to an element at the current level, a child element of which will be referenced by the nextLevel index.
      reference - A reference to the instance element identified by this index;

    • FormIndex

      public FormIndex​(FormIndex nextLevel, int localIndex, int instanceIndex, TreeReference reference)
      Constructs a @{code FormIndex} for a node that has children and that may have repeat instances in a filled form.
      Parameters:
      nextLevel - An index into the referenced element's index
      localIndex - An index to an element at the current level, a child element of which will be referenced by the nextLevel index.
      instanceIndex - How many times the element referenced has been repeated.
      reference - A reference to the instance element identified by this index;

    • FormIndex

      public FormIndex​(FormIndex nextLevel, FormIndex currentLevel)
      Constructs an index which references an element past the level of specificity of the current context, founded by the currentLevel index. (currentLevel, (nextLevel...))

  • Method Details

    • createBeginningOfFormIndex

      public static FormIndex createBeginningOfFormIndex()
      Returns an index before the start of the form

    • createEndOfFormIndex

      public static FormIndex createEndOfFormIndex()
      Returns an index after the end of the form

    • isInForm

      public boolean isInForm()
      Returns:
      true if the index is neither before the start or after the end of the form

    • getLocalIndex

      public int getLocalIndex()
      Returns:
      The index of the element in the current context

    • getInstanceIndex

      public int getInstanceIndex()
      Returns:
      The multiplicity of the current instance of a repeated question or group

    • getElementMultiplicity

      public int getElementMultiplicity()
      For the fully qualified element, get the multiplicity of the element's reference
      Returns:
      The terminal element (fully qualified)'s instance index

    • getNextLevel

      public FormIndex getNextLevel()
      Returns:
      An index into the next level of specificity past the current context. An example would be an index into an element that is a child of the element referenced by the local index.

    • getLocalReference

      public TreeReference getLocalReference()

    • getReference

      public TreeReference getReference()
      Returns:
      The TreeReference of the fully qualified element described by this FormIndex.

    • getTerminal

      public FormIndex getTerminal()

    • isTerminal

      public boolean isTerminal()
      Identifies whether this is a terminal index, in other words whether this index references with more specificity than the current context

    • isEndOfFormIndex

      public boolean isEndOfFormIndex()
      Returns:
      true if we are after the end of the form

    • isBeginningOfFormIndex

      public boolean isBeginningOfFormIndex()
      Returns:
      true if we are before the start of the form

    • equals

      public boolean equals​(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • compareTo

      public int compareTo​(Object o)

    • snip

      public FormIndex snip()
      Returns:
      Only the local component of this Form Index.

    • diff

      public FormIndex diff​(FormIndex subIndex)
      Takes in a form index which is a subset of this index, and returns the total difference between them. This is useful for stepping up the level of index specificty. If the subIndex is not a valid subIndex of this index, null is returned. Since the FormIndex represented by null is always a subset, if null is passed in as a subIndex, the full index is returned For example: Indices a = 1_0,2,1,3 b = 1,3 a.diff(b) = 1_0,2
      Parameters:
      subIndex -
      Returns:

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getDepth

      public int getDepth()
      Returns:
      the level of this index relative to the top level of the form

    • trimNegativeIndices

      public static FormIndex trimNegativeIndices​(FormIndex index)
      Trims any negative indices from the end of the passed in index.
      Parameters:
      index -
      Returns:

    • isSubIndex

      public static boolean isSubIndex​(FormIndex parent, FormIndex child)

    • isSubElement

      public static boolean isSubElement​(FormIndex parent, FormIndex child)

    • assignRefs

      public void assignRefs​(FormDef f)