| gvSIG desktop 1

/*

 * $Id: UserInputPanel.java,v 1.1 2006/06/14 07:29:07 cesar Exp $

 * Copyright (C) 2002 Elmar Grom

 *

 * File :               UserInputPanel.java

 * Description :        A panel to collect input form the end user.

 * Author's email :     elmar@grom.net

 * Author's Website :   http://www.izforge.com

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 2

 * of the License, or any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

 */

package   com.izforge.izpack.panels;

import java.awt.Color;

import java.awt.Font;

import java.awt.event.ActionEvent;

import java.awt.event.ActionListener;

import java.io.File;

import java.io.InputStream;

import java.text.MessageFormat;

import java.util.HashMap;

import java.util.HashSet;

import java.util.Iterator;

import java.util.Map;

import java.util.StringTokenizer;

import java.util.Vector;

import javax.swing.BorderFactory;

import javax.swing.ButtonGroup;

import javax.swing.JButton;

import javax.swing.JCheckBox;

import javax.swing.JComboBox;

import javax.swing.JComponent;

import javax.swing.JFileChooser;

import javax.swing.JLabel;

import javax.swing.JOptionPane;

import javax.swing.JPanel;

import javax.swing.JPasswordField;

import javax.swing.JRadioButton;

import javax.swing.JTextField;

import net.n3.nanoxml.NonValidator;

import net.n3.nanoxml.StdXMLBuilder;

import net.n3.nanoxml.StdXMLParser;

import net.n3.nanoxml.StdXMLReader;

import net.n3.nanoxml.XMLElement;

import com.izforge.izpack.LocaleDatabase;

import com.izforge.izpack.Pack;

import com.izforge.izpack.gui.ButtonFactory;

import com.izforge.izpack.gui.TwoColumnConstraints;

import com.izforge.izpack.gui.TwoColumnLayout;

import com.izforge.izpack.installer.InstallData;

import com.izforge.izpack.installer.InstallerFrame;

import com.izforge.izpack.installer.IzPanel;

import com.izforge.izpack.installer.ResourceManager;

import com.izforge.izpack.installer.VariableSubstitutor;

import com.izforge.izpack.util.MultiLineLabel;

import com.izforge.izpack.util.OsConstraint;

import com.izforge.izpack.util.OsVersion;

/*---------------------------------------------------------------------------*/

/**

 * This panel is designed to collect user input during the installation

 * process. The panel is initially blank and is populated with input elements

 * based on the XML specification in a resource file.

 *

 *

 * @version  0.0.1 / 10/19/02

 * @author   getDirectoryCreated

 */

/*---------------------------------------------------------------------------*/

/*$

 * @design

 *

 * Each field is specified in its own node, containing attributes and data.

 * When this class is instantiated, the specification is read and analyzed.

 * Each field node is processed based on its type. An specialized member

 * function is called for each field type that creates the necessary UI

 * elements. All UI elements are stored in the uiElements vector. Elements

 * are packaged in an object array that must follow this pattern:

 *

 * index 0 - a String object, that specifies the field type. This is

 *           identical to the string used to identify the field type

 *           in the XML file.

 * index 1 - a String object that contains the variable name for substitution.

 * index 2 - the constraints object that should be used for positioning the

 *           UI element

 * index 3 - the UI element itself

 * index 4 - a Vector containg a list of pack for which the item should be

 *           created. This is used by buildUI() to decide if the item should

 *           be added to the UI.

 *

 * In some cases additional entries are used. The use depends on the specific

 * needs of the type of input field.

 *

 * When the panel is activated, the method buildUI() walks the list of UI

 * elements adds them to the panel together with the matching constraint.

 *

 * When an attempt is made to move on to another panel, the method readInput()

 * walks the list of UI elements again and calls specialized methods that

 * know how to read the user input from each of the UI elemnts and set the

 * associated varaible.

 *

 * The actual variable substitution is not performed by this panel but by

 * the variable substitutor.

 *

 * To Do:

 * ------

 * * make sure all header documentation is complete and correct

 *--------------------------------------------------------------------------*/

public class UserInputPanel extends IzPanel

{

  // ------------------------------------------------------------------------

  // Constant Definitions

  // ------------------------------------------------------------------------

  // The constants beginning with 'POS_' define locations in the object arrays

  // that used to hold all information for the individual fields. Some data is

  // not required for all field types. If this happens withing the array, that

  // location must be padded with 'null'. At the end of the array it can be

  // omitted. The data stored in this way is in most cases only known by

  // convention between the add and the associated read method. the following

  // positions are also used by other service methods in this class and must

  // not be used for other purposes:

  // - POS_DISPLAYED

