source: trunk/gli/src/org/greenstone/gatherer/gems/MSMUtils.java@ 8270

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

/**************************************************************************************
 * Title:        Gatherer
 * Description:  The Gatherer: a tool for gathering and enriching a digital collection.
 * Company:      The University of Waikato
 * Written:        /  /01
 * Revised:      16/08/02 Improved 
 *               06/08/03 Bug fixes
 * @author John Thompson, Greenstone Digital Libraries
 * @version 2.3
 **************************************************************************************/
import java.io.*;
import java.util.*;
import org.greenstone.gatherer.Configuration;
import org.greenstone.gatherer.cdm.CommandTokenizer;
import org.greenstone.gatherer.util.ArrayTools;
import org.greenstone.gatherer.util.StaticStrings;
import org.greenstone.gatherer.util.Utility;
import org.w3c.dom.*;
/** This class contains a plethora of methods associated with handling the content of <strong>MetadataSet</strong>s and the <strong>Element</strong>s within. For example this is where you will find methods for comparing various parts of two <strong>MetadataSet</strong>s for equality. It also has methods for extracting common and useful data from <strong>Element</strong>s such as the AssignedValue nodes.
 * @author John Thompson, Greenstone Digital Libraries
 * @version 2.3
 */
public class MSMUtils {
    /** Used to order metadata according to set standard element order then alphabetically by value. */
    // static private MetadataComparator METADATA_COMPARATOR = new MetadataComparator();
    /** An element of the enumeration of type filter. */
    static public int NONE = 0;
    /** An element of the enumeration of type filter. */
    static public int VALUES = 1;
    /** An element of the enumeration of type filter. */
    static public int ALIASES = 2;
    /** An element of the enumeration of type filter. */
    static public int BOTH = 3;
    /** The character used to separate name space from metadata element. */
    static public char NS_SEP= '.';
    /** The character used to separate subfields from metadata element. */
    static public String SF_SEP= "#";
    /** Method to add one node as a child of another, after migrating into the target document.
     * @param parent The <strong>Node</strong> we are inserting into.
     * @param child The original <strong>Node</strong> we are inserting. Must first be cloned into the parents document.
     */
    static public void add(Node parent, Node child) {
    Document document = parent.getOwnerDocument();
    Node new_child = document.importNode(child, true);
    parent.appendChild(new_child);
    } 

    /** Method to add an attribute element to the given element. This method makes use of the language_dependant attribute of the document to not only determine if the attribute is language dependant, but also to see whether a Language element should be created if doesn't already exist.
     * @param element_element the Element to add the attribute element to
     * @param attribute_name_str the name of the new attribute to add as a String
     * @param language_code_str the two letter code String of the language this attribute is to be added as
     * @param value_str the String to be assigned as the attribute elements value
     * @see org.greenstone.gatherer.msm.MSMUtils#isAttributeLanguageDependant
     * @see org.greenstone.gatherer.msm.MSMUtils#setValue(Element, String)
     * @see org.greenstone.gatherer.util.StaticStrings#ATTRIBUTE_ELEMENT
     * @see org.greenstone.gatherer.util.StaticStrings#CODE_ATTRIBUTE
     * @see org.greenstone.gatherer.util.StaticStrings#LANGUAGE_ATTRIBUTE
     * @see org.greenstone.gatherer.util.StaticStrings#LANGUAGE_ELEMENT
     * @see org.greenstone.gatherer.util.StaticStrings#NAME_ATTRIBUTE
     */ 
    static public void addElementAttribute(Element element_element, String attribute_name_str, String language_code_str, String value_str) {
    Document document = element_element.getOwnerDocument();
    // Create the basic new attribute (everything except language attribute)
    Element attribute_element = document.createElement(StaticStrings.ATTRIBUTE_ELEMENT);
    attribute_element.setAttribute(StaticStrings.NAME_ATTRIBUTE, attribute_name_str);
    MSMUtils.setValue(attribute_element, value_str);
    // Start off by determining if we have to add this node in the new multilingual optimized way
    if(isAttributeLanguageDependant(document, attribute_name_str)) {
        boolean found = false;
        // Try to retrieve a language element for the given language code
        NodeList language_elements = element_element.getElementsByTagName(StaticStrings.LANGUAGE_ELEMENT);
        for(int i = 0; i < language_elements.getLength(); i++) {
        Element language_element = (Element) language_elements.item(i);
        if(language_element.getAttribute(StaticStrings.CODE_ATTRIBUTE).equals(language_code_str)) {
            found = true;
            // Add attribute
            language_element.appendChild(attribute_element);
        }
        language_element = null;
        }
        language_elements = null;
        // If it still hasn't been found, then add it
        if(!found) {
        Element language_element = document.createElement(StaticStrings.LANGUAGE_ELEMENT);
        language_element.setAttribute(StaticStrings.CODE_ATTRIBUTE, language_code_str);
        element_element.appendChild(language_element);
        // Add attribute
        language_element.appendChild(attribute_element);
        language_element = null;
        }
    }
    // Just add the attribute the old fashioned way
    else {
        attribute_element.setAttribute(StaticStrings.LANGUAGE_ATTRIBUTE, language_code_str);
        element_element.appendChild(attribute_element);
    }
    // Clean up
    attribute_element = null;
    document = null;
    }

