source: trunk/gli/src/org/greenstone/gatherer/cdm/Argument.java@ 4366

/**
 *#########################################################################
 *
 * A component of the Gatherer application, part of the Greenstone digital
 * library suite from the New Zealand Digital Library Project at the
 * University of Waikato, New Zealand.
 *
 * <BR><BR>
 *
 * Author: John Thompson, Greenstone Digital Library, University of Waikato
 *
 * <BR><BR>
 *
 * Copyright (C) 1999 New Zealand Digital Library Project
 *
 * <BR><BR>
 *
 * 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
 * (at your option) any later version.
 *
 * <BR><BR>
 *
 * 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.
 *
 * <BR><BR>
 *
 * 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., 675 Mass Ave, Cambridge, MA 02139, USA.
 *########################################################################
 */

 




/* GPL_HEADER */
package org.greenstone.gatherer.cdm;
/**************************************************************************************
 * Title:        Gatherer
 * Description:  The Gatherer: a tool for gathering and enriching a digital collection.
 * Company:      The University of Waikato
 * Written:      01/05/02
 * Revised:      16/08/02 Optimized and Commented.
 **************************************************************************************/
import java.io.Serializable;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.HashMap;
/** This class contains all the details about a single argument that can be passed to this plugin, including option lists if the parameters are restricted.
 * @author John Thompson, Greenstone Digital Library, University of Waikato
 * @version 2.3
 */

// ####################################################################################
// Optimization                          Saving
// ####################################################################################
// Vector -> ArrayList                   + Memory, + Processor (pos. - Processor)
// Hashtable -> HashMap                  + Processor
// int -> byte (x7)                      + Memory (168b)
// External method calls                 + Memory, Processor
// ####################################################################################

