Community articleaddHint 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


This method tells the parser which node will be referenced by your application. You can use this method at the start of your application to list all the nodes that you want to retrieve, or you can use it at the beginning of a method to list all the nodes that it will use. This improves the performance of your application by allowing the parser to collect all the requested data while traversing the form fewer times. If you list all the nodes you plan to retrieve at the beginning of your application, the parser will only need to traverse the forms once.
Use addHint to list nodes one at a time, or its companion method addHints to list an array of nodes of the same type.


   public void addHint(
   String theReference,
   int theReferenceType
   ) throws UWIException;


Table 1. Method parameters
theReferenceStringThe node you want to identify to the parser.
theReferenceTypeintOne 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].


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


Using wildcard references:
You can use wildcard characters to identify a subset of nodes for the parser to collect data from. The supported wildcard characters are:
  • * — Indicates that all of the node's immediate children should be identified.
  • ** — Indicates that all of the node's immediate children and all of their children should be retrieved. Using this wildcard character ensures that all of the node's descendants are retrieved.
For example, Page1.Field1.* retrieves all options that are children of the Page1.Field1 node, and Page1.Field1.** retrieves all options and array elements that are children of the Page1.Item1 node.
These wildcard characters modify the entire name component. For example, Page1*.Field.value provides the same results as *.Field.value. In other words, it identifies all pages, not just pages that begin with the number 1.


When the form referenced by this sample code is opened by a user, the label for the Age field instructs the user to leave the field blank. However, as the user completes the form, the field is filled in by a formula, which means this label needs to be updated during processing, so that the next form user will see the updated label. In the following example, addHint is used to identify the node that is going to be changed and setLiteralByRefEx is used to change this value.
private static void setFormula(int curMonth, int curDay, int birMonth,
   int birDay) throws Exception
   String referenceOne = "PAGE1.AGELABEL.value"
   FormNodeP theForm = theXFDL.readForm(formSample.xfd, 
   theForm.addHint(referenceOne, FormNodeP.UFL_OPTION_REFERENCE);
   theForm.setLiteralByRefEx(null, "referenceOne", 0, null,
      null, "Age:");

Parent topic:
FormNodeP class