FormIndex (javarosa 4.3.0 API)

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 Summary

Constructors
Constructor and Description
`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.
`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.
`FormIndex(FormIndex nextLevel, int localIndex, TreeReference reference)` Constructs a @{code FormIndex} for a node that has children.
`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.
`FormIndex(int localIndex, TreeReference reference)` Constructs a @{code FormIndex} for a node that does not have any children.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`assignRefs(FormDef f)`
`int`	`compareTo(Object o)`
`static FormIndex`	`createBeginningOfFormIndex()` Returns an index before the start of the form
`static FormIndex`	`createEndOfFormIndex()` Returns an index after the end of the form
`FormIndex`	`diff(FormIndex subIndex)` Takes in a form index which is a subset of this index, and returns the total difference between them.
`boolean`	`equals(Object o)`
`int`	`getDepth()`
`int`	`getElementMultiplicity()` For the fully qualified element, get the multiplicity of the element's reference
`int`	`getInstanceIndex()`
`int`	`getLocalIndex()`
`TreeReference`	`getLocalReference()`
`FormIndex`	`getNextLevel()`
`FormIndex`	`getPreviousLevel()`
`TreeReference`	`getReference()`
`FormIndex`	`getTerminal()`
`int`	`hashCode()`
`boolean`	`isBeginningOfFormIndex()`
`boolean`	`isEndOfFormIndex()`
`boolean`	`isInForm()`
`static boolean`	`isSubElement(FormIndex parent, FormIndex child)`
`static boolean`	`isSubIndex(FormIndex parent, FormIndex child)`
`boolean`	`isTerminal()` Identifies whether this is a terminal index, in other words whether this index references with more specificity than the current context
`FormIndex`	`snip()`
`String`	`toString()`
`static FormIndex`	`trimNegativeIndices(FormIndex index)` Trims any negative indices from the end of the passed in index.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - 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 Detail
  - 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)
```
  - getPreviousLevel
```
public FormIndex getPreviousLevel()
```
    Returns:
    
    An index into the previous level of specificity from this index. Could also be described as returning the index representing the parent element of this index

Class FormIndex

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FormIndex

FormIndex

FormIndex

FormIndex

FormIndex

Method Detail

createBeginningOfFormIndex

createEndOfFormIndex

isInForm

getLocalIndex

getInstanceIndex

getElementMultiplicity

getNextLevel

getLocalReference

getReference

getTerminal

isTerminal

isEndOfFormIndex

isBeginningOfFormIndex

equals

hashCode

compareTo

snip

diff

toString

getDepth

trimNegativeIndices

isSubIndex

isSubElement

assignRefs

getPreviousLevel