/**
 *#########################################################################
 *
 * 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;
	}
    }
}