Community articleaddHints 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 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 addHints to list an array of nodes of the same type, or its companion method addHint to list nodes one at a time.


   public void addHints(
   java.util.List theReferences,
   int theReferencesType
   ) throws UWIException;


Table 1. Method parameters
theReferencesjava.util.ListThe list of nodes you want to identify to the parser. Note that they must all be of the same type.
theReferencesTypeintOne 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, Field1 through Field 4 are all inactive. However, as users complete the form, they may make a choice that requires those fields to be displayed as active after the form has been processed and sent on to the next user. In the following example, addHints is used to identify the nodes that are going to be changed and setLiteralByRefEx is used to change the active option of the fields to on.
private static void setFieldsActive() throws Exception
   String referenceOne = "";
   String referenceTwo = "";
   String referenceThree = "";
   String referenceFour = "";
   List hints = new ArrayList();
   theForm.addHints(hints, FormNodeP.UFL_OPTION_REFERENCE);
   theForm.setLiteralByRefEx(null, "referenceOne", 0, null,
         null, "on");
   theForm.setLiteralByRefEx(null, "referenceTwo", 0, null,
         null, "on");
   theForm.setLiteralByRefEx(null, "referenceThree", 0, null,
         null, "on");
   theForm.setLiteralByRefEx(null, "referenceFour", 0, null,
         null, "on");

Parent topic:
FormNodeP class