Base-Class to read the file with a XML-structure for the Task-List - Fat-Client-Development

This is document contains the code for Class JSBS_XML_Tasks.
For easy 'cut and paste' ;-)

package js_base.xml;

import java.util.*;

import javax.swing.*;
import javax.swing.tree.DefaultMutableTreeNode;

import org.jdom.*;
import js_base.structures.JSBS_UniversalParameters;
/**
 *
 * @author kurt@javascout.biz
 * @date 2006-08-24
 *
 * @description
 *  Class with specialized methods to process a Task-List.
 *  A Task-List is a XML-structure containing selectable codes and
 *  descriptions for the (Sub-) Tasks of an application.
 *  This class inherits JSBS_XML_Base and uses its methods to read a file
 *  containing a XML-structure.
 *
 * @change-log
 * when         who               why
 * --------------------------------------------------------
 *
 */
public class JSBS_XML_Tasks extends JSBS_XML_Base {
/*
 * Global variables which are accessed by more than one method. */
/* Indicator, that <DisplayedCode> (from the XML-structure) and entered Code (at the GUI)
 * should be converted to upper-case before they are displayed or compared. */
    boolean bolUpperCase = false;
/* List with the tasks, number of list-elements and
 * index to access an element within the list. */
    List listTasks;
    int intListTasksSize;
    int intListTasksIndex = 0;
/*
 * -------------------------------
 * Constructor of the class */
    public JSBS_XML_Tasks(JSBS_UniversalParameters parmUniversalParameters) {
/* Perform the code in the constructor of the inherited class */
        super();
/* Get the filename for the XML-structure with the language dependant display-strings.
 * This is done by concatenating the directory with the language dependant files
 * and the filename for the file with the XML-structure. */
        String locstrFileName =
            parmUniversalParameters.strTextElementsDirectoryName +
            parmUniversalParameters.CONST_TASKLIST_FILE_NAME;
/* Read the RootElement (method implemented in the superclass - i.e. the class inherited) */
        readXMLFile(locstrFileName);
/*
 * Break processing if StatusCode signals other than OK */
        if (StatusCode != CONST_OK) return;
/*
 * Check if the <UpperCase> element is present in the XML-structure */
      Element locElementUpperCase = XML_RootElement.getChild("UpperCase");
        bolUpperCase = (locElementUpperCase != null);
/* 
 * Check if there is at least one Element for a Task in the XML-structure. */
      Element locElementTask = XML_RootElement.getChild("Task");
      if (locElementTask == null) {
        StatusCode = CONST_NO_TASK_ELEMENT_PRESENT;
      }
    }
/*
 * ************************************************** */
/*
 * Method to fill a GUI-element of type JTree with the Task-structure. */
    public JTree getTaskTree() {
/* 
 * Root-Node of the JTree. */
      DefaultMutableTreeNode BaseLayer = new DefaultMutableTreeNode();
/* 
 * Check if there is at least one Element for a Task in the XML-structure. */
      Element ElementTask = XML_RootElement.getChild("Task");
      if (ElementTask == null) {
        StatusCode = CONST_NO_TASK_ELEMENT_PRESENT;
        return new JTree();
      }
/* 
 * Get the list with all Task-elements out of the XML-structure
 * and let the subroutine do the building of the JTree. */
      listTasks = XML_RootElement.getChildren("Task");
      intListTasksSize = listTasks.size();
      do {
          BaseLayer.add(buildSubTree());
          intListTasksIndex++;
      } while(intListTasksIndex < intListTasksSize);
        StatusCode = CONST_NO_TASK_ELEMENT_PRESENT;
/* 
 * Make a JTree based on the DefaultMutableTreeNode which contains
 * the complete Task-Hierarchy now. */
      return new JTree(BaseLayer);
    }
/*
 * ************************************************** */
/*
 * Method to build a Task-Tree.
 * Rule for attaching lower levels to a 'parent' is:
 * All elements that start with the same letter(s) as the 'parent' and follow
 * to the 'parent' in the XML-structure:
 * e.g. if the XML-list is P, PM, PL, PLA, PLB, PI
 * then PM, PL and PI are one level below P – they are subtasks of P.
 * PLA and PLB are on level below PL – they are subtasks of PL.
 * Creating such a tree-structure in the GUI-element Jtree allows users
 * to show or hide all selectable code belonging to a lower level. */
    private DefaultMutableTreeNode buildSubTree() {
/*
 * ----- Variables ----- */
/* At the end of the method this 'tree' contains the sub-structure (all levels down). */
      DefaultMutableTreeNode structTaskTree;
/* XML-element with all information (elements) for one task. */
      Element elementTask;
/* XML-element with the <DisplayedCode>; that is the one the user can choose
 * and that letters decide about grouping. */
      Element elementDisplayedCode;
/* Text of the <DisplayedCode> the global index was pointing when this method was entered.
 * Used to compare if following <DisplayedCode>s are SubTasks. */
      String strDisplayedCodeWhenMethodEntered = "";
/* Text of inspected <DisplayedCode>; i.e. where the global index is actually pointing. */
      String strDisplayedCodeAtActualIndex = "";
/*
 * ----- Begin of Code ----- */
/* Create the top-element of the tree-structure created within this method.
 * The displayed text is build by the subroutine buildTaskText(). */
      structTaskTree = new DefaultMutableTreeNode(buildTaskText());
/* 
 * Keep the text of <DisplayedCode> to compare later if following XML-elements in the
 * list are SubTasks. */
      elementTask = (Element) (listTasks.get(intListTasksIndex));
      elementDisplayedCode = elementTask.getChild("DisplayedCode");
      strDisplayedCodeWhenMethodEntered = elementDisplayedCode.getTextTrim();
/* 
 * Inspect the next XML-Element(s) in the list if they are Sub-Tasks. */
      while (intListTasksIndex < intListTasksSize - 1) {
        elementTask = (Element) (listTasks.get(intListTasksIndex));
        elementDisplayedCode = elementTask.getChild("DisplayedCode");
        strDisplayedCodeWhenMethodEntered = elementDisplayedCode.getTextTrim();
/* 
 * See if the <DisplayedCode> of the next XML-element in the list starts with the
 * same letter as the <DisPlayedCode> that was stored when this method was entered. */
        if (strDisplayedCodeAtActualIndex.indexOf(strDisplayedCodeWhenMethodEntered) == 0) {
/* Starts with the same letter(s); so must be a SubTask.
 * Call this method as a subroutine (this does an inspection if there are Sub-SubTask
 * and builds the tree-structure if there are).
 * Then add the complete tree-structure build by the subroutine to the tree-structure
 * that is build in this method. */
          intListTasksIndex++;
          structTaskTree.add(buildSubTree());
        }
        else {
/* <DisplayedCode> in the next XML-element of the list does not start with the same letter(s):
 * Building of this Sub-Tree-structure is completed. */
          return structTaskTree;
        }
      }
/* 
 * Return the tree-structure build in this method if there are no more XML-elements in the list. */
      return structTaskTree;
    }
/*
 * ************************************************** */
/*
 * Method to build a string with the text to be displayed.
 * The built String is a concatenation of the following:
 * value of <DisplayedCode>, " - " (Dash as a constant value) and value of <Description>. */
    private String buildTaskText() {
/*
 * ----- Variables ----- */
/* XML-element with all information (elements) for one task. */
      Element elementTask;
/* Multiple used XML-element to get various sub-elements of a Task-element. */
      Element elementMultiUsed;
/* Text of the <DisplayedCode>. */
      String strDisplayedCode;
/* Text with the (longer) description of the Task; value of <Description>. */
      String strDescription;
/*
 * ----- Begin of Code ----- */
/* Get the XML-element of the list where the global index is pointing at. */
      elementTask = (Element) (listTasks.get(intListTasksIndex));
/* Get the values that are needed for the string to be displayed. */
      elementMultiUsed = elementTask.getChild("DisplayedCode");
      strDisplayedCode = elementMultiUsed.getTextTrim();
      elementMultiUsed = elementTask.getChild("Description");
      strDescription = elementMultiUsed.getTextTrim();
/*
 * Check if the <DisplayedCode> should be shown in UpperCase. */
      if (bolUpperCase) {
        return strDisplayedCode.toUpperCase() + " - " + strDescription;
      }
      else {
        return strDisplayedCode + " - " + strDescription;
      }
    }
/*
 * ************************************************** */
/*
 * Method to check if a Code (passed as parameter) is a valid <DisplayedCode>. */
    public boolean isValidDisplayedCode(String parmDisplayedCode) {
/*
 * ----- Variables ----- */
/* XML-element with all information (elements) for one task. */
      Element elementTask;
/* Multiple used XML-element to get various sub-elements of a Task-element. */
      Element elementMultiUsed;
/* Text of the <DisplayedCode>. */
      String strDisplayedCode;
/*
 * ----- Begin of Code ----- */
/* 
 * Check if there is at least one Element for a Task in the XML-structure. */
      Element ElementTask = XML_RootElement.getChild("Task");
      if (ElementTask == null) {
        StatusCode = CONST_NO_TASK_ELEMENT_PRESENT;
        return false;
      }
/* 
 * Get the list with all Task-elements out of the XML-structure
 * for further comparison if one has the searched <DisplayedCode>. */
      listTasks = XML_RootElement.getChildren("Task");
      intListTasksSize = listTasks.size();
/* 
 * Inspect the XML-element(s) in the list if they have the requested <DisplayedCode>. */
      for (intListTasksIndex = 0; intListTasksIndex < intListTasksSize; intListTasksIndex++) {
        elementTask = (Element) (listTasks.get(intListTasksIndex));
        elementMultiUsed = elementTask.getChild("DisplayedCode");
        strDisplayedCode = elementMultiUsed.getTextTrim();
/* 
 * Compare if the <DisplayedCode> of the inspected <Task> is the same as the searched one.
 * The comparison depends on the <UpperCase> element of the XML-structure. */
        if ( (strDisplayedCode.compareTo(parmDisplayedCode.trim()) == 0)
            || (bolUpperCase && (strDisplayedCode.compareToIgnoreCase(parmDisplayedCode.trim()) == 0))
           ) {
          StatusCode = CONST_OK;
          return true;
        }
      }
/* 
 * Task with the requested <DisplayedCode> not found; return error. */
      StatusCode = CONST_NO_TASK_ELEMENT_PRESENT;
      return false;
    }
/*
 * ************************************************** */
/*
 * Method to get the user-entered code out of a JTextField,
 * find the fitting <InternalCode> in the XML-structure,
 * set the text of the JLabels for the parameter-entry and
 * enable/disable the JTextFields for parameter-entry
 * according to the definitions in the XML-structure. */
    public String processParameterFields(JTextField parmtxtCode,
               JLabel parmlblParameter1, JTextField parmtxtParameter1,
               JLabel parmlblParameter2, JTextField parmtxtParameter2,
               JLabel parmlblParameter3, JTextField parmtxtParameter3) {
/*
 * ----- Variables ----- */
/* XML-element with all information (elements) for one task. */
      Element elementTask;
/* Multiple used XML-element to get various sub-elements of a Task-element. */
      Element elementMultiUsed;
/* Text of the <DisplayedCode> (in the XML-structure). */
      String strDisplayedCode;
/* User entered code; 'Text' of the parameter parmtxtCode;
 * to be compared with <DisplayedCode> (in of the XML-structure). */
      String strSelectedCode = parmtxtCode.getText().trim();
/*
 * ----- Begin of Code ----- */
/* 
 * Check if there is at least one Element for a Task in the XML-structure. */
      Element ElementTask = XML_RootElement.getChild("Task");
      if (ElementTask == null) {
        StatusCode = CONST_NO_TASK_ELEMENT_PRESENT;
/* If there were JLabel-elements passed: set the text of them to 'empty String'. */
        if (parmlblParameter1 != null) parmlblParameter1.setText("");
        if (parmlblParameter2 != null) parmlblParameter2.setText("");
        if (parmlblParameter3 != null) parmlblParameter3.setText("");
/* If there were JTextField-elements passed: set themto 'disabled'. */
        if (parmtxtParameter1 != null) parmtxtParameter1.setEnabled(false);
        if (parmtxtParameter2 != null) parmtxtParameter2.setEnabled(false);
        if (parmtxtParameter3 != null) parmtxtParameter3.setEnabled(false);
        return "";
      }
/* 
 * Get the list with all Task-elements out of the XML-structure
 * for further comparison if one of them is the requested one. */
      listTasks = XML_RootElement.getChildren("Task");
      intListTasksSize = listTasks.size();
/* 
 * Inspect the XML-element(s) in the list if they have the requested <DisplayedCode>. */
      for (intListTasksIndex = 0; intListTasksIndex < intListTasksSize; intListTasksIndex++) {
        elementTask = (Element) (listTasks.get(intListTasksIndex));
        elementMultiUsed = elementTask.getChild("DisplayedCode");
        strDisplayedCode = elementMultiUsed.getTextTrim();
/* 
 * Compare if the <DisplayedCode> of the inspected <Task> is the same as the searched one.
 * The comparison depends on the <UpperCase> element of the XML-structure. */
        if ( (strDisplayedCode.compareTo(strSelectedCode.trim()) == 0)
            || (bolUpperCase && (strDisplayedCode.compareToIgnoreCase(strSelectedCode.trim()) == 0))
           ) {
/* Matching <Task> element found; derive the parameter-values and the <InternalCode>. */
          StatusCode = CONST_OK;
/* Transfer the Text for the 'Parameter'-labels and
 * enable/disable the 'Parameter'-JTextFields. But only, if they were passed (not 'null'). */
/* Do this for <Parameter1>. */
          elementMultiUsed = elementTask.getChild("Parameter1");
          if (elementMultiUsed == null) {
/* No element for <Parameter1> defined; set empty String to label and disable text-field. */
            if (parmlblParameter1 != null) parmlblParameter1.setText("");
            if (parmtxtParameter1 != null) parmtxtParameter1.setEnabled(false);
          }
          else {
            if (parmlblParameter1 != null) parmlblParameter1.setText(elementMultiUsed.getTextTrim());
            if (parmtxtParameter1 != null) parmtxtParameter1.setEnabled(true);
          }
/* Do the processing for <Parameter2>. */
          elementMultiUsed = elementTask.getChild("Parameter2");
          if (elementMultiUsed == null) {
            if (parmlblParameter2 != null) parmlblParameter2.setText("");
            if (parmtxtParameter2 != null) parmtxtParameter2.setEnabled(false);
          }
          else {
            if (parmlblParameter2 != null) parmlblParameter2.setText(elementMultiUsed.getTextTrim());
            if (parmtxtParameter2 != null) parmtxtParameter2.setEnabled(true);
          }
/* Do the processing for <Parameter3>. */
          elementMultiUsed = elementTask.getChild("Parameter3");
          if (elementMultiUsed == null) {
            if (parmlblParameter3 != null) parmlblParameter3.setText("");
            if (parmtxtParameter3 != null) parmtxtParameter3.setEnabled(false);
          }
          else {
            if (parmlblParameter3 != null) parmlblParameter3.setText(elementMultiUsed.getTextTrim());
            if (parmtxtParameter3 != null) parmtxtParameter3.setEnabled(true);
          }
/* Derive the <InternalCode> an d return the value.. */
          elementMultiUsed = elementTask.getChild("InternalCode");
          if (elementMultiUsed != null) return elementMultiUsed.getTextTrim();
          else return "";
        }
      }
/* 
 * Task with the requested <DisplayedCode> not found; return error. */
      StatusCode = CONST_NO_TASK_ELEMENT_PRESENT;
/* If there were JLabel-elements passed: set the text of them to 'empty String'. */
      if (parmlblParameter1 != null) parmlblParameter1.setText("");
      if (parmlblParameter2 != null) parmlblParameter2.setText("");
      if (parmlblParameter3 != null) parmlblParameter3.setText("");
/* If there were JTextField-elements passed: set themto 'disabled'. */
      if (parmtxtParameter1 != null) parmtxtParameter1.setEnabled(false);
      if (parmtxtParameter2 != null) parmtxtParameter2.setEnabled(false);
      if (parmtxtParameter3 != null) parmtxtParameter3.setEnabled(false);
      return "";
    }
/*
 * ************************************************** */
/*
 * Method to get the <DisplayedCode> for an <InternalCode> (passed as parameter). */
    public String getDisplayedCode(String parmInternalCode) {
/*
 * ----- Variables ----- */
/* XML-element with all information (elements) for one task. */
      Element elementTask;
/* Multiple used XML-element to get various sub-elements of a Task-element. */
      Element elementMultiUsed;
/* Text of the <InternalCode>. */
      String strInternalCode;
/* Text of the <DisplayedCode>. */
      String strDisplayedCode;
/*
 * ----- Begin of Code ----- */
/* 
 * Check if there is at least one Element for a Task in the XML-structure. */
      Element ElementTask = XML_RootElement.getChild("Task");
      if (ElementTask == null) {
        StatusCode = CONST_NO_TASK_ELEMENT_PRESENT;
        return "";
      }
/* 
 * Get the list with all Task-elements out of the XML-structure
 * for further comparison if one has the searched <DisplayedCode>. */
      listTasks = XML_RootElement.getChildren("Task");
      intListTasksSize = listTasks.size();
/* 
 * Inspect the XML-element(s) in the list if they have the requested <InternalCode>. */
      for (intListTasksIndex = 0; intListTasksIndex < intListTasksSize; intListTasksIndex++) {
        elementTask = (Element) (listTasks.get(intListTasksIndex));
        elementMultiUsed = elementTask.getChild("InternalCode");
/* 
 * Verify if there is an <InternalCode> defined with this element.
 * There are elements that just have the function as 'branches' without starting a 'task'. */
        if ( elementMultiUsed == null) continue;
        strInternalCode = elementMultiUsed.getTextTrim();
/* 
 * Compare if the <InternalCode> of the inspected <Task> is the same as the searched one.
 * The comparison depends on the <UpperCase> element of the XML-structure. */
        if ( (strInternalCode.compareTo(parmInternalCode.trim()) == 0)
            || (bolUpperCase && (strInternalCode.compareToIgnoreCase(parmInternalCode.trim()) == 0))
           ) {
          StatusCode = CONST_OK;
/* Task with the requested <InternalCode> found; derive <DisplayedCode>. */
          elementMultiUsed = elementTask.getChild("DisplayedCode");
          strDisplayedCode = elementMultiUsed.getTextTrim();
/* If the codes should be in upper-case only then transform the <DisplayedCode> now. */
          if (bolUpperCase) strDisplayedCode = strDisplayedCode.toUpperCase();
          return strDisplayedCode;
        }
      }
/* 
 * Task with the requested <DisplayedCode> not found; return error. */
      StatusCode = CONST_NO_TASK_ELEMENT_PRESENT;
      return "";
    }
/*
 * ************************************************** */
/*
 * Method to get the text out of a GUI-element of type JTextField.
 * The text is only returned if the JTextField is 'enabled'.
 * This method allows not to pass entered text in parameter-fields that are not
 * used for a certain Code and therefore the JTextField was disabled. */
    public static String filterParameterField(JTextField parmtxtParameter) {
/*
 * ----- Variables ----- */
/*
 * ----- Begin of Code ----- */
      if (parmtxtParameter.isEnabled()) return parmtxtParameter.getText();
      else return "";
    }
}