  // - POS_TYPE

  // - POS_CONSTRAINTS

  // - POS_PACKS

  private static final int    POS_DISPLAYED                 = 0;

  private static final int    POS_TYPE                      = 1;

  private static final int    POS_VARIABLE                  = 2;

  private static final int    POS_CONSTRAINTS               = 3;

  private static final int    POS_FIELD                     = 4;

  private static final int    POS_PACKS                     = 5;

  private static final int    POS_OS                     = 6;

  private static final int    POS_TRUE                      = 7;

  private static final int    POS_FALSE                     = 8;

  private static final int    POS_MESSAGE                   = 9;

  private static final int    POS_GROUP                     = 10;

  /** The name of the XML file that specifies the panel layout */

  private static final String SPEC_FILE_NAME                = "userInputSpec.xml";

  private static final String LANG_FILE_NAME                = "userInputLang.xml";

  /** how the spec node for a specific panel is identified */

  private static final String NODE_ID                       = "panel";

  private static final String FIELD_NODE_ID                 = "field";

  private static final String INSTANCE_IDENTIFIER           = "order";

  private static final String TYPE                          = "type";

  private static final String DESCRIPTION                   = "description";

  private static final String VARIABLE                      = "variable";

  private static final String TEXT                          = "txt";

  private static final String KEY                           = "id";

  private static final String SPEC                          = "spec";

  private static final String SET                           = "set";

  private static final String TRUE                          = "true";

  private static final String FALSE                         = "false";

  private static final String ALIGNMENT                     = "align";

  private static final String LEFT                          = "left";

  private static final String CENTER                        = "center";

  private static final String RIGHT                         = "right";

  private static final String TOP                           = "top";

  private static final String BOTTOM                        = "bottom";

  private static final String ITALICS                       = "italic";

  private static final String BOLD                          = "bold";

  private static final String SIZE                          = "size";

  private static final String VALIDATOR                     = "validator";

  private static final String PROCESSOR                     = "processor";

  private static final String CLASS                         = "class";

  private static final String FIELD_LABEL                   = "label";

  private static final String TITLE_FIELD                   = "title";

  private static final String TEXT_FIELD                    = "text";

  private static final String TEXT_SIZE                     = "size";

  private static final String STATIC_TEXT                   = "staticText";

  private static final String COMBO_FIELD                   = "combo";

  private static final String COMBO_CHOICE                  = "choice";

  private static final String COMBO_VALUE                   = "value";

  private static final String RADIO_FIELD                   = "radio";

  private static final String RADIO_CHOICE                  = "choice";

  private static final String RADIO_VALUE                   = "value";

  private static final String SPACE_FIELD                   = "space";

  private static final String DIVIDER_FIELD                 = "divider";

  private static final String CHECK_FIELD                   = "check";

  private static final String RULE_FIELD                    = "rule";

  private static final String RULE_LAYOUT                   = "layout";

  private static final String RULE_SEPARATOR                = "separator";

  private static final String RULE_RESULT_FORMAT            = "resultFormat";

  private static final String RULE_PLAIN_STRING             = "plainString";

  private static final String RULE_DISPLAY_FORMAT           = "displayFormat";

  private static final String RULE_SPECIAL_SEPARATOR        = "specialSeparator";

  private static final String RULE_ENCRYPTED                = "processed";

  private static final String RULE_PARAM_NAME               = "name";

  private static final String RULE_PARAM_VALUE              = "value";

  private static final String RULE_PARAM                    = "param";

  private static final String PWD_FIELD                     = "password";

  private static final String PWD_INPUT                     = "pwd";

  private static final String PWD_SIZE                      = "size";

  private static final String SEARCH_FIELD                  = "search";

  // internal value for the button used to trigger autodetection

  private static final String SEARCH_BUTTON_FIELD           = "autodetect";

  private static final String SEARCH_CHOICE                 = "choice";

  private static final String SEARCH_FILENAME               = "filename";

  private static final String SEARCH_RESULT                 = "result";

  private static final String SEARCH_VALUE                  = "value";

  private static final String SEARCH_TYPE                   = "type";

  private static final String SEARCH_FILE                   = "file";

  private static final String SEARCH_DIRECTORY              = "directory";

  private static final String SEARCH_PARENTDIR              = "parentdir";

  private static final String SEARCH_CHECKFILENAME          = "checkfilename";

  private static final String PACKS                         = "createForPack";

  private static final String NAME                          = "name";

  private static final String OS = "os";

  private static final String FAMILY = "family";

  // ------------------------------------------------------------------------

  // Variable Declarations

  // ------------------------------------------------------------------------

  private static int          instanceCount   = 0;

