/*
 * (C) Copyright IBM Corp. 1997-1998  All rights reserved.
 *
 * US Government Users Restricted Rights Use, duplication or
 * disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
 *
 * The program is provided "as is" without any warranty express or
 * implied, including the warranty of non-infringement and the implied
 * warranties of merchantibility and fitness for a particular purpose.
 * IBM will not be liable for any damages suffered by you as a result
 * of using the Program. In no event will IBM be liable for any
 * special, indirect or consequential damages or lost profits even if
 * IBM has been advised of the possibility of their occurrence. IBM
 * will not be liable for any third party claims against you.
 */

package com.ibm.xml.parser;

import org.w3c.dom.*;

/**
 * The ElementDecl class implements the ElementDefinition interface as defined by the Document Object Model (DOM).
 * <p>Element declarations in the DTD determine the possible structure of the XML document.
 * The following structures, known as <var>content models</var>, are supported for element declaration:
 * <dl>
 * <dt>EMPTY
 * <dd>This Element can not have any content, and must appear as an empty Element in the
 * XML document.  For example, the <var>EMPTY</var> element declaration 
 * <CODE>&lt;!ELEMENT graphic EMPTY&gt;</CODE> would have the Element tag <CODE>&lt;graphic/&gt;</CODE>
 * appear in the XML document.
 * <dt>ANY
 * <dd>This Element can have any combination of character data and element types allow by
 * the DTD.
 * <dt>#PCDATA
 * <dd>This Element must only contain character data.  For example, the <var>#PCDATA</var> 
 * element declaration <CODE>&lt;!ELEMENT text (#PCDATA)&gt;</CODE> could have the Element 
 * tag <CODE>&lt;text&gt;a group of character data&lt;/text&gt;</CODE> appear in the XML document.
 * <dt>MODEL_GROUP
 * <dd>This Element allows a mixture of #PCDATA and other Elements as their children.
 * The following language primitives are used to help express this relationship:
 *   <dl>
 *   <dt>( and )
 *   <dd>Surround a sequence of alternatives
 *   <dt>,
 *   <dd>Separates each Element type in a sequence
 *   <dt>|
 *   <dd>Separates each Element type in a list of alternatives
 *   <dt>? and *
 *   <dd>Indicates that an Element or group occurs zero or more times
 *   <dt>+
 *   <dd>Indicates that an Element or group occurs one or more times
 *   </dl>
 *   <p>To illustrate this point, the element declaration 
 *   <CODE>&lt;!ELEMENT memo (from, to+, cc*, date?, content)&gt;</CODE> could have the Element 
 *   tag <CODE>&lt;memo&gt; &lt;from&gt;me&lt;/from&gt; &lt;to&gt;you&lt;/to&gt; &lt;to&gt;and you&lt;/to&gt; &lt;content&gt;hello world&lt;/content&gt; &lt;/memo&gt;</CODE> appear in the XML document.
 * </dl>
 *
 * @version 1.1
 * @author TAMURA Kent &lt;kent@trl.ibm.co.jp&gt;
 * @see org.w3c.dom.ElementDefinition
 * @see com.ibm.xml.parser.Child
 */
public class ElementDecl extends Child implements ElementDefinition {

            String          name            =   null;
            ContentModel    contentModel    =   null;

    /**
     * Constructor.
     * @param name          This element definition's name. 
     * @param contentModel  The content model to associate with this element definition,
     *                      or <var>null</var> if the content model is to be set later.
     */
    public ElementDecl(String name, ContentModel contentModel) {
        this.name = name;
        this.contentModel = contentModel;
    }

    /**
     * Clone this element definition Node using the appropriate factory.
     * <p>This method is defined by Child.
     * @return          Cloned element definition Node.
     * @see com.ibm.xml.parser.Child#clone
     */
    public synchronized Object clone() {
        checkFactory();
        ElementDecl ed = factory.createElementDecl(this.name, null);
        ed.setFactory(getFactory());
        ed.contentModel = (ContentModel)this.contentModel.clone();
        return ed;
    }

    /**
     * Returns that this object is an element definition Node.
     * <p>This method is defined by DOM.
     * @return          Element definition Node indicator.
     */
    public int getNodeType() {
        return Child.ELEMENTDEFINITION;
    }