    /** A method for comparing two AssignedValues trees. This compares not only the Subject hierarchies but also the values themselves.
     * @param avt A <strong>Node</strong> which is the root of an AssignedValues tree.
     * @param bvt The <strong>Node</strong> which is the root of the tree we wish to compare it to.
     * @return <i>true</i> if the two trees are equal, <i>false</i> otherwise.
     */
    static final private boolean assignedValuesEqual(Node avt, Node bvt) {
    if(avt == null && bvt == null) {
        return true; // Both are null so both are equal.
    }
    else if(avt == null || bvt == null) {
                // One is null and the other isn't.
        return false;
    }
    else {
        Hashtable a_map = new Hashtable();
        getValueMappings(avt, null, a_map);
        Hashtable b_map = new Hashtable();
        getValueMappings(bvt, null, b_map);
        if(a_map.size() == b_map.size()) {
        /** @TODO - Figure out what to do now. */
        return true;
        }
    }
    return false;
    }
    /** A method for comparing two attribute nodes of type Node not Attr as you might think. Attr objects are used to describe the attributes of tags themselves, while in a metadata set we intend attribute nodes to describe qualities of metadata elements. It's just confusing because the two systems (DOM model and Dublin Core) are quite similar.
     * @param an A <strong>Node</strong> representing some attribute of an element.
     * @param bn The <strong>Node</strong> we wish to compare it to.
     * @return <i>true</i> if and only if the attributes are equal.
     */
    static final public boolean attributesEqual(Node an, Node bn) {
    // Check we are comparing apples and apples...
    if(an.getNodeName().equals("Attribute") && bn.getNodeName().equals("Attribute")) {
        Element ae = (Element) an;
        Element be = (Element) bn;
                // Ensure we are comparing the same type of attribute.
        if(ae.getAttribute("name").equals(be.getAttribute("name"))) {
        // And finally retrieve and compare the values.
        if(getValue(ae).equals(getValue(be))) {
            // We have a match.
            return true;
        }
        }
    }
    // And if anything goes wrong we can't be dealing with equal attributes.
    return false;
    }

    /** Remove all of the child nodes from a certain node. */
    static final public void clear(Node parent) {
    while(parent.hasChildNodes()) {
        parent.removeChild(parent.getFirstChild());
    }
    }

    /** Method to compare two metadata elements (of type Element, which is bound to get more than a bit confusing) for equality. This test may only check the structural (ie pretty much unchanging) consistancy, or may include the AssignedValue tree as well (which will be different for each collection I'd imagine).
     * @param a_set The <strong>MetadataSet</strong> a comes from.
     * @param ae An <strong>Element</strong>.
     * @param b_set The <strong>MetadataSet</strong> b comes from.
     * @param be The <strong>Element</strong> to compare it to.
     * @param values <i>true</i> if the AssignedValues tree should also be compared, <i>false</i> otherwise.
     * @return <i>true</i> if the elements are equal, <i>false</i> otherwise.
     */
    static final public boolean elementsEqual(MetadataSet a_set, Element ae, MetadataSet b_set, Element be, boolean values) {
    // Compare Element Attr(ibutes) within the DOM, not to be confused with comparing element attributes in a Dublin Core sense...
    NamedNodeMap aas = ae.getAttributes();
    NamedNodeMap bas = be.getAttributes();
    // For each attribute in a...
    for(int i = 0; i < aas.getLength(); i++) {
        Attr aa = (Attr)aas.item(i);
                // Try to retrieve an attribute of the same name from b.
        Attr ba = (Attr)bas.getNamedItem(aa.getNodeName());
                // Now if there was no such attribute, or if the values for the
                // two attributes are different the structures different.
        if(ba == null || (!aa.getValue().equals(ba.getValue()))) {
        //ystem.err.println("Attributes are not equal");
        return false;
        }
    }
    // Quickest test of children is to see we have the same number in
    // each. Remember to modify for missing AssignedValues which have
    // nothing to do with structure.
    int anc = getAttributeCount(ae);
    int bnc = getAttributeCount(be);
    if(anc != bnc) {
        return false;
    }
    // Now we compare the child nodes of the two Elements taking into 
    // account three special cases...
    // 1. We don't test the AssignedValues element here.
    // 2. Remember OptionList node.
    // 3. The Attributes of each metadata element.
    // For each child node of a.
    for(Node an = ae.getFirstChild(); an !=null; an =an.getNextSibling()) {
        if(an.getNodeName().equals("OptionList")) {
        //ystem.err.println("Matching OptionLists.");
        Node bn = getNodeFromNamed(be, "OptionList");
        if(bn == null || !optionListsEqual(an, bn)) {
            //ystem.err.println("OptionLists are not equal");
            return false;
        }
        }
                // Matching attributes.
        else if(an.getNodeName().equals("Attribute")) {
        //ystem.err.println("Matching Attributes.");
        boolean matched = false;
        for(Node bn = be.getFirstChild(); bn != null && !matched;
            bn = bn.getNextSibling()) {
            if(bn.getNodeName().equals("Attribute")) {
            matched = attributesEqual(an, bn);
            }
        }
        if(!matched) {
            //ystem.err.println("Cannot match attribute.");
            return false;
        }
        }
    }
    // Finally, if we've been asked to compares value trees (for some unknown reason) go ahead and compare them too.
    if(values) {
        GValueModel avt = a_set.getValueTree(new ElementWrapper(ae));
        GValueModel bvt = b_set.getValueTree(new ElementWrapper(be));
        return assignedValuesEqual(avt.getDocument().getDocumentElement(), bvt.getDocument().getDocumentElement());
    }
    // If we've got this far the elements match!
    return true;
    }   
    /** This method extracts the assigned value trees details, if any, from a certain element and stores them in an array ready to be passed as arguments to the Dictionary.
     * @param element The <strong>Element</strong> whose values we wish to view.
     * @return A <strong>String[]</strong> containing the details of the assigned values tree.
     * @see org.greenstone.gatherer.Dictionary
     */
    static final public String[] getAssignedValuesDetails(MetadataSet mds, Element element) {
    String details[] = null;
    //Node avt = getNodeFromNamed(element, "AssignedValues");
    GValueModel avt = mds.getValueTree(new ElementWrapper(element));
    if(avt != null) {
        Hashtable mapping = new Hashtable();
        getValueMappings(avt.getDocument().getDocumentElement(), null, mapping);
        ArrayList values = new ArrayList(mapping.keySet());
        Collections.sort(values);
        details = new String[1];
        for(int i = 0; i < values.size(); i++) {
        if(details[0] == null) {
            details[0] = "   " + values.get(i);
        }
        else {
            details[0] = details[0] + "\n   " + values.get(i);
        }
        }
        mapping = null;
        values = null;
    }
    avt = null;
    return details;
    }

