Community articlegetLiteralByRefEx method (Streaming API)
Added by IBM contributorIBM on May 2, 2012
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars




Description

This method finds a particular FormNodeP on the basis of a reference string. The node you call this method on is used as the starting point for the search unless you provide an absolute reference. Once the FormNodeP is found, its literal is retrieved.
Note: It is not necessary to call this method when you are using XForms. The replaceXFormsInstance and extractXFormsInstance methods perform this task automatically.

Method

   public String getLiteralByRefEx(
      String theScheme,
      String theReference,
      int theReferenceCode
      String theCharSet,
      FormNodeP theNSNode
      ) throws UWIException;


Parameters

Table 1. Method parameters
ExpressionTypeDescription
theSchemeStringReserved. This must be null.
theReferenceStringThe reference string.
theReferenceCodeintReserved. This must be 0.
theCharSetStringThe character set you want to use to view the literal string. Use null or Unicode for Unicode.
theNSNodeFormNodePA node that is used to resolve the namespaces in 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 literal string or throws a generic exception (UWIException) if an error occurs. If the literal is empty or does not exist, the method returns null.

Notes

FormNodeP:
Before you decide which FormNodeP to call the 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 method will fail.
  3. 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 are not on the same page, the method will fail.
  4. If the FormNodeP is at the argument level, the search will not start from that point. Instead, the nearest ancestor that is at the option level will be used as the starting point for the search.
Creating a reference string:
For more information about creating a reference, see About references API 8 StrJavaCreate New Article .
Determining namespace:
In some cases, you may want to use the getLiteralByRefEx method to get the literal of 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.getLiteralByRefEx(null, "Field1.processing:myValue", 0,
      null, null)

In this example, the getLiteralByRefEx 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.getLiteralByRefEx(null, "Field1.processing:myValue", 0,
      null, Field1Node)


Example

The following example uses getLiteralByRefEx to get the literal value from a specific node. That value is then converted into an integer.
   private static int getCurrentDay( ) throws Exception
   {
   String temp;
 
      temp = theForm.getLiteralByRefEx(null, "PAGE1.CURRENTDAY.value", 0,
         null, null);
 
      /* If a literal value was returned, convert it into an integer value;
      otherwise, indicate that no value was entered into the field and throw
      an exception. */
 
      if (temp != null)
      {
         return Integer.parseInt(temp);
      }
      else
      {
         throw new UWIException("The current day was not entered.");
      }
   }


Parent topic:
FormNodeP class