org.w3c.dom.Entity Maven / Gradle / Ivy

/*
 * Copyright (C) 2005 by Quentin Anciaux
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Library General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at your
 * option) any later version.
 *
 * This library 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 Library General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Library General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 *	@author Quentin Anciaux
 */

package org.w3c.dom;

/**
 * This interface represents a known entity, either parsed or unparsed, in an
 * XML document. Note that this models the entity itself not the
 * entity declaration.
 * 
 * 
 * The nodeName attribute that is inherited from Node
 * contains the name of the entity.
 * 
 * 
 * 
 * An XML processor may choose to completely expand entities before the
 * structure model is passed to the DOM; in this case there will be no
 * EntityReference nodes in the document tree.
 * 
 * 
 * 
 * XML does not mandate that a non-validating XML processor read and process
 * entity declarations made in the external subset or declared in parameter
 * entities. This means that parsed entities declared in the external subset
 * need not be expanded by some classes of applications, and that the
 * replacement text of the entity may not be available. When the 
 * replacement text  is available, the corresponding Entity
 * node's child list represents the structure of that replacement value.
 * Otherwise, the child list is empty.
 * 
 * 
 * 
 * DOM Level 3 does not support editing Entity nodes; if a user
 * wants to make changes to the contents of an Entity, every
 * related EntityReference node has to be replaced in the
 * structure model by a clone of the Entity's contents, and then
 * the desired changes must be made to each of those clones instead.
 * Entity nodes and all their descendants are readonly.
 * 
 * 
 * 
 * An Entity node does not have any parent. Note:  If the
 * entity contains an unbound namespace prefix, the namespaceURI
 * of the corresponding node in the Entity node subtree is
 * null. The same is true for EntityReference nodes
 * that refer to this entity, when they are created using the
 * createEntityReference method of the Document
 * interface.
 * 
 * 
 * 
 * See also the Document
 * Object Model (DOM) Level 3 Core Specification .
 * 
 */
public interface Entity
    extends Node {
    /**
     * The public identifier associated with the entity if specified, and
     * null otherwise.
     *
     * @return DOCUMENT ME!
     */
    public String getPublicId();

    /**
     * The system identifier associated with the entity if specified, and
     * null otherwise. This may be an absolute URI or not.
     *
     * @return DOCUMENT ME!
     */
    public String getSystemId();

    /**
     * For unparsed entities, the name of the notation for the entity. For
     * parsed entities, this is null.
     *
     * @return DOCUMENT ME!
     */
    public String getNotationName();

    /**
     * An attribute specifying the encoding used for this entity at the time of
     * parsing, when it is an external parsed entity. This is
     * null if it an entity from the internal subset or if it is
     * not known.
     *
     * @return DOCUMENT ME!
     *
     * @since DOM Level 3
     */
    public String getInputEncoding();

    /**
     * An attribute specifying, as part of the text declaration, the encoding
     * of this entity, when it is an external parsed entity. This is
     * null otherwise.
     *
     * @return DOCUMENT ME!
     *
     * @since DOM Level 3
     */
    public String getXmlEncoding();

    /**
     * An attribute specifying, as part of the text declaration, the version
     * number of this entity, when it is an external parsed entity. This is
     * null otherwise.
     *
     * @return DOCUMENT ME!
     *
     * @since DOM Level 3
     */
    public String getXmlVersion();
}