source: trunk/gli/src/org/greenstone/gatherer/cdm/Plugin.java@ 9019

/**
 *#########################################################################
 *
 * 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.
 *
 * Author: John Thompson, Greenstone Digital Library, University of Waikato
 *
 * Copyright (C) 1999 New Zealand Digital Library Project
 *
 * 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.
 *
 * 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., 675 Mass Ave, Cambridge, MA 02139, USA.
 *########################################################################
 */
package org.greenstone.gatherer.cdm;

import java.io.*;
import java.util.*;
import org.greenstone.gatherer.util.StaticStrings;
import org.w3c.dom.*;

/** This class is responsible for storing information from a parsed pluginfo call in such a way that it allows easy access to parsed details for the purposes of user design and specification of plugins. */
public class Plugin
    extends ArrayList
    implements ArgumentContainer, Comparable, DOMProxyListEntry, Serializable {
    /** The DOM Element this assigned Plugin is modelled on. */
    private Element element;
    private boolean does_explode_metadata_databases = false; // Only for Base
    private boolean is_abstract = false; // Only for Base
    /** The parent Plugin this one inherits from, if any. */
    private Plugin super_plugin; // Only for Base
    private String description; // Only for Base
    private String name; // Only for Base

    /** Constructor used in DOMProxyListModel initializations, and Library Level. Used for Base plugins (those in the list of available plugins, not ones that are in the DOMProxyList)
     */
    public Plugin() {
    }
    
    /** Constructor used for the plugins that are in the DOMProxyList */
    // Every time the list of plugins in the assigned plugins box changes, (eg plugin added or removed, not when plugin configured), the plugins seem to be regenerated, using the element from the old plugin. All known args get added to the element the first time this happens - we need to add them to the arguments list in the order they are found in the base plugins though, not this order.
    public Plugin(Element element, Plugin base_plugin) {
    super();
    this.element = element;
    this.name = element.getAttribute(StaticStrings.TYPE_ATTRIBUTE);
    //DebugStream.println("Establishing Plugin: " + name);
    // Parse in any argument options for this plugin, keeping a list of the ones found
    HashMap known_arguments = new HashMap();
    NodeList option_elements = element.getElementsByTagName(StaticStrings.OPTION_ELEMENT);
    int option_elements_length = option_elements.getLength();
    for(int i = 0; i < option_elements_length; i++) {
        Element option_element = (Element) option_elements.item(i);
        Argument argument = new Argument(option_element);
        //DebugStream.println("Rebuilding existing argument: " + argument.getName());
        known_arguments.put(argument.getName(), argument);
        if (argument.isAssigned() || base_plugin == null) {
        // if the arg is assigned, the current plugin now becomes its owner, and we add it to the front of the ArrayList of args. But otherwise, it will retain its old owner, and we will add it in the correct place from the base plugin
        argument.setOwner(name);
        add(argument);
        } 
    }
    // If a base plugin was given
    if(base_plugin != null) {
        //DebugStream.println("Based on previous plugin.");
        // Copy the details, and add a reference to whatever base_plugins super plugin is. ?? 
        description = base_plugin.getDescription();
        // Now search through the 'dummy' arguments belonging to the base plugin. For each found, if it is already assigned, fill out further details such as type. If any are found that are not already assigned for this plugin, copy them and add them, but without a value.
        ArrayList all_arguments = base_plugin.getArguments(true, true);
        int argument_count = all_arguments.size();
        for(int j = 0; j < argument_count; j++) {
        Argument base_argument = (Argument) all_arguments.get(j);
        String base_argument_name = base_argument.getName();
        //DebugStream.println("Library indicates this plugin should have an argument: " + base_argument_name);
        Argument existing_argument = (Argument) known_arguments.get(base_argument_name);
        // Found an existing argument. Complete its details
        if(existing_argument != null) {
            //DebugStream.println("Found existing argument. Filling out details.");
            existing_argument.setCustomArgument(false);
            existing_argument.setDefaultValue(base_argument.getDefaultValue());
            existing_argument.setDescription(base_argument.getDescription());
            existing_argument.setOptions(base_argument.getOptions());
            existing_argument.setRequired(base_argument.isRequired());
            existing_argument.setType(base_argument.getType());
            existing_argument.setMinimum(base_argument.getMinimum());
            existing_argument.setMaximum(base_argument.getMaximum());
            if (!existing_argument.isAssigned()) {
            // here we give it back its original owner and add it to the list. If it is assigned, these two things were done already
            existing_argument.setOwner(base_argument.getOwner());
            add(existing_argument); 
            }
            
        }
        // No existing argument. Copy base_argument and add it, but do not set its assigned flag. That should be set the first time its changed by the user.
        else {
            //DebugStream.println("No such argument. Adding new, unassigned, argument.");
            // The trick thing is that we have to create a new element in the DOM as well.
            Argument new_argument = base_argument.copy();
            Element argument_element = CollectionDesignManager.collect_config.document.createElement(StaticStrings.OPTION_ELEMENT);
            argument_element.setAttribute(StaticStrings.NAME_ATTRIBUTE, base_argument_name);
            argument_element.setAttribute(StaticStrings.ASSIGNED_ATTRIBUTE, StaticStrings.FALSE_STR);
            argument_element.setAttribute(StaticStrings.CUSTOM_ATTRIBUTE, StaticStrings.FALSE_STR);
            new_argument.setElement(argument_element);
            // All done. Add it.
            // if we are not in the first collection opened, then this 
            /// will belong to a different document, so need to import 
            // it.
            element.appendChild(element.getOwnerDocument().importNode(argument_element, true));
            add(new_argument);
        }
        }
    }
    }

    /** Method to add an argument to this base plugin. Only adds the argument if it isn't already present, and only if this is a base plugin (ie not based on DOM).
     * @param argument the Argument to add
     */
    public void addArgument(Argument argument) {
    if(element == null && !contains(argument)) {
        add(argument);
        argument.setOwner(name);
    }
    }

    /** Method to compare two plugins for ordering.
     * @param object The plugin we are comparing to, as an <strong>Object</strong>.
     * @return An <i>int</i> specifying the plugin order, using values as set out in <strong>String</strong>.
     * @see java.lang.String#compareTo
     */
    public int compareTo(Object object) {
    if(object instanceof Plugin) {
        return name.compareTo(((Plugin)object).getName());
    }
    return -1;
    }

    /** The assigned plugin constructor.
     * @param element the DOM Element this plugin is based upon
     */
    public DOMProxyListEntry create(Element element) {
    String plugin_name = element.getAttribute(StaticStrings.TYPE_ATTRIBUTE);
    // Determine the base plugin from the plugin name
    Plugin base_plugin = CollectionDesignManager.plugin_manager.getBasePlugin(plugin_name);
    Plugin plugin = new Plugin(element, base_plugin);
    base_plugin = null;
    plugin_name = null;
    return plugin;
    }


    /** Checks whether the plugin this instance is based on processes metadata databases that can be exploded. */
    public boolean doesExplodeMetadataDatabases()
    {
    return false;
    // Plugin base_plugin = CollectionDesignManager.plugin_manager.getBasePlugin(getName());
    // return base_plugin.does_explode_metadata_databases;
    }


    /** Checks whether this plugin instance will process the specified file (given its process_exp and block_exp). */
    public boolean doesProcessFile(File file)
    {
    // Check the filename against the plugin's process_exp and block_exp values
    ArrayList arguments = getArguments(true, true);
    for (int i = 0; i < arguments.size(); i++) {
        Argument argument = (Argument) arguments.get(i);
        if (argument.getName().equals("process_exp") || argument.getName().equals("block_exp")) {
        // Try the assigned value first, for when the user has manually set the value
        String regular_expression = argument.getValue();
        if (regular_expression == null || regular_expression.equals("")) {
            // Not set, so use the default value
            regular_expression = argument.getDefaultValue();
            if (regular_expression.equals("")) {
            continue;
            }
        }

        // The $ at the end doesn't seem to work in Java, so need to add ".*" at the start
        if (regular_expression.startsWith("(?i)")) {
            // Don't mess up case-insensitive matching though
            regular_expression = "(?i)" + ".*" + regular_expression.substring("(?i)".length());
        }
        else {
            regular_expression = ".*" + regular_expression;
        }

        // If the filename matches the regular expression, this plugin will deal with the file in some way
        if (file.getName().matches(regular_expression)) {
            return true;
        }
        }
    }

    // This plugin will (probably) not deal with the specified file
    return false;
    }


    /** Method to determine if two plugins are equal.
     * @param object The plugin to test against, as an <strong>Object</strong>.
     * @return <i>true</i> if the plugin names match, <i>false</i> otherwise.
     */
    public boolean equals(Object object) {
    return (compareTo(object) == 0);
    }

    /** Method to retrieve an argument by its name.
     * @param name The name of the argument as a <strong>String</strong>.
     * @return The <strong>Argument</strong> requested, or <i>null</i> if no such argument.
     */
    public Argument getArgument(String name) {
    // The name given may still include the '-'
    if(name.startsWith("-")) {
        name = name.substring(1);
    }
    ArrayList arguments = getArguments(true, true);
    for(int i = 0; i < arguments.size(); i++) {
        Argument argument = (Argument)arguments.get(i);
        if(argument.getName().equals(name)) {
        return argument;
        }
    }
    return null;
    }

    /** Retrieve all of the arguments available to this base plugin, including its super plugins arguments. Some complexity is added by allowing the caller to choose whether they want normal arguments, custom arguments, or both.
     * @return an ArrayList of all of the arguments, starting with those for this plugin and ending with the arguments for basplug or similiar root plugin
     */
    public ArrayList getArguments(boolean include_normal, boolean include_custom) {
    ArrayList arguments = new ArrayList();
    if(include_normal && include_custom) {
        arguments.addAll(this);
    }
    else {
        int size = size();
        for(int i = 0; i < size; i++) {
        Argument argument = (Argument) get(i);
        if(argument.isCustomArgument()) {
            if(include_custom && !arguments.contains(argument)) {
            arguments.add(argument);
            }
        }
        else {
            if(include_normal && !arguments.contains(argument)) {
            arguments.add(argument);
            }
        }
        argument = null;
        }
    }
    if(super_plugin != null) {
        ArrayList remainder = super_plugin.getArguments(include_normal, include_custom);
        remainder.removeAll(arguments);
        arguments.addAll(remainder);
    }
    return arguments;
    }

    /** Method to retrieve a plugins custom argument information. Custom arguments are defined to be those that have not got matching arguments in the base reference plugin from the library. Of course if there is no base plugin then all arguments are considered to be custom.
     * @return the custom arguments as a String
     */
    public String getCustom() {
    StringBuffer custom_text = new StringBuffer();
    // Retrieve all of the arguments, and append any that are custom into one long string
    ArrayList arguments = getArguments(false, true);
    int arguments_size = arguments.size();
    boolean first = true;
    for(int i = 0; i < arguments_size; i++) {
        Argument argument = (Argument) arguments.get(i);
        if(argument.isAssigned()) {
        if(!first) {
            custom_text.append(" ");
        }
        custom_text.append(argument.toString());
        first = false;
        }
    }
    return custom_text.toString();
    }

    public String getDescription() {
    return description;
    }

    public Element getElement() {
    return element;
    }

    /** Method to retrieve a plugins name.
     * @return A <strong>String</strong> containing the plugins name.
     */
    public String getName() {
    if(name == null && element != null) {
        name = element.getAttribute(StaticStrings.TYPE_ATTRIBUTE);
    }
    return name;
    }

    public boolean isAbstract() {
    return is_abstract;
    }

    public boolean isAssigned() {
    return (element != null && !element.getAttribute(CollectionConfiguration.ASSIGNED_ATTRIBUTE).equals(CollectionConfiguration.FALSE_STR));
    }

    public boolean isSeparator() {
    return (element != null && element.getAttribute(StaticStrings.SEPARATOR_ATTRIBUTE).equals(StaticStrings.TRUE_STR));
    }

    public void setAssigned(boolean assigned) {
    if(element != null) {
        element.setAttribute(CollectionConfiguration.ASSIGNED_ATTRIBUTE, (assigned ? CollectionConfiguration.TRUE_STR : CollectionConfiguration.FALSE_STR));
    }
    }

    /** Set the custom arguments. This turns out to be quite tricky. We must parse in the string, searching for arguments (for that we use a handy method in CollectionConfiguration). Next, for each argument, we check if we already know about it. If so we update its value, otherwise we create a new argument and assign it (must assign!).
     * @param custom_str the custom arguments all splodged together in one String
     */
    public void setCustom(String custom_str) {
    HashMap raw_arguments = CollectionConfiguration.parseArguments(new CommandTokenizer(custom_str));
    ArrayList custom_arguments = getArguments(false, true);
    int size = custom_arguments.size();
    for(int i = 0; i < size; i++) {
        Argument argument = (Argument) custom_arguments.get(i);
        String original_argument_name = StaticStrings.MINUS_CHARACTER + argument.getName();
        if(raw_arguments.containsKey(original_argument_name)) {
        // Set as assigned
        argument.setAssigned(true);
        String argument_value = (String)raw_arguments.remove(original_argument_name);
        if(argument_value != null) {
            argument.setValue(argument_value);
            argument_value = null;
        }
        }
        // We've removed it from our custom statement, so unassign
        else {
        argument.setAssigned(false);
        }
        argument = null;
    }
    // Any left over, add to the plugin
    Iterator argument_names = raw_arguments.keySet().iterator();
    while(argument_names.hasNext()) {
        String argument_name = (String) argument_names.next();
        String argument_value = (String) raw_arguments.get(argument_name);
        // The tricky thing is that we have to create a new element in the DOM as well.
        Element argument_element = CollectionDesignManager.collect_config.document.createElement(StaticStrings.OPTION_ELEMENT);
        argument_element.setAttribute(StaticStrings.NAME_ATTRIBUTE, argument_name.substring(1));
        argument_element.setAttribute(StaticStrings.ASSIGNED_ATTRIBUTE, StaticStrings.TRUE_STR);
        argument_element.setAttribute(StaticStrings.CUSTOM_ATTRIBUTE, StaticStrings.TRUE_STR);
        Argument argument = new Argument(argument_element);
        argument_name = null;
        if(argument_value != null) {
        argument.setValue(argument_value);
        argument_value = null;
        }
        // All done. Add it.
        element.appendChild(argument_element);
        add(argument);
        argument_element = null;
    }
    raw_arguments = null;
    }

    /** Method to set the value of desc.
     * @param description The new value of desc as a <strong>String</strong>.
     */
    public void setDescription(String description) {
    this.description = description;
    }

    public void setDoesExplodeMetadataDatabases(boolean does_explode_metadata_databases) {
    this.does_explode_metadata_databases = does_explode_metadata_databases;
    }

    public void setElement(Element element) {
    this.element = element;
    }

    public void setIsAbstract(boolean is_abstract) {
    this.is_abstract = is_abstract;
    }

    /** Method to set the value of name.
     * @param name The new value of name as a <strong>String</strong>.
     */
    public void setName(String name) {
    this.name = name;
    }

    /** Method to set the value of the super_plugin.
     * @param super_plugin The new value of super_plugin as a <strong>Plugin</strong>, or <i>null</i> if this class has no inheritance.
     */
    public void setSuper(Plugin super_plugin) {
    this.super_plugin = super_plugin;
    }

    /** Method to print out this plugin as it would appear as a command within the collection configuration file.
     * @return A <strong>String</strong> containing a single plugin command.
     */
    public String toString() {
    if(element != null) {
        if(name == null) {
        name = element.getAttribute(StaticStrings.TYPE_ATTRIBUTE);
        }
        StringBuffer text = new StringBuffer(StaticStrings.PLUGIN_STR);
        text.append(" ");
        text.append(name);
        text.append(" ");
        ArrayList arguments = getArguments(true, true);
        int arguments_size = arguments.size();
        for(int i = 0; i < arguments_size; i++) {
        Argument argument = (Argument)arguments.get(i);
        if(argument.isAssigned()) {
            text.append(argument.toString());
            text.append(" ");
        }
        argument = null;
        }
        return text.substring(0, text.length() - 1);
    }
    // Basic Plugin
    else {
        return name;
    }
    }
}