    /** Retrieve all of the attributes for the given element as a tree set. Note that this requires significant manipulation if the source is a multilingual optimized metadata set.
     * @param element the Element whose attributes we wish to catalog
     * @return a TreeSet of the attributes sorted by their natural ordering
     * @see org.greenstone.gatherer.msm.MSMUtils#getValue(Node)
     * @see org.greenstone.gatherer.util.StaticStrings#ATTRIBUTE_ELEMENT
     * @see org.greenstone.gatherer.util.StaticStrings#CODE_ATTRIBUTE
     * @see org.greenstone.gatherer.util.StaticStrings#LANGUAGE_ATTRIBUTE
     * @see org.greenstone.gatherer.util.StaticStrings#LANGUAGE_ELEMENT
     * @see org.greenstone.gatherer.util.StaticStrings#NAME_ATTRIBUTE
     */
    static public TreeSet getAttributes(Element element) {
    TreeSet attribute_tree = new TreeSet();
    for(Node node = element.getFirstChild(); node != null; node = node.getNextSibling()) {
        if(node instanceof Element) {
        Element some_element = (Element) node;
        String some_element_name = some_element.getNodeName();
        if(some_element_name.equals(StaticStrings.ATTRIBUTE_ELEMENT)) {
            attribute_tree.add(new Attribute(some_element.getAttribute(StaticStrings.NAME_ATTRIBUTE), some_element.getAttribute(StaticStrings.LANGUAGE_ATTRIBUTE), MSMUtils.getValue(some_element)));
        }
        else if(some_element_name.equals(StaticStrings.LANGUAGE_ELEMENT)) {
            String language_code = some_element.getAttribute(StaticStrings.CODE_ATTRIBUTE);
            NodeList attribute_elements = some_element.getElementsByTagName(StaticStrings.ATTRIBUTE_ELEMENT);
            for(int i = 0; i < attribute_elements.getLength(); i++) {
            Element attribute_element = (Element) attribute_elements.item(i);
            attribute_tree.add(new Attribute(attribute_element.getAttribute(StaticStrings.NAME_ATTRIBUTE), language_code, MSMUtils.getValue(attribute_element)));
            attribute_element = null;
            }
            attribute_elements = null;
            language_code = null;
        }
        some_element_name = null;
        some_element = null;
        }
    }
    return attribute_tree;
    }

    /** Method to count the number of Attribute nodes under a certain Element. This ignores other nodes such as #text, OptionList and AssignedValues nodes.
     * @param element The <strong>Element</strong> whose attributes you want to count.
     * @return An <i>int</i> which is the number of attribute nodes.
     */
    static final private int getAttributeCount(Node element) {
    int count = 0;
    for(Node n = element.getFirstChild(); n != null; 
        n = n.getNextSibling()) {
        if(n.getNodeName().equals("Attribute")) {
        count++;
        }
    }
    return count;
    }

    /** This method is a slight variation on getNodeNamed in that it is especially written to retrieve the attribute Nodes of a certain name present under the given element.
     * @param element The target element <strong>Node</strong>.
     * @param name The name of the attribute you wish to return.
     * @return An <strong>Element[]</strong> containing the attributes you requested, or <i>null</i> if no such attributes exists.
     */
    static final public Element[] getAttributeNodesNamed(Node element, String name) { 
    Element attributes[] = null;
    for(Node n = element.getFirstChild(); n != null; n = n.getNextSibling()) {
        if(n.getNodeName().equals("Attribute")) {
        Element e = (Element)n;
        if(e.getAttribute("name").equals(name)) {
            if(attributes == null) {
            attributes = new Element[1];
            attributes[0] = e;
            }
            else {
            Element temp[] = attributes;
            attributes = new Element[temp.length + 1];
            System.arraycopy(temp, 0, attributes, 0, temp.length);
            attributes[temp.length] = e;
            temp = null;
            }
        }
        e = null;
        }
    }
    return attributes;
    }

    /** Method to construct an elements description by retrieving the correct attribute.
     * @param element the Element whose name we wish to retrieve
     * @return a String which is the elements description, or an empty string if no description exists
     * @see org.greenstone.gatherer.msm.MSMUtils#getElementAttribute
     * @see org.greenstone.gatherer.util.StaticStrings#COMMENT_VALUE
     * @see org.greenstone.gatherer.util.StaticStrings#DEFINITION_VALUE
     * @see org.greenstone.gatherer.util.StaticStrings#EMPTY_STR
     * @see org.greenstone.gatherer.util.StaticStrings#SPACE_CHARACTER
     */
    static public String getDescription(Element element) {
    String language_code_str = Configuration.getLanguage();
    StringBuffer description = new StringBuffer(StaticStrings.EMPTY_STR);
    description.append(getElementAttribute(element, StaticStrings.DEFINITION_VALUE, language_code_str));
    if(description.length() > 0) {
        description.append(StaticStrings.SPACE_CHARACTER);
    }
    description.append(getElementAttribute(element, StaticStrings.COMMENT_VALUE, language_code_str));
    language_code_str = null;
    return description.toString();
    }

