Community articlesetLiteralByRefEx method (Streaming API)
Added by IBM contributorIBM on August 16, 2011
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars


This method finds a particular FormNodeP as specified by a reference string. Once the FormNodeP is found, its literal will be set as specified. If the FormNodeP does not exist, this method will create it, but only if the FormNodeP would be an option or argument node.
If necessary, this method can create several nodes at once. For example, if you set the literal for the second argument of an itemlocation, this method will create the itemlocation option node and the two argument nodes and then set the literal for the second argument node.
This method cannot create a FormNodeP at the form, page, or item level. To do so, you must use the classic API.
The node you call this method on is used as the starting point for the search.
Note: It is not necessary to call this method when you are using XForms. Use the updateXFormsInstance method instead.


   public void setLiteralByRefEx(
      String theScheme,
      String theReference,
      int theReferenceCode,
      String theCharset,  
      FormNodeP theNSNode,
      String theLiteral
   ) throws UWIException;


theSchemeStringReserved. This must be null.
theReferenceStringA string that contains the reference.
theReferenceCodeintReserved. Must be 0.
theCharSetStringThe character set in which theLiteral parameter is written. Use null or Unicode for Unicode.
theNSNodeFormNodePA node that is used to resolve the namespaces in theReference parameter (see “Determining Namespace” in the Notes section below). Use null if the node that you are calling this method on has inherited the necessary namespaces.
theLiteralStringThe string that will be assigned to the literal. If null, any existing literal is removed.


Nothing if the call is successful or throws a generic exception (UWIException) if an error occurs.


This method is a shortcut method and is equivalent to performing the following on a FormNodeP object:
   aNode.dereferenceEx(theScheme, theReference, theReferenceCode,
      theNamespaceNode).setLiteralEx(aCharSet, aLiteral);

Before you decide which FormNodeP to use this method on, be sure you understand the following:
  1. The FormNodeP you supply can never be more than one level in the hierarchy above the level at which your reference string starts. 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 method will fail. For example, given a FormNodeP that represents "field_1" and a reference of "field_2", the method will access the "page" node above "field_1", and will then try to locate "field_2" below that node. If the two fields were not on the same page, the method would fail.
Creating a reference string:
For more information about creating a reference, see About references API 4 StrJavaCreate New Article.
Digital signatures:
Do not set a node that is digitally signed. Doing so will break the digital signature and produce an error.
Determining namespace:
In some cases, you may want to use the setLiteralByRefEx method:
   <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.setLiteralByRefEx(null, "Field1.processing:myValue", 0,
      null, null, "20")

In this example, the setLiteralByRefEx 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 a parameter in the method:
   Label1Node.setLiteralByRefEx(null, "Field1.processing:myValue", 0,
      null, Field1Node, "20")


In the original form, the label for the Age field instructs the user to leave the field blank. However, now that the field has been filled in by a formula, this label needs to be changed. In the following example setLiteralByRefEx is used to change this value.
   private static void setFormula(int curMonth, int curDay, int birMonth,
      int birDay) throws Exception
      /* additional code removed */
      theForm.setLiteralByRefEx(null, "PAGE1.AGELABEL.value", 0, null,
         null, "Age:");

Parent topic:
FormNodeP class