Community articledereferenceEx method (Streaming API)
Added by IBM contributorIBM on July 26, 2013
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars


Use this function to locate a particular FormNodeP 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.


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


Table 1. Method parameters
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_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.
theNSNodeFormNodePA node that is used to resolve the namespaces in theReference parameter (see the note about namespace). Use null if the node that this method is operating on has inherited the necessary namespaces.


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.


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 will fail.
  3. dereferenceEx does not support the XForms scheme.
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: 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">
   <field sid="Field1" xmlns:processing="URI">

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)


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

Parent topic:
FormNodeP class