    /** Retrieve the value for the requested attribute in the required language. Once again this method must be aware of the differences between the old metadata sets and the new multilingual optimized ones.
     * @param element_element the Element whose attributes we are searching through
     * @param attribute_name_str the name of the desired attribute as a String
     * @param language_code_str the two letter code String indicating the desired language
     * @see org.greenstone.gatherer.msm.MSMUtils#getValue
     * @see org.greenstone.gatherer.msm.MSMUtils#isAttributeLanguageDependant
     * @see org.greenstone.gatherer.util.StaticStrings#ATTRIBUTE_ELEMENT
     * @see org.greenstone.gatherer.util.StaticStrings#CODE_ATTRIBUTE
     * @see org.greenstone.gatherer.util.StaticStrings#EMPTY_STR
     * @see org.greenstone.gatherer.util.StaticStrings#LANGUAGE_ATTRIBUTE
     * @see org.greenstone.gatherer.util.StaticStrings#LANGUAGE_ELEMENT
     * @see org.greenstone.gatherer.util.StaticStrings#NAME_ATTRIBUTE
     */
    static private String getElementAttribute(Element element_element, String attribute_name_str, String language_code_str) {
    boolean found = false;
    String result = StaticStrings.EMPTY_STR;
    Document document = element_element.getOwnerDocument();
    // Determine if the attribute is language specific
    if(isAttributeLanguageDependant(document, attribute_name_str)) {
        NodeList language_elements = element_element.getElementsByTagName(StaticStrings.LANGUAGE_ELEMENT);
        for(int i = 0; !found && i < language_elements.getLength(); i++) {
        Element language_element = (Element) language_elements.item(i);
        if(language_element.getAttribute(StaticStrings.CODE_ATTRIBUTE).equals(language_code_str)) {
            NodeList attribute_elements = language_element.getElementsByTagName(StaticStrings.ATTRIBUTE_ELEMENT);
            for(int j = 0; !found && j < attribute_elements.getLength(); j++) {
            Element attribute_element = (Element) attribute_elements.item(j);
            if(attribute_element.getAttribute(StaticStrings.NAME_ATTRIBUTE).equals(attribute_name_str)) {
                found = true;
                result = MSMUtils.getValue(attribute_element);
            }
            attribute_element = null;
            }
            attribute_elements = null;
        }
        language_element = null;
        }
        language_elements = null;
    }
    else {
        boolean first_match = false;
        NodeList attribute_elements = element_element.getElementsByTagName(StaticStrings.ATTRIBUTE_ELEMENT);
        for(int k = 0; !found && k < attribute_elements.getLength(); k++) {
        Element attribute_element = (Element) attribute_elements.item(k);
        // We don't want to consider those attributes found inside language elements
        if(attribute_element.getParentNode() == element_element) {
            ///ystem.err.println("First level");
            String target_name_str = attribute_element.getAttribute(StaticStrings.NAME_ATTRIBUTE);
            String target_language_str = attribute_element.getAttribute(StaticStrings.LANGUAGE_ATTRIBUTE);
            ///ystem.err.println("Does " + target_name_str + " equal " + attribute_name_str + "?");
            if(attribute_name_str.equals(target_name_str)) {
            ///ystem.err.println("Does " + target_language_str + " equal " + language_code_str + "?");
            if(language_code_str.equals(target_language_str)) {
                ///ystem.err.println("Perfect match!");
                found = true;
                result = MSMUtils.getValue(attribute_element);
            }
            else if((result == StaticStrings.EMPTY_STR || first_match) && isLegacyMDS(document)) {
                ///ystem.err.println("Legacy MDS");
                // Special case for old style documents, where the english match is good enough
                if(target_language_str.equals(StaticStrings.ENGLISH_LANGUAGE_STR)) {
                ///ystem.err.println("English plate.");
                result = MSMUtils.getValue(attribute_element);
                }
                // Super special case where the first match is better than nothing
                else if(result == StaticStrings.EMPTY_STR && !first_match) {
                ///ystem.err.println("First match.");
                first_match = true;
                result = MSMUtils.getValue(attribute_element);
                }
            }
            }
            target_language_str = null;
            target_name_str = null;
        }
        //else {
        ///ystem.err.println("Second level");
        //}
        attribute_element = null;
        }
        attribute_elements = null;

    }
    document = null;
    return result;
    }

    /*************************************************************************/
    /** Method to construct an elements fully qualified name. Note that this is different from a nodes identifier. Think of name as a short, unique reference to a metadata element, whereas identifier can be much longer, language specific and non-unique.
     * @param element An <strong>Element</strong> whose name we are interested in.
     * @return A <strong>String</strong> representing this given elements fully namespace qualified name.
     */
    static final public String getFullName(Element element) {
    return getFullName(element, "");

    }
    /*************************************************************************/
    /** Method to construct an elements fully qualified name. Note that this is different from a nodes identifier. Think of name as a short, unique reference to a metadata element, whereas identifier can be much longer, language specific and non-unique.
     * @param element An <strong>Element</strong> whose name we are interested in.
     * @return A <strong>String</strong> representing this given elements fully namespace qualified name.
     */
    static final public String getFullName(Element element, String namespace) {
    StringBuffer name_buffer = new StringBuffer();
    if(element == null) {
        return "Error";
    }
    // First get the root node.
    Document document = element.getOwnerDocument();
    Element root = document.getDocumentElement();
    document = null;
    // Retrieve this elements name
    name_buffer.append(element.getAttribute("name"));
    // Now we check if element has a parent node, other than root. If so we begin building up the full name
    Element parent_element = (Element) element.getParentNode();
    while(parent_element != null && parent_element != root) {
        name_buffer.insert(0, SF_SEP);
        name_buffer.insert(0, parent_element.getAttribute("name"));
        parent_element = (Element)parent_element.getParentNode();
    }
    parent_element = null;
    // Finally insert the namespace and we are all done.
    if(root != null) {
        namespace = root.getAttribute("namespace");
    } 
    root = null;
    // If no root, or no namespace found, assume its extracted (at least then they can't edit it)
    if(namespace == null || namespace.equals("")) {
        namespace = Utility.EXTRACTED_METADATA_NAMESPACE;
    }
    name_buffer.insert(0, NS_SEP);
    name_buffer.insert(0, namespace);
    namespace = null;
    return name_buffer.toString();
    } // static public String getFullName(Element element)