  protected      int          instanceNumber  = 0;

  private        boolean      uiBuilt         = false;

  /** If there is a possibility that some UI elements will not get added we

      can not allow to go back to the PacksPanel, because the process of

      building the UI is not reversable. This variable keeps track if any

      packs have been defined and will be used to make a decision for

      locking the 'previous' button. */

  private         boolean     packsDefined    = false;

  private InstallerFrame      parentFrame;

  /** The parsed result from reading the XML specification from the file */

  private XMLElement          spec;

  private boolean             haveSpec = false;

  /** Holds the references to all of the UI elements */

  private Vector              uiElements      = new Vector ();

  /** Holds the references to all radio button groups */

  private Vector              buttonGroups    = new Vector ();

  /** Holds the references to all password field groups */

  private Vector              passwordGroups  = new Vector ();

  /** used for temporary storage of references to password groups that

      have already been read in a given read cycle. */

  private Vector              passwordGroupsRead  = new Vector ();

  /** Used to track search fields. Contains SearchField references. */

  private Vector              searchFields = new Vector();

  /** Holds all user inputs for use in automated installation */

  private Vector              entries         = new Vector ();

  private TwoColumnLayout     layout;

  private LocaleDatabase      langpack        = null;

 /*--------------------------------------------------------------------------*/

 // This method can be used to search for layout problems. If this class is

 // compiled with this method uncommented, the layout guides will be shown

 // on the panel, making it possible to see if all components are placed

 // correctly.

 /*--------------------------------------------------------------------------*/

//  public void paint (Graphics graphics)

//  {

//    super.paint (graphics);

//    layout.showRules ((Graphics2D)graphics, Color.red);

//  }

 /*--------------------------------------------------------------------------*/

 /**

  * Constructs a <code>UserInputPanel</code>.

  *

  * @param     parent       reference to the application frame

  * @param     installData  shared information about the installation

  */

 /*--------------------------------------------------------------------------*/

  public UserInputPanel (InstallerFrame parent,

                         InstallData    installData)

