/*
 * Copyright (c) 2011 by Intevation GmbH
 *
 * This program is free software under the LGPL (>=v2.1)
 * Read the file LGPL.txt coming with the software for details
 * or visit http://www.gnu.org/licenses/ if it does not exist.
 */
package de.intevation.artifacts.common.utils;

import javax.xml.xpath.XPathConstants;

import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;

import de.intevation.artifacts.common.ArtifactNamespaceContext;


/**
 * This class provides methods that help creating the artifact protocol
 * documents DESCRIBE, FEED, ADVANCE and OUT.
 *
 * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
 */
public class ClientProtocolUtils {

    /** The XPath to the current state in the DESCRIBE document.*/
    public static final String XPATH_CURRENT_STATE = "/art:result/art:state";

    /** The XPath to the static UI part in the DESCRIBE document.*/
    public static final String XPATH_STATIC  = "/art:result/art:ui/art:static";

    /** The XPath to the dynamic UI part in the DESCRIBE document.*/
    public static final String XPATH_DYNAMIC = "/art:result/art:ui/art:dynamic";

    /** The XPath to the reachable states part in the DESCRIBE document.*/
    public static final String XPATH_STATES  =
        "/art:result/art:reachable-states";

    /** The XPath to the select node relative to the dynamic UI node in the
     * DESCRIBE document.*/
    public static final String XPATH_DATA_SELECT = "art:select";

    /** The XPath to the choices nodes relative to the select node in the
     * DESCRIBE document.*/
    public static final String XPATH_DATA_ITEMS = "art:choices/art:item";

    /** The XPath to a label in the artifact's DESCRIBE document.*/
    public static final String XPATH_LABEL = "art:label/text()";

    /** The XPath to a value in the artifact's DESCRIBE document.*/
    public static final String XPATH_VALUE = "art:value/text()";


    /**
     * It should not be necessary to create instances of this class.
     */
    private ClientProtocolUtils() {
    }


    /**
     * This method creates a new CREATE document.
     *
     * @return the CREATE document.
     */
    public static Document newCreateDocument(String factory) {
        Document doc = XMLUtils.newDocument();

        XMLUtils.ElementCreator cr = new XMLUtils.ElementCreator(
            doc,
            ArtifactNamespaceContext.NAMESPACE_URI,
            ArtifactNamespaceContext.NAMESPACE_PREFIX);

        Element action = cr.create("action");
        Element type   = cr.create("type");
        Element fac    = cr.create("factory");

        type.setAttribute("name", "create");
        fac.setAttribute("name", factory);

        action.appendChild(type);
        action.appendChild(fac);

        doc.appendChild(action);

        return doc;
    }


    /**
     * This method creates a new document that is used to create new artifact
     * collections in the artifact server.
     *
     * @param name <b>Optional</b> name of the collection.
     *
     * @return the document to create new collections.
     */
    public static Document newCreateCollectionDocument(String name) {
        Document doc = XMLUtils.newDocument();

        XMLUtils.ElementCreator cr = new XMLUtils.ElementCreator(
            doc,
            ArtifactNamespaceContext.NAMESPACE_URI,
            ArtifactNamespaceContext.NAMESPACE_PREFIX);

        Element action     = cr.create("action");
        Element type       = cr.create("type");
        Element collection = cr.create("artifact-collection");

        cr.addAttr(type, "name", "create");
        cr.addAttr(collection, "name", name != null ? name : "");

        action.appendChild(type);
        action.appendChild(collection);

        doc.appendChild(action);

        return doc;
    }


    /**
     * Returns string value found by {@link XPATH_LABEL} relative to
     * <i>node</i>.
     *
     * @param node A node.
     *
     * @return the string value found by {@link XPATH_LABEL}.
     */
    public static String getLabel(Node node) {
        return (String) XMLUtils.xpath(
            node,
            XPATH_LABEL,
            XPathConstants.STRING,
            ArtifactNamespaceContext.INSTANCE);
    }


    /**
     * Returns string value found by {@link XPATH_VALUE} relative to
     * <i>node</i>.
     *
     * @param node A node.
     *
     * @return the string value found by {@link XPATH_VALUE}.
     */
    public static String getValue(Node node) {
        return (String) XMLUtils.xpath(
            node,
            XPATH_VALUE,
            XPathConstants.STRING,
            ArtifactNamespaceContext.INSTANCE);
    }


    /**
     * This method returns the static UI part of the artifact's DESCRIBE
     * document.
     *
     * @param description The document returned by the artifact server's
     * DESCRIBE operation.
     *
     * @return the static UI node.
     */
    public static Node getStaticUI(Document description) {
        return (Node) XMLUtils.xpath(
            description,
            XPATH_STATIC,
            XPathConstants.NODE,
            ArtifactNamespaceContext.INSTANCE);
    }


    /**
     * This method returns the dynamic UI part of the artifact's DESCRIBE
     * document.
     *
     * @param description The document returned by the artifact server's
     * DESCRIBE operation.
     *
     * @return the dynamic UI node.
     */
    public static Node getDynamicUI(Document description) {
        return (Node) XMLUtils.xpath(
            description,
            XPATH_DYNAMIC,
            XPathConstants.NODE,
            ArtifactNamespaceContext.INSTANCE);
    }


    /**
     * This method returns the current state node contained in the DESCRIBE
     * document.
     *
     * @param description The document returned by the artifact server's
     * DESCRIBE operation.
     *
     * @return the node containing information about the current state.
     */
    public static Node getCurrentState(Document description) {
        return (Node) XMLUtils.xpath(
            description,
            XPATH_CURRENT_STATE,
            XPathConstants.NODE,
            ArtifactNamespaceContext.INSTANCE);
    }


    /**
     * This method returns the node that contains information about the
     * reachable states of the artifact in the artifact's DESCRIBE document.
     *
     * @param description The document returned by the artifact server's
     * DESCRIBE operation.
     *
     * @return the node that contains the reachable states.
     */
    public static Node getReachableStates(Document description) {
        return (Node) XMLUtils.xpath(
            description,
            XPATH_STATES,
            XPathConstants.NODE,
            ArtifactNamespaceContext.INSTANCE);
    }


    /**
     * Returns the node found by {@link XPATH_DATA_SELECT}.
     *
     * @param dynamicNode The dynamic UI node of the DESCRIBE document.
     *
     * @return the select node found in the dynamic UI node.
     */
    public static Node getSelectNode(Node dynamicNode) {
        return (Node) XMLUtils.xpath(
            dynamicNode,
            XPATH_DATA_SELECT,
            XPathConstants.NODE,
            ArtifactNamespaceContext.INSTANCE);
    }


    /**
     * Returns the items that could be found in the <i>node</i>.
     *
     * @param node A select node.
     *
     * @return the choices nodes as node list.
     */
    public static NodeList getItemNodes(Node node) {
        return (NodeList) XMLUtils.xpath(
            node,
            XPATH_DATA_ITEMS,
            XPathConstants.NODESET,
            ArtifactNamespaceContext.INSTANCE);
    }
}
// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :