Community articlegetReferenceEx method
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


This method returns the reference string that identifies the node. For example, a value node might return a reference of Page1.Field1.value. The reference will either begin at the page level of the form or at a level specified by the caller.


   public String getReferenceEx(
      String theScheme,
      FormNodeP theNSNode,
      FormNodeP theStartPoint,
      boolean addNamespaces
  ) throws UWIException;


Table 1. Method parameters
theSchemeStringReserved. This must be null.
theNSNodeFormNodePA node that defines which namespace prefixes are used when constructing the reference. Only namespace prefixes that this node inherits are used. Use null if the node that this method is operating on has inherited the necessary namespaces.
theStartPointFormNodePA node that determines the starting point of the reference. This node must be a parent of the current node. The reference will begin one level below the start point node. For example, if you provide a page node the reference will begin at the item level. Use null to start the reference at the page level.
addNamespacesbooleanUse true to add declarations for unknown namespaces to the namespace node (theNSNode). Otherwise, use false.


A string containing a reference to the node, or throws a generic exception (UWIException) if an error occurs.

Usage details

Creating a reference string:
For more information about creating a reference, see About references .
Working with namespace prefixes:
In some cases, you may want to use the getReferenceEx method to get the reference to a node that uses a different prefix for a known namespace. For example, consider the following form:
   <label sid="Label1" xmlns:data="URI">
   <field sid="Field1" xmlns:processing="URI">

In this form, processing and data are prefixes for the same namespace, since they both refer to the same URI. However, both namespaces have limited scope since they are declared at the item level. This means that Label1 node does not understand the processing prefix, and that the Field1 node does not understand the data prefix.
This becomes a problem if you want to refer to a namespace from a location that does not understand that namespace. For example, suppose you want to set the value of Label1 to be a reference to the myValue node in Field1. Normally, you would locate the myValue node and use getReferenceEx as shown:
   myValueNode.getReferenceEx(null, null, null, false)

In this case, getReferenceEx would return the following reference: Page1.Field1.processing:myValue. However, because the processing namespace is not defined for Label1, a reference to the processing namespace is not understood. This means that you cannot set the value of Label1 to equal this reference, since the node would not understand that content.
Instead, you must generate a reference that includes a known namespace prefix, such as the data namespace. You can do this by including a second node in the getReferenceEx method. The second node must understand the appropriate namespace. For example, you could include the Label1 node in the method, as shown:
   myValueNode.getReferenceEx(null, Label1Node, null, false)

In this case, the method will substitute the data prefix for the processing prefix, since they both resolve to the same namespace. As a result, the method will return: Since the data prefix is defined within Label1, you can use this reference to set Label1's value node.
Working with unknown namespaces:
In some cases, you may want to use the getReferenceEx method to get the reference to a node that uses an unknown namespace. For example, consider the following form:
   <page sid="Page1" xmlns:processing="URI1">
      <global sid="global">
      <field sid="Field1" xmlns:data="URI2">

In this example, you might want to store a reference to the <data:info> element in the <processing:info> element. getReferenceEx would return the following reference for the <data:info> element: However, this reference includes the data namespace, which is not defined for the page global. This means that you could not store this reference in the <processing:info> element, because it would not understand the reference.
To solve this problem, you can use the addNamespaces flag in the getReferenceEx method. When this flag is set to true, the method will add unknown namespaces to the theNSNode.
For example, if you set theNSNode to be the global item node for Page1, and set the addNamespace flag to true, as shown:
   dataNode.getReferenceEx(null, pageGlobalNode, null, true)

The method would return the reference to the <data:info> element, but would also modify the global item node to include the unknown data namespaces, as shown:
   <global sid="global" xmlns:data="URI2">

You could then store the reference in that global item or any of its descendants, since the namespace is now properly defined.


In the following example, a page node is passed to the method. The method then uses getChildren and getNext to locate the last item node in the page. getReferenceEx is then called to get the reference to that node, which is returned to the caller.
   public String getLastItemReference(FormNodeP pageNode)
   FormNodeP itemNode, tempNode;
   String theReference;
      /* Get the first item node in the page. */
      itemNode = pageNode.getChildren();
      /* Cycle through to the last item node in the page. */
      while ((tempNode = itemNode.getNext()) != null)
         itemNode = tempNode;
      /* Get the reference to the node and return it. */
      theReference = itemNode.getReferenceEx(null, null, null, false);

Parent topic:
FormNodeP class