  {

    super (parent, installData);

    instanceNumber = instanceCount++;

    this.parentFrame = parent;

    // ----------------------------------------------------

    // ----------------------------------------------------

    layout = new TwoColumnLayout (10, 5, 30, 25, TwoColumnLayout.LEFT);

    setLayout (layout);

    // ----------------------------------------------------

    // get a locale database

    // ----------------------------------------------------

    try

    {

      //this.langpack = parent.langpack;

      String resource = LANG_FILE_NAME+"_"+idata.localeISO3;

      this.langpack = new LocaleDatabase (ResourceManager.getInstance().getInputStream (resource));

    }

    catch (Throwable exception)

    {}

    // ----------------------------------------------------

    // read the specifications

    // ----------------------------------------------------

    try

    {

      readSpec ();

    }

    catch (Throwable exception)

    {

      // log the problem

      exception.printStackTrace ();

    }

    if (!haveSpec)

    {

      // return if we could not read the spec. further

      // processing will only lead to problems. In this

      // case we must skip the panel when it gets activated.

      return;

    }

    // ----------------------------------------------------

    // process all field nodes. Each field node is analyzed

    // for its type, then an appropriate memeber function

    // is called that will create the correct UI elements.

    // ----------------------------------------------------

    Vector fields = spec.getChildrenNamed (FIELD_NODE_ID);

    for (int i = 0; i < fields.size (); i++)

    {

      XMLElement  field     = (XMLElement)fields.elementAt (i);

      String      attribute = field.getAttribute (TYPE);

      if (attribute != null)

      {

        if (attribute.equals (RULE_FIELD))

        {

          addRuleField (field);

        }

        else if (attribute.equals (TEXT_FIELD))

        {

          addTextField (field);

        }

        else if (attribute.equals (COMBO_FIELD))

        {

          addComboBox (field);

        }

        else if (attribute.equals (RADIO_FIELD))

        {

          addRadioButton (field);

        }

        else if (attribute.equals (PWD_FIELD))

        {

          addPasswordField (field);

        }

        else if (attribute.equals (SPACE_FIELD))

        {

          addSpace (field);

        }

        else if (attribute.equals (DIVIDER_FIELD))

        {

          addDivider (field);

        }

        else if (attribute.equals (CHECK_FIELD))

        {

          addCheckBox (field);

        }

        else if (attribute.equals (STATIC_TEXT))

        {

          addText (field);

        }

        else if (attribute.equals (TITLE_FIELD))

        {

          addTitle (field);

        }

        else if (attribute.equals (SEARCH_FIELD))

        {

          addSearch (field);

        }

      }

    }

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Indicates wether the panel has been validated or not. The installer won't

  * let the user go further through the installation process until the panel

  * is validated. Default behavior is to return true.

  *

  * @return    A boolean stating wether the panel has been validated or not.

  */

 /*--------------------------------------------------------------------------*/

  public boolean isValidated ()

  {

    return (readInput ());

  }

 /*--------------------------------------------------------------------------*/

 /**

  * This method is called when the panel becomes active.

  */

 /*--------------------------------------------------------------------------*/

  public void panelActivate ()

  {

    if (spec == null)

    {

      // TODO: translate

      emitError("User input specification could not be found.",

          "The specification for the user input panel could not be found. Please contact the packager.");

      parentFrame.skipPanel();

    }

    Vector forPacks = spec.getChildrenNamed (PACKS);

    Vector forOs = spec.getChildrenNamed(OS);

    if (!itemRequiredFor (forPacks) || !itemRequiredForOs(forOs))

    {

      parentFrame.skipPanel ();

      return;

    }

    if (!haveSpec)

    {

      parentFrame.skipPanel ();

      return;

    }

   // if (uiBuilt)

    //{

     // return;

    //}

    buildUI ();

    uiBuilt = true;

    if (packsDefined)

    {

      parentFrame.lockPrevButton ();

    }

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Asks the panel to set its own XML data that can be brought back for an

  * automated installation process. Use it as a blackbox if your panel needs

  * to do something even in automated mode.

  *

  * @param     panelRoot    The XML root element of the panels blackbox tree.

  */

 /*--------------------------------------------------------------------------*/

  public void makeXMLData (XMLElement panelRoot)

  {

                Map entryMap = new HashMap();

                for (int i = 0; i < entries.size (); i++)

                {

                        TextValuePair pair = (TextValuePair)entries.elementAt(i);

                        entryMap.put( pair.toString(), pair.getValue() );

                }

                new UserInputPanelAutomationHelper(entryMap).makeXMLData(idata, panelRoot);

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Builds the UI and makes it ready for display

  */

 /*--------------------------------------------------------------------------*/

  private void buildUI ()

  {

    Object [] uiElement;

    for (int i = 0; i < uiElements.size (); i++)

    {

      uiElement = (Object [])uiElements.elementAt (i);

      if (itemRequiredFor ((Vector)uiElement [POS_PACKS]) && itemRequiredForOs((Vector) uiElement[POS_OS]) )

      {

        try

        {

                if (uiElement [POS_DISPLAYED] == null || uiElement [POS_DISPLAYED].toString().equals("false"))

                {

                  add ((JComponent)uiElement [POS_FIELD], uiElement [POS_CONSTRAINTS]);

                }

                uiElement [POS_DISPLAYED] = Boolean.valueOf (true);

                uiElements.remove(i);

                uiElements.add(i, uiElement);          

        }

        catch (Throwable exception)

        {

          System.out.println ("Internal format error in field: " + uiElement [POS_TYPE].toString ());  // !!! logging

        }

      }

      else

      {

              try

              {

                if (uiElement [POS_DISPLAYED] != null && uiElement [POS_DISPLAYED].toString().equals("true"))

                {

                  remove((JComponent)uiElement [POS_FIELD]);

                }

              }

              catch (Throwable exception)

              {

                System.out.println ("Internal format error in field: " + uiElement [POS_TYPE].toString ());  // !!! logging

              }

        uiElement [POS_DISPLAYED] = Boolean.valueOf (false);

        uiElements.remove(i);

        uiElements.add(i, uiElement);

      }

    }

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Reads the input data from all UI elements and sets the associated variables.

  *

  * @return    <code>true</code> if the operation is successdul, otherwise

  *            <code>false</code>.

  */

 /*--------------------------------------------------------------------------*/

  private boolean readInput ()

  {

    boolean     success;

    String      fieldType = null;

    Object []   field     = null;

    passwordGroupsRead.clear ();

    // ----------------------------------------------------

    // cycle through all but the password fields and read

    // their contents

    // ----------------------------------------------------

    for (int i = 0; i < uiElements.size (); i++)

    {

      field     = (Object [])uiElements.elementAt (i);

      if ((field != null) && (((Boolean)field [POS_DISPLAYED]).booleanValue ()))

      {

        fieldType = (String)(field [POS_TYPE]);

        // ------------------------------------------------

        if (fieldType.equals (RULE_FIELD))

        {

          success = readRuleField (field);

          if (!success)

          {

            return (false);

          }

        }

        // ------------------------------------------------

        if (fieldType.equals (PWD_FIELD))

        {

          success = readPasswordField (field);

          if (!success)

          {

            return (false);

          }

        }

        // ------------------------------------------------

        else if (fieldType.equals (TEXT_FIELD))

        {

          success = readTextField (field);

          if (!success)

          {

            return (false);

          }

        }

        // ------------------------------------------------

        else if (fieldType.equals (COMBO_FIELD))

        {

          success = readComboBox (field);

          if (!success)

          {

            return (false);

          }

        }

        // ------------------------------------------------

        else if (fieldType.equals (RADIO_FIELD))

        {

          success = readRadioButton (field);

          if (!success)

          {

            return (false);

          }

        }

        // ------------------------------------------------

        else if (fieldType.equals (CHECK_FIELD))

        {

          success = readCheckBox (field);

          if (!success)

          {

            return (false);

          }

        }

        else if (fieldType.equals (SEARCH_FIELD))

        {

          success = readSearch (field);

          if (!success)

          {

            return (false);

          }

        }

      }

    }

    return (true);

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Reads the XML specification for the panel layout. The result is

  * stored in spec.

  *

  * @exception Exception for any problems in reading the specification

  */

 /*--------------------------------------------------------------------------*/

  private void readSpec () throws Exception

  {

    InputStream input = null;

    XMLElement  data;

    Vector      specElements;

    String      attribute;

    String      instance = Integer.toString (instanceNumber);

    try

    {

      input = parentFrame.getResource (SPEC_FILE_NAME);

    }

    catch (Exception exception)

    {

      haveSpec = false;

      return;

    }

    if (input == null)

    {

      haveSpec = false;

      return;

    }

    // initialize the parser

    StdXMLParser parser = new StdXMLParser ();

    parser.setBuilder   (new StdXMLBuilder ());

    parser.setValidator (new NonValidator ());

    parser.setReader    (new StdXMLReader (input));

    // get the data

    data = (XMLElement) parser.parse ();

    // extract the spec to this specific panel instance

    if (data.hasChildren ())

    {

      specElements = data.getChildrenNamed (NODE_ID);

      for (int i = 0; i < specElements.size (); i++)

      {

        data      = (XMLElement)specElements.elementAt (i);

        attribute = data.getAttribute (INSTANCE_IDENTIFIER);

        if (instance.equals (attribute))

        {

          // use the current element as spec

          spec = data;

          // close the stream

          input.close ();

          haveSpec = true;

          return;

        }

      }

      haveSpec = false;

      return;

    }

    haveSpec = false;

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Adds the title to the panel. There can only be one title, if mutiple

  * titles are defined, they keep overwriting what has already be defined,

  * so that the last definition is the one that prevails.

  *

  * @param     spec  a <code>XMLElement</code> containing the specification

  *                  for the title.

  */

 /*--------------------------------------------------------------------------*/

  private void addTitle (XMLElement spec)

  {

    String  title       = getText       (spec);

    boolean italic      = getBoolean    (spec, ITALICS, false);

    boolean bold        = getBoolean    (spec, BOLD, false);

    float   multiplier  = getFloat      (spec, SIZE, 2.0f);

    int     justify     = getAlignment  (spec);

    if (title != null)

    {

      JLabel label = new JLabel (title);

      Font   font  = label.getFont ();

      float  size  = font.getSize ();

      int    style = 0;

      if (bold)

      {

        style = style + Font.BOLD;

      }

      if (italic)

      {

        style = style + Font.ITALIC;

      }

      font = font.deriveFont (style, (size * multiplier));

      label.setFont (font);

      label.setAlignmentX (0);

      TwoColumnConstraints constraints = new TwoColumnConstraints ();

      constraints.align     = justify;

      constraints.position  = TwoColumnConstraints.NORTH;

      add (label, constraints);

    }

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Adds a rule field to the list of UI elements.

  *

  * @param     spec  a <code>XMLElement</code> containing the specification

  *                  for the rule field.

  */

 /*--------------------------------------------------------------------------*/

  private void addRuleField (XMLElement spec)

  {

    Vector forPacks = spec.getChildrenNamed (PACKS);

        Vector forOs = spec.getChildrenNamed(OS);

    XMLElement      element       = spec.getFirstChildNamed (SPEC);

    String          variable      = spec.getAttribute (VARIABLE);

    RuleInputField  field         = null;

    JLabel          label;

    String          layout;

    String          set;

    String          separator;

    String          format;

    String          validator     = null;

    String          message       = null;

        boolean         hasParams        = false;

        String          paramName        = null;

        String          paramValue       = null;

        HashMap         validateParamMap = null;

        Vector          validateParams   = null;

    String          processor     = null;

    int             resultFormat  = RuleInputField.DISPLAY_FORMAT;

    // ----------------------------------------------------

    // extract the specification details

    // ----------------------------------------------------

    if (element != null)

    {

      label     = new JLabel (getText (element));

      layout    = element.getAttribute (RULE_LAYOUT);

      set       = element.getAttribute (SET);

      // retrieve value of variable if not specified

      // (does not work here because of special format for set attribute)

      //if (set == null)

      //{

      //  set = idata.getVariable (variable);

      //}

      separator = element.getAttribute (RULE_SEPARATOR);

      format    = element.getAttribute (RULE_RESULT_FORMAT);

      if (format != null)

      {

        if (format.equals (RULE_PLAIN_STRING))

        {

          resultFormat = RuleInputField.PLAIN_STRING;

        }

        else if (format.equals (RULE_DISPLAY_FORMAT))

        {

          resultFormat = RuleInputField.DISPLAY_FORMAT;

        }

        else if (format.equals (RULE_SPECIAL_SEPARATOR))

        {

          resultFormat = RuleInputField.SPECIAL_SEPARATOR;

        }

        else if (format.equals (RULE_ENCRYPTED))

        {

          resultFormat = RuleInputField.ENCRYPTED;

        }

      }

    }

    // ----------------------------------------------------

    // if there is no specification element, return without

    // doing anything.

    // ----------------------------------------------------

    else

    {

      return;

    }

    // ----------------------------------------------------

    // get the description and add it to the list of UI

    // elements if it exists.

    // ----------------------------------------------------

    element = spec.getFirstChildNamed (DESCRIPTION);

    addDescription (element, forPacks, forOs);

    // ----------------------------------------------------

    // get the validator and processor if they are defined

    // ----------------------------------------------------

    element = spec.getFirstChildNamed (VALIDATOR);

    if (element != null)

    {

      validator = element.getAttribute (CLASS);

      message   = getText (element);

      // ----------------------------------------------------------

      // check and see if we have any parameters for this validator.

      // If so, then add them to validateParamMap.

      // ----------------------------------------------------------

      validateParams = element.getChildrenNamed(RULE_PARAM);

      if (validateParams != null

          && validateParams.size() > 0

          && validateParamMap == null)

      {

        validateParamMap = new HashMap();

        hasParams = true;

      }

      for (Iterator it = validateParams.iterator(); it.hasNext();)

      {

        element = (XMLElement) it.next();

        paramName = element.getAttribute(RULE_PARAM_NAME);

        paramValue = element.getAttribute(RULE_PARAM_VALUE);

        validateParamMap.put(paramName, paramValue);

      }

    }

    element = spec.getFirstChildNamed (PROCESSOR);

    if (element != null)

    {

      processor = element.getAttribute (CLASS);

    }

    // ----------------------------------------------------

    // create an instance of RuleInputField based on the

    // extracted specifications, then add it to the list

    // of UI elements.

    // ----------------------------------------------------

    if (hasParams)

    {

      field =

        new RuleInputField(

          layout,

          set,

          separator,

          validator,

          validateParamMap,

          processor,

          resultFormat,

          getToolkit());

    }

    else

    {

      field =

        new RuleInputField(

          layout,

          set,

          separator,

          validator,

          processor,

          resultFormat,

          getToolkit ());

    }

    TwoColumnConstraints constraints = new TwoColumnConstraints ();

    constraints.position              = TwoColumnConstraints.WEST;

    uiElements.add (new Object [] {null, FIELD_LABEL, null, constraints, label, forPacks, forOs});

    TwoColumnConstraints constraints2 = new TwoColumnConstraints ();

    constraints2.position             = TwoColumnConstraints.EAST;

    uiElements.add (new Object [] {null, RULE_FIELD, variable, constraints2, field, forPacks, forOs, null, null, message});

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Reads the data from the rule input field and sets the associated variable.

  *

  * @param     field  the object array that holds the details of the field.

  *

  * @return    <code>true</code> if there was no problem reading the data or

  *            if there was an irrecovarable problem. If there was a problem

  *            that can be corrected by the operator, an error dialog is

  *            popped up and <code>false</code> is returned.

  */

 /*--------------------------------------------------------------------------*/

  private boolean readRuleField (Object [] field)

  {

    RuleInputField  ruleField = null;

    String          variable  = null;

    try

    {

      ruleField = (RuleInputField)field [POS_FIELD];

      variable  = (String)field [POS_VARIABLE];

    }

    catch (Throwable exception)

    {

      return (true);

    }

    if ((variable == null) || (ruleField == null))

    {

      return (true);

    }

    boolean success = ruleField.validateContents ();

    if (!success)

    {

        String message = "";

        try{

                message = langpack.getString( (String)field [POS_MESSAGE]);

                if (message.equals("")){

                        message = (String)field [POS_MESSAGE];

                }

        }catch (Throwable t){

                        message = (String)field [POS_MESSAGE];

        }

      JOptionPane.showMessageDialog (parentFrame,

                                     message,

                                     parentFrame.langpack.getString ("UserInputPanel.error.caption"),

                                     JOptionPane.WARNING_MESSAGE);

      return (false);

    }

    idata.setVariable (variable, ruleField.getText ());

    entries.add (new TextValuePair (variable, ruleField.getText ()));

    return (true);

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Adds a text field to the list of UI elements

  *

  * @param     spec  a <code>XMLElement</code> containing the specification

  *                  for the text field.

  */

 /*--------------------------------------------------------------------------*/

  private void addTextField (XMLElement spec)

  {

    Vector      forPacks = spec.getChildrenNamed (PACKS);

        Vector forOs = spec.getChildrenNamed(OS);

    XMLElement  element  = spec.getFirstChildNamed (SPEC);

    JLabel      label;

    String      set;

    int         size;

    String      variable = spec.getAttribute (VARIABLE);

    if ((variable == null) || (variable.length () == 0))

    {

      return;

    }

    // ----------------------------------------------------

    // extract the specification details

    // ----------------------------------------------------

    if (element != null)

    {

      label = new JLabel (getText (element));

      set   = element.getAttribute (SET);

      if (set == null)

      {

        set = idata.getVariable (variable);

        if (set == null)

        {

          set = "";

        }

      }

      try

      {

        size = Integer.parseInt (element.getAttribute (TEXT_SIZE));

      }

      catch (Throwable exception)

      {

        size = 1;

      }

    }

    // ----------------------------------------------------

    // if there is no specification element, return without

    // doing anything.

    // ----------------------------------------------------

    else

    {

      return;

    }

    // ----------------------------------------------------

    // get the description and add it to the list UI

    // elements if it exists.

    // ----------------------------------------------------

    element = spec.getFirstChildNamed (DESCRIPTION);

    addDescription (element, forPacks, forOs);

    // ----------------------------------------------------

    // construct the UI element and add it to the list

    // ----------------------------------------------------

    JTextField field = new JTextField (set, size);

    field.setCaretPosition (0);

    TwoColumnConstraints constraints = new TwoColumnConstraints ();

    constraints.position  = TwoColumnConstraints.WEST;

    uiElements.add (new Object [] {null, FIELD_LABEL, null, constraints, label, forPacks, forOs});

    TwoColumnConstraints constraints2 = new TwoColumnConstraints ();

    constraints2.position  = TwoColumnConstraints.EAST;

    uiElements.add (new Object [] {null, TEXT_FIELD, variable, constraints2, field, forPacks, forOs});

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Reads data from the text field and sets the associated variable.

  *

  * @param     field  the object array that holds the details of the field.

  *

  * @return    <code>true</code> if there was no problem reading the data or

  *            if there was an irrecovarable problem. If there was a problem

  *            that can be corrected by the operator, an error dialog is

  *            popped up and <code>false</code> is returned.

  */

 /*--------------------------------------------------------------------------*/

  private boolean readTextField (Object [] field)

  {

    JTextField  textField = null;

    String      variable  = null;

    String      value     = null;

    try

    {

      textField = (JTextField)field [POS_FIELD];

      variable  = (String)field [POS_VARIABLE];

      value     = textField.getText ();

    }

    catch (Throwable exception)

    {

      return (true);

    }

    if ((variable == null) || (value == null))

    {

      return (true);

    }

    idata.setVariable(variable, value);

    entries.add (new TextValuePair (variable, value));

    return (true);

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Adds a combo box to the list of UI elements. <br>

  * This is a complete example of a valid XML specification

  * <pre>

  * <field type="combo" variable="testVariable">

  *   <description text="Description for the combo box" id="a key for translated text"/>

  *   <spec text="label" id="key for the label"/>

  *     <choice text="choice 1" id="" value="combo box 1"/>

  *     <choice text="choice 2" id="" value="combo box 2" set="true"/>

  *     <choice text="choice 3" id="" value="combo box 3"/>

  *     <choice text="choice 4" id="" value="combo box 4"/>

  *   </spec>

  * </field>

  * </pre>

  * @param     spec  a <code>XMLElement</code> containing the specification

  *                  for the combo box.

  */

 /*--------------------------------------------------------------------------*/

  private void addComboBox (XMLElement spec)

  {

    Vector        forPacks  = spec.getChildrenNamed (PACKS);

        Vector forOs = spec.getChildrenNamed(OS);

    XMLElement    element   = spec.getFirstChildNamed (SPEC);

    String        variable  = spec.getAttribute (VARIABLE);

    TextValuePair listItem  = null;

    JComboBox     field     = new JComboBox ();

    JLabel        label;

    // ----------------------------------------------------

    // extract the specification details

    // ----------------------------------------------------

    if (element != null)

    {

      label = new JLabel (getText (element));

      Vector choices = element.getChildrenNamed (COMBO_CHOICE);

      if (choices == null)

      {

        return;

      }

      for (int i = 0; i < choices.size (); i++)

      {

        String processorClass = ((XMLElement)choices.elementAt (i)).getAttribute("processor");

        if (!"".equals(processorClass))

        {

                        String choiceValues = "";

                try

                {

                                choiceValues = ((Processor) Class.forName(processorClass).newInstance()).process(null);

                }

                catch (Throwable t)

                {

                        t.printStackTrace();

                }

                        String set    = ((XMLElement)choices.elementAt (i)).getAttribute (SET);

                        if (set == null)

                        {

                                set = "";

                        }

                StringTokenizer tokenizer = new StringTokenizer(choiceValues, ":");

                int counter = 0;

                while (tokenizer.hasMoreTokens()){

                        String token = tokenizer.nextToken();

                        listItem = new TextValuePair(token, token);

                        field.addItem(listItem);

                                if (set.equals(token)){

                                        field.setSelectedIndex (field.getItemCount()-1);

                                }

                        counter++;

                }

        }

        else

        {

                listItem = new TextValuePair (getText ((XMLElement)choices.elementAt (i)),

                                          ((XMLElement)choices.elementAt (i)).getAttribute (COMBO_VALUE));

                        field.addItem (listItem);

                        String set    = ((XMLElement)choices.elementAt (i)).getAttribute (SET);

                        if (set != null)

                        {

                          if (set.equals (TRUE))

                          {

                                field.setSelectedIndex (i);

                          }

                        }

        }

      }

    }

    // ----------------------------------------------------

    // if there is no specification element, return without

    // doing anything.

    // ----------------------------------------------------

    else

    {

      return;

    }

    // ----------------------------------------------------

    // get the description and add it to the list of UI

    // elements if it exists.

    // ----------------------------------------------------

    element = spec.getFirstChildNamed (DESCRIPTION);

    addDescription (element, forPacks, forOs);

    TwoColumnConstraints constraints = new TwoColumnConstraints ();

    constraints.position  = TwoColumnConstraints.WEST;

    uiElements.add (new Object [] {null, FIELD_LABEL, null, constraints, label, forPacks, forOs});

    TwoColumnConstraints constraints2 = new TwoColumnConstraints ();

    constraints2.position  = TwoColumnConstraints.EAST;

    uiElements.add (new Object [] {null, COMBO_FIELD, variable, constraints2, field, forPacks, forOs});

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Reads the content of the combobox field and substitutes the associated

  * variable.

  *

  * @param     field  the object array that holds the details of the field.

  *

  * @return    <code>true</code> if there was no problem reading the data or

  *            if there was an irrecovarable problem. If there was a problem

  *            that can be corrected by the operator, an error dialog is

  *            popped up and <code>false</code> is returned.

  */

 /*--------------------------------------------------------------------------*/

  private boolean readComboBox (Object [] field)

  {

    String variable;

    String value;

    JComboBox comboBox;

    try

    {

      variable  = (String)field [POS_VARIABLE];

      comboBox  = (JComboBox)field [POS_FIELD];

      value     = ((TextValuePair)comboBox.getSelectedItem ()).getValue ();

    }

    catch (Throwable exception)

    {

      return true;

    }

    if ((variable == null) || (value == null))

    {

      return true;

    }

    idata.setVariable(variable, value);

    entries.add (new TextValuePair (variable, value));

    return true;

  }

 /*--------------------------------------------------------------------------*/

 /**

  * Adds a radio button set to the list of UI elements. <br>

  * This is a complete example of a valid XML specification

  * <pre>

  * <field type="radio" variable="testVariable">

  *   <description text="Description for the radio buttons" id="a key for translated text"/>

  *   <spec text="label" id="key for the label"/>

  *     <choice text="radio 1" id="" value=""/>

  *     <choice text="radio 2" id="" value="" set="true"/>

  *     <choice text="radio 3" id="" value=""/>

  *     <choice text="radio 4" id="" value=""/>

  *     <choice text="radio 5" id="" value=""/>

  *   </spec>

  * </field>

  * </pre>

  *

  * @param     spec  a <code>XMLElement</code> containing the specification

  *                  for the radio button set.

  */

 /*--------------------------------------------------------------------------*/