/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */
package hu.astrid.xmltools.beans;

import hu.astrid.xmltools.beantoxml.XmlToBeanConverter;
import org.w3c.dom.Document;
import org.w3c.dom.Node;

/**
 * Used, to convert Objects and Documents
 * @author István Zoltán Nagy
 */
public interface XmlConvertable<T> {

    /**
     * Sets the data tags of the current instance from the node hierarchy of the children of node parameter.
     * @param node The root of the hierarchy
     */
    public void buildFromXml(Node node) throws Exception;

    /**
     * Sets the data tags of the current instance from the node hierarchy of the children of node parameter.
     * This method uses fully qualified names during the generation, so this needs a prefix name.
     * @param node The root of the hierarchy
     * @param nameSpace The prefix of the names
     */
    public void buildFromXml(Node node, String nameSpace) throws Exception;

    /**
     * Creates a node hierarchy from the current instance with the return value as root.
     * @param doc The xml document, which contains the root of the hierarchy
     * @return node The root of the newly created hierarchy
     */
    public Node toXml(Document doc) throws Exception;

    /**
     * Creates a node hierarchy from the current instance with the return value as root.
     * This method uses fully qualified names during the generation, so this needs a prefix name.
     * @param doc The xml document, which contains the root of the hierarchy
     * @param nameSpace The prefix of the names
     * @return node The root of the newly created hierarchy
     */
    public Node toXml(Document doc, String nameSpace) throws Exception;

    /**
     * Returns a new XmlConverter instance
     * @return xmlConverter
     * @throws Exception When the creation of the new XmlConverter isn't possible
     */
    public XmlToBeanConverter getXmlConverter() throws Exception;
}