    /** Method to construct an elements name (sic identifier) by retrieving the correct attribute, language specific.
     * @param element the Element whose name we wish to retrieve
     * @return a String which is the elements identifier, or an empty string if no identifier exists
     * @see org.greenstone.gatherer.msm.MSMUtils#getElementAttribute
     * @see org.greenstone.gatherer.util.StaticStrings#IDENTIFIER_VALUE
     * @see org.greenstone.gatherer.util.StaticStrings#NAME_ATTRIBUTE
     */
    static final public String getIdentifier(Element element) {
    String identifier = getElementAttribute(element, StaticStrings.IDENTIFIER_VALUE, Configuration.getLanguage());
    // Failing the above we return the nodes name instead.
    if(identifier == null || identifier.length() == 0) {
        identifier = element.getAttribute(StaticStrings.NAME_ATTRIBUTE);
    }
    return identifier;
    }

    /** Method to retrieve from the node given, a certain child node with the specified name.
     * @param parent The <strong>Node</strong> whose children should be searched.
     * @param name The required nodes name as a <strong>String</strong>.
     * @return The requested <strong>Node</strong> if it is found, <i>null</i> otherwise.
     */ 
    static final public Node getNodeFromNamed(Node parent, String name) {
    Node child = null;
    for(Node i = parent.getFirstChild(); i != null && child == null; 
        i = i.getNextSibling()) {
        if(i.getNodeName().equals(name)) {
        child = i;
        }
    }
    return child;
    }
    /** Look for the occurances 'field' of the element and return it if found.
     * @return An <i>int</i> which matches the number in the occurances attribute of the element, or 0 if no such attribute.
     */
    static final public int getOccurances(Element element) {
    int count = 0;
    String number = null;
    if((number = element.getAttribute("occurances")) != null) {
        try {
        count = Integer.parseInt(number);
        }
        catch(Exception error) {
        count = 0;
        }
    }
    return count;
    }    
    /** This method extracts the option list details, if any, from a certain element and stores them in an array ready to be passed as arguments to the <strong>Dictionary</strong>.
     * @param element The <strong>Element</strong> whose option list we wish to view.
     * @return A <strong>String[]</strong> containing the details of the option list.
     * TODO implement.
     * @see org.greenstone.gatherer.Dictionary
     */
    static final public String[] getOptionListDetails(Element element) {
    return null;
    }


    /** This method extracts the structural details from a certain element and stores them in an array, all ready for passing to the <strong>Dictionary</strong>.
     * @param element The <Strong>Element</strong> whose details we wish to gather.
     * @return A <strong>String[]</strong> containing the structural details.
     */
    static final public String[] getStructuralDetails(MetadataSet mds, Element element) {
    String details[] = new String[4];
    //Element root = (Element)element.getParentNode();
    //details[0] = root.getAttribute("name");
    //details[1] = root.getAttribute("namespace");
    details[0] = mds.getName();
    details[1] = mds.getNamespace();
    details[2] = getFullName(element);
    details[3] = null;
    // Get attributes
    Vector attributes = new Vector();
    for(Node n=element.getFirstChild(); n!=null; n=n.getNextSibling()) {
        if(n.getNodeName().equals("Attribute")) {
        Element temp = (Element)n;
        attributes.add(temp.getAttribute("name") + "=" + getValue(n));
        }
    }
    // Sort attributes
    Collections.sort(attributes);
    // Add attributes to details.
    for(int i = 0; i < attributes.size(); i++) {
        if(details[3] == null) {
        details[3] = "   " + attributes.get(i);
        }
        else {
        details[3] = details[3] + "\n   " + attributes.get(i);
        }
    }
    return details;
    }

    /** Method to retrieve the value of a given node (not the assigned values tree!).
     * @param element The <strong>Element</strong> whose value we wish to find.
     * @return The value found as a <strong>String</strong>, or <i>null</i> if this element has no value.
     */
    static final public String getValue(Node element) {
    // If we've been given a subject node first retrieve its value node.
    if(element.getNodeName().equals("Subject")) {
        element = getNodeFromNamed(element, "Value");
    }
    // If we've got a value node, then reconstruct the text. Remember that DOM will split text over 256 characters into several text nodes
    if(element != null && element.hasChildNodes()) {
       StringBuffer text_buffer = new StringBuffer();
       NodeList text_nodes = element.getChildNodes();
       for(int i = 0; i < text_nodes.getLength(); i++) {
          Node possible_text = text_nodes.item(i);
          if(possible_text.getNodeName().equals(StaticStrings.TEXT_NODE)) {
         text_buffer.append(possible_text.getNodeValue());
          }
       }
       return text_buffer.toString();
    }
    return "";
    }

    /** Method to traverse the given value tree, and build up a hashtable of mappings between the value path key names and the Subject nodes of the tree.
     * @param current The root <strong>Node</strong> of a subtree of the AssignedValues tree.
     * @param prefix The value path key <strong>String</string>, which shows the path from the root of the AssignedValue tree to <i>current</i>s parent using '\' as a separator.
     * @param values A <strong>Hashtable</strong> containing the mapping discovered so far in our tree traversal.
     */ 
    static final private void getValueMappings(Node current, String prefix, Hashtable values) {
    if(current != null) {
        String name = current.getNodeName();
        String new_prefix = prefix;
        // If we've found the outer layer of a new value, add it to our mapping
        if(name.equals("Subject")) {
        Node value_node = getNodeFromNamed(current, "Value");
        String value = getValue(value_node);
        if(new_prefix != null) {
            new_prefix = new_prefix + "\\" + value;
        }
        else {
            new_prefix = value;
        }
        values.put(new_prefix, current);
        }
        if(name.equals("Subject") || name.equals("AssignedValues")) {
        for(Node child = current.getFirstChild(); child != null;
            child = child.getNextSibling()) {
            getValueMappings(child, new_prefix, values);
        }
        }
    }
    }
    /** Parses the value tree template file.
     * @return The Document parsed.
     */
    static final public Document getValueTreeTemplate() {
    return Utility.parse(Utility.METADATA_VALUE_TEMPLATE, true);
    }

    /** Determine if the named attribute is language specific for this collection. This information is found in a DOM attribute of the document element, as a comma separated list of attribute names.
     * @param document the Document for which we wish to check the language requirements
     * @param attribute_name_str the name of the attribute we a testing as a String
     * @see org.greenstone.gatherer.util.StaticStrings#LANGUAGEDEPENDANT_ATTRIBUTE
     */
    static private boolean isAttributeLanguageDependant(Document document, String attribute_name_str) {
    String language_specific_attributes = document.getDocumentElement().getAttribute(StaticStrings.LANGUAGEDEPENDANT_ATTRIBUTE).toLowerCase();
    return language_specific_attributes.indexOf(attribute_name_str) != -1;
    }

    /** Determine if the given document is a legacy MDS or a new multilingual one. The easiest way to tell is whether there is a language_dependant attribute in the document element.
     * @param document the Document to test
     * @return true if this is an old mds, false otherwise
     * @see org.greenstone.gatherer.util.StaticStrings#LANGUAGEDEPENDANT_ATTRIBUTE
     * @see org.greenstone.gatherer.util.StaticStrings#EMPTY_STR
     */
    static private boolean isLegacyMDS(Document document) {
    ///ystem.err.println("isLegacyMDS(): l_d = " + document.getDocumentElement().getAttribute(StaticStrings.LANGUAGEDEPENDANT_ATTRIBUTE));
    return (document.getDocumentElement().getAttribute(StaticStrings.LANGUAGEDEPENDANT_ATTRIBUTE)).equals(StaticStrings.EMPTY_STR);
    }

    /** Method to compare two OptionsLists for equality.
     * @param al A <strong>Node</strong> which represents an OptionList.
     * @param bl The <strong>Node</strong> we wish to test against.
     * @return A <i>boolean</i> which is <i>true</i> if the two option lists are equal, <i>false</i> otherwise.
     * TODO Implementation
     */
    static final private boolean optionListsEqual(Node al, Node bl) {
    // Compare the 'restricted' attribute of the two lists.
    Element ae = (Element) al;
    Element be = (Element) bl;
    if(!ae.getAttribute("restricted").equals
       (be.getAttribute("restricted"))) {
        return false;
    }
    // Compare the Values under each list.
    for(Node an = al.getFirstChild(); an != null; 
        an = an.getNextSibling()){
        if(an.getNodeName().equals("Value")) {
        boolean matched = false;
        for(Node bn = bl.getFirstChild(); bn != null && !matched;
            bn = bn.getNextSibling()) {
            if(bn.getNodeName().equals("Value")) {
            matched = valuesEqual(an, bn);
            }
        }
        if(!matched) {
            return false;
        }
        }
    }
    return true;
    }

    /** A method to remove a specific attribute element from an element. This attribute must match in name, language and in value before being removed. Note that this method supports both legacy and multilingual optimized versions of the mds.
     * @param element_element the Element which represent the metadata element we are altering
     * @param attribute_name_str the name of the attribute to remove as a String
     * @param language_code_str the language code we must match as a String
     * @param value_str the value String which also must match before we remove anything
     * @return true if the desired attribute was successfully found and removed, false otherwise
     * @see org.greenstone.gatherer.msm.MSMUtils#isAttributeLanguageDependant
     * @see org.greenstone.gatherer.msm.MSMUtils#getValue(Node)
     * @see org.greenstone.gatherer.util.StaticStrings#ATTRIBUTE_ELEMENT
     * @see org.greenstone.gatherer.util.StaticStrings#CODE_ATTRIBUTE
     * @see org.greenstone.gatherer.util.StaticStrings#LANGUAGE_ATTRIBUTE
     * @see org.greenstone.gatherer.util.StaticStrings#LANGUAGE_ELEMENT
     * @see org.greenstone.gatherer.util.StaticStrings#NAME_ATTRIBUTE
     */
    static public boolean removeElementAttribute(Element element_element, String attribute_name_str, String language_code_str, String value_str) {
    // Multilingual Optimized version
    // 1. Determine the if this is one of the language specific attributes
    if(isAttributeLanguageDependant(element_element.getOwnerDocument(), attribute_name_str)) {
        // Retrieve the language elements, and determine the correct one
        NodeList language_elements = element_element.getElementsByTagName(StaticStrings.LANGUAGE_ELEMENT);
        for(int i = 0; i < language_elements.getLength(); i++) {
        Element language_element = (Element) language_elements.item(i);
        if(language_element.getAttribute(StaticStrings.CODE_ATTRIBUTE).equalsIgnoreCase(language_code_str)) {
            NodeList attribute_elements = language_element.getElementsByTagName(StaticStrings.ATTRIBUTE_ELEMENT);
            for(int j = 0; j < attribute_elements.getLength(); j++) {
            Element attribute_element = (Element) attribute_elements.item(j);
            String target_name_str = attribute_element.getAttribute(StaticStrings.NAME_ATTRIBUTE);
            String target_value_str = MSMUtils.getValue(attribute_element);
            if(attribute_name_str.equals(target_name_str) && value_str.equals(target_value_str)) {
                language_element.removeChild(attribute_element);
                if(attribute_elements.getLength() == 0) {
                element_element.removeChild(language_element);
                }
                target_value_str = null;
                target_name_str = null;
                attribute_element = null;
                attribute_elements = null;
                language_element = null;
                language_elements = null;
                return true;
            }
            target_value_str = null;
            target_name_str = null;
            attribute_element = null;           
            }
            attribute_elements = null;
        }
        language_element = null;
        }
        language_elements = null;
        // Not found
        return false;
    }
    // Otherwise just use the old method

    // Find the attribute to remove
    NodeList attribute_elements = element_element.getElementsByTagName(StaticStrings.ATTRIBUTE_ELEMENT);
    for (int k = 0; k < attribute_elements.getLength(); k++) {
        Element attribute_element = (Element) attribute_elements.item(k);
        // Remember to ignore any attributes that live within nested language elements
        if (attribute_element.getParentNode() == element_element && attribute_element.getAttribute(StaticStrings.NAME_ATTRIBUTE).equals(attribute_name_str) && attribute_element.getAttribute(StaticStrings.LANGUAGE_ATTRIBUTE).equalsIgnoreCase(language_code_str) && MSMUtils.getValue(attribute_element).equals(value_str)) {
        // Match found, so remove the attribute node and return
        element_element.removeChild(attribute_element);
        attribute_element = null;
        attribute_elements = null;
        return true;
        }
        attribute_element = null;
    }
    attribute_elements = null;
    // No match found
    return false;
    }