    /**
     * Returns this element definition's name.
     * <p>This method is defined by DOM.
     * @return          The string that is this Element's name, or <var>null</var> if no name. 
     * @see #setName
     */
    public String getName() {
        return this.name;
    }

    /**
     * Sets this element definition's name. 
     * <p>This method is defined by DOM.
     * @param   name    The string that is this element definition's name. 
     * @see #getName
     */
    public void setName(String name) {
        this.name = name;
    }

    /**
     * Returns the content type which represents the content model used by this element definition. 
     * <p>This method is defined by DOM.
     * @return          The content type for this element's definition, or <var>null</var> if 
     *                  no content type has been defined. 
     *                  Must be one of org.w3c.dom.ElementDefinition#ContentType.
     *                  Note that the XML4J parser will never set <code>PCDATA</code> as the
     *                  content type; <code>MODEL_GROUP</code> will be set instead.
     * @see #setContentType
     * @see #getContentModel
     */
    public int getContentType() {
        return getXML4JContentModel().getType();
    }

    /**
     * Sets the content type which represents the content model used by this element definition. 
     * <p>This method is defined by DOM.
     * @param contentType   The content type for this element's definition.
     *                      Must be one of org.w3c.dom.ElementDefinition#ContentType.
     * @see #getContentType
     * @see #setContentModel
     */
    public void setContentType(int contentType) {
        getXML4JContentModel().setType(contentType);
    }

    /**
     * Returns the content model used by this element definition. The returned value is
     * only meaningful if this element definition's content type is <code>MODEL_GROUP</code>.
     * <p>This method is defined by DOM.
     * <p>This method is CURRENTLY NOT IMPLEMENTED.
     * @return          The content model for this element's definition, or <var>null</var> if 
     *                  no content model has been defined. 
     * @see #getContentType
     * @see #setContentModel
     */
    public ModelGroup getContentModel() {
        return null;
    }

    /**
     * Sets the content model used by this element definition. The specified <var>contentModel</var> is
     * only meaningful if this element definition's content type is <code>MODEL_GROUP</code>.
     * <p>This method is defined by DOM.
     * <p>This method is CURRENTLY NOT IMPLEMENTED.
     * @param contentModel  The content model for this element's definition. 
     * @see #setContentType
     * @see #getContentModel
     */
    public void setContentModel(ModelGroup contentModel) {
    }

    /**
     * Returns the attribute list that was defined by this element definition. 
     * <p>This method is defined by DOM.
     * <p>This method is CURRENTLY NOT IMPLEMENTED.
     * @return          The Node that defines the attribute list for this element definition,
     *                  or <var>null</var> if no attributes defined.
     * @see com.ibm.xml.parser.Attlist#elements
     * @see #setAttributeDefinitions
     */
    public Node getAttributeDefinitions() {
        return null;
    }

    /**
     * Sets the attribute list that was defined by this element definition. 
     * <p>This method is defined by DOM.
     * <p>This method is CURRENTLY NOT IMPLEMENTED.
     * @param   attList The Node that defines the attribute list for this element definition.
     * @see com.ibm.xml.parser.Attlist#addElement
     * @see #getAttributeDefinitions
     */
    public void setAttributeDefinitions(Node attList) {
    }

    /**
     * This method is only meaningful for HTML documents, and not for XML documents.   
     * <p>This method is defined by DOM.
     * @deprecated This method will not be implemented in XML4J.
     * @return          Always returns <var>null</var>. 
     * @see #setInclusions
     */
    public Node getInclusions() {
        return null;
    }

    /**
     * This method is only meaningful for HTML documents, and not for XML documents.   
     * <p>This method is defined by DOM.
     * @deprecated This method will not be implemented in XML4J.
     * @see #getInclusions
     */
    public void setInclusions(Node inclusion) {
    }

    /**
     * This method is only meaningful for HTML documents, and not for XML documents.   
     * <p>This method is defined by DOM.
     * @deprecated This method will not be implemented in XML4J.
     * @return          Always returns <var>null</var>. 
     * @see #setExceptions
     */
    public Node getExceptions() {
        return null;
    }

    /**
     * This method is only meaningful for HTML documents, and not for XML documents.   
     * <p>This method is defined by DOM.
     * @deprecated This method will not be implemented in XML4J.
     * @see #getExceptions
     */
    public void setExceptions(Node exception) {
    }

    ContentModel getXML4JContentModel() {
        return this.contentModel;
    }
}
