Community articledereferenceEx method
Added by IBM contributorIBM on August 15, 2011
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

No abstract provided.



Description

Use this function to locate a particular FormNodeP, to locate a cell in a particular group, or to locate a data item in a particular datagroup. The node that this method operates on is used as the starting point of the search.
Note: It is not necessary to call this method when you are working with an XForms data model. The updateXFormsInstance and extractXFormsInstance methods perform this task automatically.

Method

   public FormNodeP dereferenceEx(
      String theScheme,
      String theReference,
      int theReferenceCode,
      int referenceType,
      FormNodeP theNSNode
   ) throws UWIException;


Parameters

Table 1. Method parameters
ExpressionTypeDescription
theSchemeStringReserved. This must be null.
theReferenceStringThe reference string.
theReferenceCodeintReserved. This must be 0.
referenceTypeintOne of the following constants:
FormNodeP.UFL_PAGE_REFERENCE— Indicates page level nodes. For example, PAGE1.
FormNodeP.UFL_ITEM_REFERENCE — Indicates item level nodes. For example, PAGE1.FIELD1.
FormNodeP.UFL_OPTION_REFERENCE — Indicates option level nodes. For example, PAGE1.FIELD1.itemlocation.
FormNodeP.UFL_ARRAY_REFERENCE — Indicates argument level nodes. For example, PAGE1.FIELD1.itemlocation[2].
FormNodeP.UFL_GROUP_REFERENCE — Indicates grouped nodes, such as radio button or checkbox groups. For example, PAGE1.group1.
FormNodeP.UFL_DATAGROUP_REFERENCE — Indicates a datagroup node, such as an attachment. For example, PAGE1.datagroup1.
If it is an option or argument reference, you can use bitwise OR ( | ) with one of:
FormNodeP.UFL_SEARCH — Searches for the requested node or returns null if the node is not found.
FormNodeP.UFL_SEARCH_AND_CREATE — Searches for the requested node or creates one if the node is not found.
If it is a group or datagroup reference, you can use bitwise OR ( | ) with one of:
FormNodeP.UFL_FIRST — Finds the first cell or data item in the group or datagroup.
FormNodeP.UFL_NEXT — Finds the next cell or data item in the group or datagroup.
FormNodeP.UFL_ARRAY_REFERENCE — Indicates argument level nodes. For example, PAGE1.FIELD1.itemlocation[2].
FormNodeP.UFL_GROUP_REFERENCE — Indicates grouped nodes, such as radio button or checkbox groups. For example, PAGE1.group1.
FormNodeP.UFL_DATAGROUP_REFERENCE — Indicates a datagroup node, such as an attachment. For example, PAGE1.datagroup1.
If it is an option or argument reference, you can use bitwise OR ( | ) with one of:
FormNodeP.UFL_SEARCH — Searches for the requested node or returns null if the node is not found.
FormNodeP.UFL_SEARCH_AND_CREATE — Searches for the requested node or creates one if the node is not found.
If it is a group or datagroup reference, you can use bitwise OR ( | ) with one of:
FormNodeP.UFL_FIRST — Finds the first cell or data item in the group or datagroup.
FormNodeP.UFL_NEXT — Finds the next cell or data item in the group or datagroup.
theNSNodeFormNodePA node that is used to resolve the namespaces in the theReference parameter (see the note about namespace below). Use null if the node that this method is operating on has inherited the necessary namespaces.


Returns

The FormNodeP defined by the reference string or null if the referenced node does not exist and UFL_SEARCH_AND_CREATE is not specified. On error, the function throws a UWIException object that describes the problem.

Notes

FormNodeP
Before you decide which FormNodeP to use this method on, be sure you understand the following:
  1. The FormNodeP supplied can never be more than one level in the hierarchy above the starting point of the reference string. For example, if the reference string begins with an option, then the FormNodeP can be no higher in the hierarchy than an item.
  2. If the FormNodeP is at the same level or lower in the hierarchy than the starting point of the reference string, the method will attempt to locate a common ancestor. The method will locate the ancestor of the FormNodeP that is one level in the hierarchy above the starting point of the reference string. The method will then attempt to follow the reference string back down through the hierarchy. If the reference string cannot be followed from the located ancestor (for example, if the ancestor is not common to both the FormNodeP and the reference string), the function will fail. For example, given a FormNodeP that represents field_1 and a reference of field_2, the function will access the page node above field_1, and will then try to locate field_2 below that node. If the two fields are not on the same page, the function fails.
  3. dereferenceEx does not support the XForms scheme.
Creating a reference string
For general information about creating a reference string, see About references .
Reference strings for groups or datagroups follow this format:
   page.group. or page.datagroup

In both cases, the page component is optional. It is only required if you want to search a different page than the one containing your reference node.
For example, to refer to the "State" group of cells on PAGE1 of the form, use:
   PAGE1.State

Locating cells or data items
If you want to locate a cell or a data item, you must perform a bitwise OR with UFL_FIRST or UFL_NEXT. UFL_FIRST will locate the first cell or data item in the page. UFL_NEXT will locate the next cell or data item. This allows you to loop through all the cells or data item on a page until you have found the one you want.
Note that groups and datagroups are limited to a single page, and that your search will likewise be limited to a single page.
Creating a node
For an option or argument reference, you can have the library create a node that does not exist. To do so, perform a bitwise OR of UFL_SEARCH_AND_CREATE to the referenceType parameter; otherwise, perform a bitwise OR of UFL_SEARCH to the referenceType variable and the function will return null if the node does not exist.
Determining namespace
In some cases, you may want to use the dereferenceEx method to locate a node that does not have a globally defined namespace. For example, consider the following form:
   <label sid="Label1">
      <value>Field1.processing:myValue</value>
   </label>
   <field sid="Field1" xmlns:processing="URI">
      <value></value>
      <processing:myValue>10<processing:myValue>
   </field>

In this form, the processing namespace is declared in the Field1 node. Any elements within Field1 will understand that namespace; however, elements outside of the scope of Field1 will not.
In cases like this, you will often start your search at a node that does not understand the namespace of the node you are trying to locate. For example, you might want to locate the node referenced in the value of Label1. In this case, you would first locate the Label1 value node and get its literal. Then, from the Label1 value node, you would attempt to locate the processing:myValue node as shown:
   Label1Node.dereferenceEx(null, "Field1.processing:myValue", 0,
      FormNodeP.UFL_OPTION_REFERENCE, null)

In this example, the dereferenceEx method would fail. The method cannot properly resolve the processing namespace because this namespace is not defined for the Label1 value node. To correct this, you must also provide a node that understands the processing namespace (in this case, any node in the scope of Field1) as the last parameter in the method:
   Label1Node.dereferenceEx(null, "Field1.processing:myValue", 0,
      FormNodeP.UFL_OPTION_REFERENCE, Field1Node)


Example

The following sample code uses dereferenceEx to locate the node representing the field called colorfield. It then uses setLiteralByRef to change the value displayed by the field to Purple.
   private static void changeColorField(FormNodeP theForm) throws UWIException
   {
   FormNodeP tempNode;
 
      if ((tempNode = theForm.dereferenceEx(null, "PAGE1.COLORFIELD", 0,
         FormNodeP.UFL_ITEM_REFERENCE, null)) == null)
      {
         throw new UWIException("Could not locate COLORFIELD node.");
      } 
      tempNode.setLiteralByRefEx(null, "PAGE1.COLORFIELD.value", 0, 
         null, null, "Purple");
 
      /* additional code removed */
   }


Parent topic:
FormNodeP class