Community articlereadForm method
Added by IBM contributorIBM on August 15, 2011
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

No abstract provided.



Description

This method reads a form into memory from a specified file, Java Reader, or input stream.

Method

READING A FILE:
   public FormNodeP readForm(
      String theFilePath,
      int flags
      ) throws UWIException;

READING A STREAM:
   public FormNodeP readForm(
      InputStream theStream,
      int flags
      ) throws UWIException;

READING A READER:
   public FormNodeP readForm(
      java.io.Reader theReader,
      int flags
      ) throws UWIException;


Parameters

ExpressionTypeDescription
theFilePathStringThe path to the source file on the local disk.
theStream InputStreamThis is the stream that will read the form data. Note that this data must be UTF-8.
theReader java.io.ReaderThis is the reader that will read the form data.
flagsint0 — no special behavior.
XFDL.UFL_SERVER_SPEED_FLAGS — This setting significantly improves server processing times. It does that by turning off the following features: computes, automatic formatting, duplicate sid detection, XForms processing, write relevant, the event model, and relative page and item tags (for example, itemprevious, itemnext, and so on).
Note that this setting does not respect XForms relevance.
XFDL.UFL_SERVER_SPEED_FLAGS_WITH_XFORMS — This setting significantly improves server processing times in the same manner as XFDL.UFL_SERVER_SPEED_FLAGS, but it does not turn off XForms processing, and it respects XForms relevance.
The remaining flags cause special behaviors. If using multiple flags, combine them using a bitwise OR, AND, or NOT. For example:
   XFDL.UFL_AUTOCOMPUTE_OFF | 
   XFDL.UFL_AUTOCREATE_FORMATS_OFF

XFDL.UFL_AUTOCOMPUTE_OFF — Reads the form into memory, but disables the compute system so that no computes are evaluated.
XFDL.UFL_AUTOCREATE_CONTROLLED_OFF — Reads the form into memory, but disables the creation of all options that are maintained only in memory (for example, itemnext, itemprevious, pagenext, pageprevious, and so on).
XFDL.UFL_AUTOCREATE_FORMATS_OFF — Reads the form into memory, but disables the evaluation of all format options.
XFDL.UFL_XFORMS_INITIALIZE_ONLY — Turns off UI connection to the XForms model. This flag respects XForms relevance and validity settings, but changes to the XForms model are not reflected in the UI.
XFDL.UFL_XFORMS_OFF — Turns off XForms processing, including UI connection to the XForms model.


Returns

Returns a new FormNodeP that is the root node of the form, or throws a generic exception (UWIException) if an error occurs.

Notes

Duplicate Scope IDs
If a form contains duplicate scope IDs (for example, two items on the same page with the same SID), readForm will fail to read the form and will return an error. This enforces correct XFDL syntax, and eliminates certain security risks that exist when duplicate scope IDs appear in signed forms.
Digital Signatures
When a form containing one or more digital signatures is read, the signatures will be verified. The result of the verification is stored in a flag that can be checked by calling getSignatureVerificationStatus.
Note that this flag is only set by readForm, and its value will not be adjusted by changes made to the form after it has been read. This means that calls such as setLiteralEx may actually break a signature (by changing the value of a signed item), but that this will not adjust the flag's value. To verify a signature after changes have been made to a form, use verifyAllSignatures.
Server-Side Processing
Using the XFDL.UFL_SERVER_SPEED_FLAGS setting significantly improves performance during server-side processing. Note that this setting turns XForms processing off. If you need XForms processing to be on, use XFDL.UFL_SERVER_SPEED_FLAGS_WITH_XFORMS.
Components of XFDL.UFL_SERVER_SPEED_FLAGS
XFDL.UFL_SERVER_SPEED_FLAGS is comprised of a number of other flags that are used together to provide improved server processing times. These flags include:
  • XFDL.UFL_AUTOCOMPUTE_OFF
  • XFDL.UFL_AUTOCREATE_CONTROLLED_OFF
  • XFDL.UFL_AUTOCREATE_FORMATS_OFF
  • XFDL.UFL_XFORMS_OFF
If you find that you need some but not all of the functionality of XFDL.UFL_SERVER_SPEED_FLAGS, you can turn off these flags as shown in the Server-Side Processing usage note, above.
Using updateXFormsInstance and extractXFormsInstance with UFL_SERVER_SPEED_FLAGS
You can modify an XForms instance with updateXFormsInstancereadFormextractXFormsInstance

Example

The following example demonstrates the use of readForm to load a form into memory, and then returns to the root node of the form.
   private static FormNodeP loadForm() throws Exception
   {
    XFDL theXFDL;
    formNodeP theForm;
      if ((theXFDL = IFSSingleton.getXFDL()) == null)
         throw new Exception("Could not find interface");
      if ((theForm = theXFDL.readForm("formSample.xfd", 0)) == null)
         throw new Exception("Could not load form.");
      return(theForm);
   }


Parent topic:
XFDL class