package org.jdom.input;

import org.jdom.*;
import java.util.Map;

/**
An interface defining a JDOM object factory
Shoud support all public constructors of the
jdom classes
 */
public interface JDOMFactory
{
	// **** constructing Attributes ****

	/**
	 * <p>
	 * This will create a new <code>Attribute</code> with the
	 *   specified (local) name and value, and in the provided
	 *   <code>{@link Namespace}</code>.
	 * </p>
	 *
	 * @param name <code>String</code> name of <code>Attribute</code>.
	 * @param value <code>String</code> value for new attribute.
	 */
	public Attribute attribute(String name, String value, Namespace namespace);

	/**
	 * <p>
	 * This will create a new <code>Attribute</code> with the
	 *   specified (local) name and value, and place it in
	 *   the specified namespace (with prefix).
	 * </p>
	 *
	 * @param name <code>String</code> name of <code>Attribute</code>.
	 * @param prefix <code>String</code> prefix for <code>Attribute</code>.
	 * @param uri <code>String</code> URI for namespace this
	 *        <code>Attribute</code> is in.
	 * @param value <code>String</code> value for new attribute.
	 */
	public Attribute attribute(String name, String prefix, String uri, String value);

	/**
	 * <p>
	 * This will create a new <code>Attribute</code> with the
	 *   specified (local) name and value, and does not place
	 *   the attribute in a <code>{@link Namespace}</code>.
	 * </p><p>
	 *  <b>Note</b>: This actually explicitly puts the
	 *    <code>Attribute</code> in the "empty" <code>Namespace</code>
	 *    (<code>{@link Namespace#NO_NAMESPACE}</code>).
	 * </p>
	 *
	 * @param name <code>String</code> name of <code>Attribute</code>.
	 * @param value <code>String</code> value for new attribute.
	 */
	public Attribute attribute(String name, String value);

	// **** constructing CDATA ****

	/**
	 * <p>
	 * This creates the CDATA with the supplied
	 *   text.
	 * </p>
	 *
	 * @param text <code>String</code> content of CDATA.
	 */
	public CDATA cdata(String text) ;

	// **** constructing Comment ****

	/**
	 * <p>
	 * This creates the comment with the supplied
	 *   text.
	 * </p>
	 *
	 * @param text <code>String</code> content of comment.
	 */
	public Comment comment(String text);

	// **** constructing DocType

	/**
	 * <p>
	 * This will create the <code>DocType</code> with
	 *   the specified element name and a reference to an
	 *   external DTD.
	 * </p>
	 *
	 * @param elementName <code>String</code> name of
	 *        element being constrained.
	 * @param publicID <code>String</code> public ID of
	 *        referenced DTD
	 * @param systemID <code>String</code> system ID of
	 *        referenced DTD
	 */
	public DocType docType(String elementName, String publicID, String systemID);

	/**
	 * <p>
	 * This will create the <code>DocType</code> with
	 *   the specified element name and reference to an
	 *   external DTD.
	 * </p>
	 *
	 * @param elementName <code>String</code> name of
	 *        element being constrained.
	 * @param systemID <code>String</code> system ID of
	 *        referenced DTD
	 */
	public DocType docType(String elementName, String systemID);

	/**
	 * <p>
	 * This will create the <code>DocType</code> with
	 *   the specified element name
	 * </p>
	 *
	 * @param elementName <code>String</code> name of
	 *        element being constrained.
	 */
	public DocType  docType(String elementName);

	// **** constructing Document

	/**
	 * <p>
	 * This will create a new <code>Document</code>,
	 *   with the supplied <code>{@link Element}</code>
	 *   as the root element and the supplied
	 *   <code>{@link DocType}</code> declaration.
	 * </p>
	 *
	 * @param rootElement <code>Element</code> for document root.
	 * @param docType <code>DocType</code> declaration.
	 */
	public Document document(Element rootElement, DocType docType);

	/**
	 * <p>
	 * This will create a new <code>Document</code>,
	 *   with the supplied <code>{@link Element}</code>
	 *   as the root element, and no <code>{@link DocType}</code>
	 *   declaration.
	 * </p>
	 *
	 * @param rootElement <code>Element</code> for document root
	 */
	public Document document(Element rootElement);

	// **** constructing Entity

	/**
	 * <p>
	 * This will create a new <code>Entity</code>
	 *   with the supplied name.
	 * </p>
	 *
	 * @param name <code>String</code> name of element.
	 */
	public Entity entity(String name);

	// **** constructing Elements ****

	/**
	 * <p>
	 * This will create a new <code>Element</code>
	 *   with the supplied (local) name, and define
	 *   the <code>{@link Namespace}</code> to be used.
	 * </p>
	 *
	 * @param name <code>String</code> name of element.
	 * @namespace <code>Namespace</code> to put element in.
		 */
	public Element element(String name, Namespace namespace);

	/**
	 * <p>
	 *  This will create an <code>Element</code> in no
	 *    <code>{@link Namespace}</code>.
	 * </p>
	 *
	 * @param name <code>String</code> name of element.
	 */
	public Element element(String name);

	/**
	 * <p>
	 *  This will create a new <code>Element</code> with
	 *    the supplied (local) name, and specifies the URI
	 *    of the <code>{@link Namespace}</code> the <code>Element</code>
	 *    should be in, resulting it being unprefixed (in the default
	 *    namespace).
	 * </p>
	 *
	 * @param name <code>String</code> name of element.
	 * @param uri <code>String</code> URI for <code>Namespace</code> element
	 *        should be in.
	 */
	public Element element(String name, String uri);

	/**
	 * <p>
	 *  This will create a new <code>Element</code> with
	 *    the supplied (local) name, and specifies the prefix and URI
	 *    of the <code>{@link Namespace}</code> the <code>Element</code>
	 *    should be in.
	 * </p>
	 *
	 * @param name <code>String</code> name of element.
	 * @param uri <code>String</code> URI for <code>Namespace</code> element
	 *        should be in.
	 */
	public Element element(String name, String prefix, String uri);

	// **** constructing ProProcessingInstruction ****

	/**
	 * <p>
	 * This will create a new <code>ProcessingInstruction</code>
	 *   with the specified target and data.
	 * </p>
	 *
	 * @param target <code>String</code> target of PI.
	 * @param data <code>Map</code> data for PI, in
	 *             name/value pairs
	 */
	public ProcessingInstruction processingInstruction(String target, Map data);

	/**
	 * <p>
	 * This will create a new <code>ProcessingInstruction</code>
	 *   with the specified target and data.
	 * </p>
	 *
	 * @param target <code>String</code> target of PI.
	 * @param rawData <code>String</code> data for PI.
	 */
	public ProcessingInstruction processingInstruction(String target, String data);

}