    /** can only be used to set the english value */
    static final public void setIdentifier(Node element, String value) {
    // Get the 'identifier' Element
    for(Node node = element.getFirstChild(); node != null;
        node = node.getNextSibling()) {
        if(node.getNodeName().equals("Attribute")) {
        Element target = (Element)node;
        if(target.getAttribute("name").equals("identifier") && target.getAttribute("language").equals("en")) {
            Node text = target.getFirstChild();
            text.setNodeValue(value);
            break;
        }
        }
    }
    }
    /** Set the value of the element attribute occurances.
     * @param element The <strong>Element</strong> to change.
     * @param value The value to change by as an <i>int</i>.
     */
    static final public void setOccurance(Element element, int value) {
    Integer new_value = new Integer(getOccurances(element) + value);
    element.setAttribute("occurances", new_value.toString());
    }

    /** Set the #text node value of some element.
     * @param element the Element whose value we wish to set
     * @param value the new value for the element as a String
     */
    static final public void setValue(Element element, String value) {
    // Remove any existing child node(s)
    clear(element);
    // Add new text node.
    if (value != null) {
        element.appendChild(element.getOwnerDocument().createTextNode(value));
    }
    }

    /** This method also traverses the tree, but this one is used to gather all the values and aliases at once, and to 'prune' the tree if necessary.
     * @param current The current root <strong>Node</strong> of this AssignedValues tree subtree.
     * @param return_filter This <i>int</i> specifies what nodes from the tree should be returned, where;<br>VALUES  = return values only<br>ALIASES = return aliases only<br>BOTH    = return both values and aliases<br>NONE    = return nothing.
     * @param remove_leaves A leaf node is a subject that contains no child subjects. If this <i>boolean</i> is set to <i>true</i> then the leaf nodes will be removed from the tree. 
     * @return A <strong>Node[]</strong> containing whatever values or aliases have been found during the trees traversal.
     */
    static final public Node[] traverseTree(Node current, int return_filter, boolean remove_leaves) {
    Node leaves[] = null;
    String name = current.getNodeName();
    if(name.equals("Value") && (return_filter == VALUES || return_filter == BOTH)) {
        leaves = ArrayTools.add(leaves, current);
    }
    else if(name.equals("Alias") && (return_filter == ALIASES || return_filter == BOTH)) {
        leaves = ArrayTools.add(leaves, current);
    }
    else if(name.equals("Subject")) {
        boolean has_subject_child = false;
        Node children[] = ArrayTools.nodeListToNodeArray(current.getChildNodes());
        for(int i = 0; i < children.length; i++) {
        if(children[i].getNodeName().equals("Subject")) {
            has_subject_child = true;
        }
        leaves = ArrayTools.add(leaves, traverseTree(children[i], return_filter, remove_leaves));
        }
        if(!has_subject_child && remove_leaves) {
        Node parent = current.getParentNode();
        parent.removeChild(current);
        }
    }
    else if(name.equals("AssignedValues")) {
        Node children[] = ArrayTools.nodeListToNodeArray(current.getChildNodes());
        for(int i = 0; i < children.length; i++) {
        leaves = ArrayTools.add(leaves, traverseTree(children[i], return_filter, remove_leaves));
        }
    }                                                             
    return leaves;
    }