public class Argument
    implements Comparable, Serializable {
    /** If this argument has multiple values, then they are stored here. This was originally a Hashtable, but since the synchronization overhead is unwarrented it was changed to a HashMap. */
    private ArrayList values = null;
    /** <i>true</i> if this argument is required for the applicable script to work properly, <i>false</i> otherwise. */
    private boolean required = false;
    /** The type of this argument. Initially an int, but bytes are cheaper. */
    private byte type = FLAG;
    /** If the argument is of type ENUM then this map holds all the various options. Each entry is an &lt;option value&gt; -&gt; &lt;description&gt; mapping. */
    private HashMap list = null;
    /** A default value for parameter-type arguments. May be a Perl pattern. */
    private String default_value = null;
    /** The text description of this argument parsed from the pluginfo output. */
    private String desc = null;
    /** The argument flag as it appears in the command. Also used as the unique identifier of an argument. */
    private String name = null;
    /** The plugin that owns this argument, for the purposes of visualising inheritance. */
    private String owner = null;
    /** If this argument has been assigned, what is its value. Must be non-null for the argument to be printed. */
    private String value = null;
    /** An element of the argument type enumeration. */
    static final public byte ENUM = 0;
    /** An element of the argument type enumeration. */
    static final public byte FLAG = 1;
    /** An element of the argument type enumeration. */
    static final public byte HIERARCHY = 2;
    /** An element of the argument type enumeration. */
    static final public byte INTEGER = 3;
    /** An element of the argument type enumeration. */
    static final public byte LANGUAGE = 4;
    /** An element of the argument type enumeration. */
    static final public byte METADATA = 5;
    /** An element of the argument type enumeration. */
    static final public byte METADATUM = 6;
    /** An element of the argument type enumeration. */
    static final public byte STRING = 7;
    /** Default Constructor. */
    public Argument() {
    }
    /** Normal Constructor, based on data parsed from an information script.
      * @param name The argument flag as it appears in the command, as a <strong>String</strong>. Also used as the unique identifier of an argument.
      * @param desc The text description of this argument parsed from the output as a <strong>String</strong>.
      * @param type The type of this argument as a <i>byte</i>.
      * @param default_value The default value for a parameter type argument, which may include a Perl type regular expression, as a <strong>String</strong>.
      */
    public Argument(String name, String desc, byte type, String default_value) {
    this.default_value = default_value;
    this.desc = desc;
    this.name = name;
    this.type = type;
    if(type == ENUM) {
        this.list = new HashMap();
    }
    if(type == METADATUM) {
        values = new ArrayList();
    }
    }
    /** Method to add an element to the option list.
      * @param name The name value of the option as a <strong>String</strong>.
      * @param desc The description of this options as a <strong>String</strong>.
      */
    public void addOption(String name, String desc) {
    if(type == ENUM && name != null) {
        if(desc == null) {
        desc = "";
        }
        if(!list.containsKey(name)) {
        list.put(name, desc);
        }
    }
    }
    /** Method to compare two arguments for ordering.
      * @param object The argument we are comparing to, as an <strong>Object</strong>.
      * @return An <i>int</i> specifying the argument order, using values as set out in String.
      * @see java.lang.String#compareTo
      * @see org.greenstone.gatherer.cdm.Argument
      */
    public int compareTo(Object object) {
    Argument argument = (Argument)object;
    return getName().compareTo(argument.getName());
    }
    /** Method to deep copy this argument.
      * @return A newly created <strong>Argument</strong> which has the same details as this one.
      */
    public Argument copy() {
    Argument copy = new Argument(name, desc, type, default_value);
    copy.setRequired(required);
    if(values != null) {
        copy.setValues(values);
    }
    if(list != null) {
        HashMap list_deep_copy = new HashMap();
        Iterator it = list.keySet().iterator();
        while(it.hasNext()) {
        String key = (String) it.next();
        String desc = (String) list.get(key);
        list_deep_copy.put(new String(key), new String(desc));
        }
        copy.setOptions(list_deep_copy);
    }
    return copy;
    }
    /** Method to determine if two arguments are equal.
      * @param object The argument to test against, as an <strong>Object</strong>.
      * @return <i>true</i> if the arguments names match, <i>false</i> otherwise.
      */
    public boolean equals(Object object) {
    return (compareTo(object) == 0);
    }
    /** Method to retrieve the value of default_value.
      * @return A <strong>String</strong> containing the default value.
      */
    public String getDefaultValue() {
    return default_value;
    }
    /** Method to retrieve this arguments description.
      * @return A <strong>String</strong> containing the description.
      */
    public String getDesc() {
    return desc;
    }
    /** Method to retrieve the description of a certain list option value.
      * @param key The <strong>String</strong> whose description we are searching for.
      * @return The description of the desired key as a <strong>String</strong> which may be empty if no such key exists.
      */
    public String getDesc(String key) {
    if(list.containsKey(key)) {
        return (String)list.get(key);
    }
    return "";
    }
    /** Method to retrieve the option list for this argument.
      * @return A <strong>HashMap</strong> containing &lt;option value&gt; -&gt; &lt;description&gt; entries.
      */
    public HashMap getList() {
    return list;
    }
    /** Method to retrieve the value of name.
      * @return A <strong>String</strong> containing the argument name.
      */
    public String getName() {
    return name;
    }
    /** Retrieve the name of the owner of this argument.
      * @return The owners name as a <strong>String</strong>.
      */
    public String getOwner() {
    return owner;
    }
    /** Method to determine the type of this argument.
      * @return An <i>byte</i> specifying the type.
      */
    public byte getType() {
    return type;
    }
    /** Method to retrieve the value of value.
      * @return The value of value as a <strong>String</strong>.
      */
    public String getValue() {
    return value;
    }
    /** Retrieve the vector of values.
      * @return An <strong>ArrayList</strong> of values.
      */
    public ArrayList getValues() {
    return values;
    }
    /** Method to determine if this argument has been assigned.
      * @return <i>true</i> if it has, <i>false</i> otherwise.
      */
    public boolean isAssigned() {
    return (required || value != null || (values != null && values.size() > 0));
    }
    /** Method to determine of this argument is required for the associated script to work.
      * @return <i>true</i> if this argument is required, <i>false</i> otherwise.
      */
    public boolean isRequired() {
    return required;
    }
    /** Method to allow for the activation of arguments that might never have their setValue() method called.
      * @param new_state The required state as a <i>boolean</i>.
      */
    public void setAssigned(boolean new_state) {
    if(new_state && (value == null || values == null)) {
        value = "";
    }
    else {
        value = null;
    }
    }
    /** Sets the value of default_value.
      * @param new_default_value The new value for default_value as a <strong>String</strong>.
      */
    public void setDefault(String new_default_value) {
    default_value = new_default_value;
    }
    /** Set the value of desc.
      * @param new_desc The new value of desc as a <strong>String</strong>.
      */
    public void setDesc(String new_desc) {
    desc = new_desc;
    }
    /** Set the value of name.
      * @param new_name The new value of name as a <strong>String</strong>.
      */
    public void setName(String new_name) {
    name = new_name;
    }
    /** Sets the value of the options list.
      * @param new_list The new options list as a <strong>HashMap</strong>.
      */
    public void setOptions(HashMap new_list) {
    list = new_list;
    }
    /** Set the owner of this argument.
      * @param owner The name of the owner of this argument as a <strong>String</strong>.
      */
    public void setOwner(String owner) {
    this.owner = owner;
    }
    /** Set the value of required.
      * @param new_required The new value of required as a <i>boolean</i>.
      */
    public void setRequired(boolean new_required) {
    required = new_required;
    }
    /** Set the value of type.
      * @param new_type The new value of type as an <i>byte</i>.
      */
    public void setType(byte new_type) {
    type = new_type;
    if(type == ENUM) {
        list = new HashMap();
    }
    if(type == METADATUM && values == null) {
        values = new ArrayList();
    }
    }
    /** Set the value of type, by matching a type to the given string.
      * @param new_type A <strong>String</strong> which contains the name of a certain argument type.
      */
    public void setType(String new_type) {
    if(new_type.equalsIgnoreCase("enum")) {
        this.type = ENUM;
        list = new HashMap();
    }
    else if(new_type.equalsIgnoreCase("flag")) {
        this.type = FLAG;
    }
    else if(new_type.equalsIgnoreCase("hierarchy")) {
        this.type = HIERARCHY;
    }
    else if(new_type.equalsIgnoreCase("int")) {
        this.type = INTEGER;
    }
    else if(new_type.equalsIgnoreCase("language")) {
        this.type = LANGUAGE;
    }
    else if(new_type.equalsIgnoreCase("metadata")) {
        this.type = METADATA;
    }
    else if(new_type.equalsIgnoreCase("metadatum")) {
        this.type = METADATUM;
        if(values == null) {
        values = new ArrayList();
        }
    }
    else if(new_type.equalsIgnoreCase("string")) {
        this.type = STRING;
    }
    }
    /** Method to set the value of value.
      * @param new_value The new value of value as a <strong>String</strong>.
      */
    public void setValue(String new_value) {
    this.value = new_value;
    }
    /** Set the values vector to the given values. Currently I just assign the new values, whereas I may later want to implement a deep clone.
      * @param new_values An <strong>ArrayList</strong> of values.
      */
    public void setValues(ArrayList new_values) {
    values = new_values;
    }
    /** Method for translating the data of this class into a string.
      * @return A <strong>String</strong> containing a fragment of the total arguments string.
      */
    public String toString() {
    switch(type) {
    case FLAG:
        return "-" + name;
    case METADATUM:
        String text = "-" + name + " ";
        for(int i = 0; i < values.size(); i++) {
        text = text + values.get(i).toString();
        if(i < values.size() - 1) {
            text = text + ",";
        }
        }
        return text;
    default:
        return "-" + name + " " + value;
    }
    }
}