    /** This method is used to systematically merge two AssignedValues tree. Both trees have their current values mapped, then the new tree is searched for key paths that don't exist in the current tree. If such a key is found, the Subject <strong>Node</strong> it maps to is retrieved and then imported and added to whatever was the closest available node (in terms of tree path) in the current tree.
     * @param a_set The MetadataSet from which the Element a came from.
     * @param a The Element at the root of the current AssignedValues tree.
     * @param b_set The MetadataSet from which the Element b came from.
     * @param b The root Element of the tree that is being merged.
     * @return A <i>boolean</i> which is <i>true</i> if the trees merged without error, <i>false</i> otherwise.
     */
    static final public boolean updateValueTree(MetadataSet a_set, Element a, MetadataSet b_set, Element b) {
    GValueModel avt = a_set.getValueTree(new ElementWrapper(a));
    GValueModel bvt = b_set.getValueTree(new ElementWrapper(b));
    // If neither element even has a value tree, we're all done.
    if(avt == null && bvt == null) {
        avt = null;
        bvt = null;
        return true;
    }
    // If the new element has no value tree then nothing needs to be done.
    else if(avt != null && bvt == null) {
        avt = null;
        bvt = null;
        return true;
    }
    // If only the new element has a value tree, then add all of its values
    // immediately.
    else if(avt == null && bvt != null) {
        a_set.addValueTree(new ElementWrapper(a), bvt);
        avt = null;
        bvt = null;
        return true;
    }
    // We have both trees for both elements, time to merge.
    else {
        Document document = avt.getDocument();
        Hashtable a_map = new Hashtable();
        getValueMappings(document.getDocumentElement(), null, a_map);
        Hashtable b_map = new Hashtable();
        getValueMappings(bvt.getDocument().getDocumentElement(), null, b_map);
                // For each new entry in b_map
        for(Enumeration b_keys = b_map.keys(); b_keys.hasMoreElements(); ) {
        String b_key = (String)b_keys.nextElement();
        // Test if there is already an entry in a_map.
        if(!a_map.containsKey(b_key)) {
            // If not, search through a_map for the longest match.
            Node target = document.getDocumentElement();
            String last_match = null;
            for(Enumeration a_keys = a_map.keys(); 
            a_keys.hasMoreElements(); ) {
            String a_key = (String)a_keys.nextElement();
            if(b_key.startsWith(a_key)) {
                if(last_match == null || a_key.length() > last_match.length()) {
                last_match = a_key;
                target = (Node)a_map.get(a_key);
                }
            }
            a_key = null;
            }
            // Now import the node at b_key and add it to target.
            Node subtree = (Node)b_map.get(b_key);
            subtree = document.importNode(subtree, true);
            // Find the node to insert before...
            String name = getValue(subtree);
            Node move = null;
            for(Node n = target.getFirstChild(); n != null && move == null; n = n.getNextSibling()) {
            if(n.getNodeName().equals("Subject")) {
                if(name.compareTo(getValue(n)) <= 0) {
                move = n;
                }
            }
            }
            if(move == null) {
            target.appendChild(subtree);
            }
            else {
            target.insertBefore(subtree, move);
            }
            target = null;
            last_match = null;
            subtree = null;
            name = null;
            move = null;
        }
        b_key = null;
        }
        document = null;
        a_map = null;
        b_map = null;
        avt = null;
        bvt = null;
        return true;
    }
    }

    /** Method to determine if two Value nodes are equal.
     * @param av A <strong>Node</strong> representing a value.
     * @param bv The <strong>Node</strong> we want to compare it to.
     * @return A <i>boolean</i> which is <i>true</i> if the two value nodes are equal, <i>false</i> otherwise.
     */
    static final private boolean valuesEqual(Node av, Node bv) {
    // Check we are comparing apples and apples...
    if(av.getNodeName().equals("Value") && 
       bv.getNodeName().equals("Value")) {
        // Retrieve and then compare their text values.
        Node at = av.getFirstChild();
        Node bt = bv.getFirstChild();
        if(at.getNodeValue().equals(bt.getNodeValue())) {
        return true;
        }
    }
    return false;
    }

    /** A comparator for sorting metadata element-value pairs into their standard order (elements) then alphabetical order (values). */
//     static final private class MetadataComparator
//  implements Comparator {
//  /** Compares its two arguments for order. */
//  public int compare(Object o1, Object o2) {
//      int result = 0;
//      ElementWrapper e1 = null;
//      ElementWrapper e2 = null;
//      String v1 = null;
//      String v2 = null;
//      if(o1 instanceof Metadata && o2 instanceof Metadata) {
//      Metadata m1 = (Metadata) o1;
//      Metadata m2 = (Metadata) o2;
//      ///ystem.err.println("MSMUtils.compare(" + m1 + ", " + m2 + ") = ");
//      e1 = m1.getElement();
//      e2 = m2.getElement();
//      v1 = m1.getValue().toLowerCase();
//      v2 = m2.getValue().toLowerCase();
//      }
//      else if(o1 instanceof ElementWrapper && o2 instanceof ElementWrapper) {
//      e1 = (ElementWrapper) o1;
//      e2 = (ElementWrapper) o2;
//      }
//      if(e1 != null && e2 != null) {
//      // First we compare the namespaces
//      result = e1.getNamespace().compareTo(e2.getNamespace());
//      if(result == 0 && Gatherer.c_man != null && Gatherer.c_man.ready() && e1.getNamespace() != null) {
//          // Now, given both elements are in the same set, we compare the element ordering using methods in MetadataSet
//          MetadataSet set = Gatherer.c_man.getCollection().msm.getSet(e1.getNamespace());
//          ///ystem.err.print("MetadataSet.compare(" + e1 + ", " + e2 + ") = ");
//          if(set != null) {
//          result = set.compare(e1.getElement(), e2.getElement());
//          ///ystem.err.println(result);
//          if(result == 0 && v1 != null && v2 != null) {
//              // Finally we compare the values alphabetically.
//              result = v1.compareTo(v2);
//          }
//          }
//          else {
//          return 0;
//          }
//      }
//      }
//      else {
//      result = o1.toString().compareTo(o2.toString());
//      }
//      ///ystem.err.println("Result: " + result);
//      return result;
//  }
          
//  /** Indicates whether some other object is "equal to" this Comparator. */
//  public boolean equals(Object obj) { 
//      return compare(this, obj) == 0;
//  }
//     }
}