View Javadoc

    1   /*
    2    * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
    3    *
    4    * This software is open source.
    5    * See the bottom of this file for the licence.
    6    */
    7
    8   package org.dom4j;
    9
    10  import java.util.Map;
    11
    12  import org.xml.sax.EntityResolver;
    13
    14  /***
    15   * <p>
    16   * <code>Document</code> defines an XML Document.
    17   * </p>
    18   *
    19   * @author <a href="mailto:jstrachan@apache.org">James Strachan </a>
    20   * @version $Revision: 1.14 $
    21   */
    22  public interface Document extends Branch {
    23      /***
    24       * Returns the root {@link Element}for this document.
    25       *
    26       * @return the root element for this document
    27       */
    28      Element getRootElement();
    29
    30      /***
    31       * Sets the root element for this document
    32       *
    33       * @param rootElement
    34       *            the new root element for this document
    35       */
    36      void setRootElement(Element rootElement);
    37
    38      /***
    39       * Adds a new <code>Comment</code> node with the given text to this
    40       * branch.
    41       *
    42       * @param comment
    43       *            is the text for the <code>Comment</code> node.
    44       *
    45       * @return this <code>Document</code> instance.
    46       */
    47      Document addComment(String comment);
    48
    49      /***
    50       * Adds a processing instruction for the given target
    51       *
    52       * @param target
    53       *            is the target of the processing instruction
    54       * @param text
    55       *            is the textual data (key/value pairs) of the processing
    56       *            instruction
    57       *
    58       * @return this <code>Document</code> instance.
    59       */
    60      Document addProcessingInstruction(String target, String text);
    61
    62      /***
    63       * Adds a processing instruction for the given target
    64       *
    65       * @param target
    66       *            is the target of the processing instruction
    67       * @param data
    68       *            is a Map of the key / value pairs of the processing
    69       *            instruction
    70       *
    71       * @return this <code>Document</code> instance.
    72       */
    73      Document addProcessingInstruction(String target, Map data);
    74
    75      /***
    76       * Adds a DOCTYPE declaration to this document
    77       *
    78       * @param name
    79       *            is the name of the root element
    80       * @param publicId
    81       *            is the PUBLIC URI
    82       * @param systemId
    83       *            is the SYSTEM URI
    84       *
    85       * @return this <code>Document</code> instance.
    86       */
    87      Document addDocType(String name, String publicId, String systemId);
    88
    89      /***
    90       * DOCUMENT ME!
    91       *
    92       * @return the DocumentType property
    93       */
    94      DocumentType getDocType();
    95
    96      /***
    97       * Sets the DocumentType property
    98       *
    99       * @param docType
    100      *            DOCUMENT ME!
    101      */
    102     void setDocType(DocumentType docType);
    103
    104     /***
    105      * DOCUMENT ME!
    106      *
    107      * @return the EntityResolver used to find resolve URIs such as for DTDs, or
    108      *         XML Schema documents
    109      */
    110     EntityResolver getEntityResolver();
    111
    112     /***
    113      * Sets the EntityResolver used to find resolve URIs such as for DTDs, or
    114      * XML Schema documents
    115      *
    116      * @param entityResolver
    117      *            DOCUMENT ME!
    118      */
    119     void setEntityResolver(EntityResolver entityResolver);
    120
    121     /***
    122      * Return the encoding of this document, as part of the XML declaration This
    123      * is <code>null</code> when unspecified or when it is not known (such as
    124      * when the Document was created in memory) or when the implementation does
    125      * not support this operation.
    126      *
    127      * <p>
    128      * The way this encoding is retrieved also depends on the way the XML source
    129      * is parsed. For instance, if the SAXReader is used and if the underlying
    130      * XMLReader implementation support the
    131      * <code>org.xml.sax.ext.Locator2</code> interface, the result returned by
    132      * this method is specified by the <code>getEncoding()</code> method of
    133      * that interface.
    134      * </p>
    135      *
    136      * @return The encoding of this document, as stated in the XML declaration,
    137      *         or <code>null</code> if unknown.
    138      *
    139      * @since 1.5
    140      */
    141     String getXMLEncoding();
    142
    143     /***
    144      * Sets the encoding of this document as it will appear in the XML
    145      * declaration part of the document.
    146      *
    147      * @param encoding the encoding of the document
    148      *
    149      * @since 1.6
    150      */
    151     void setXMLEncoding(String encoding);
    152 }
    153
    154 /*
    155  * Redistribution and use of this software and associated documentation
    156  * ("Software"), with or without modification, are permitted provided that the
    157  * following conditions are met:
    158  *
    159  * 1. Redistributions of source code must retain copyright statements and
    160  * notices. Redistributions must also contain a copy of this document.
    161  *
    162  * 2. Redistributions in binary form must reproduce the above copyright notice,
    163  * this list of conditions and the following disclaimer in the documentation
    164  * and/or other materials provided with the distribution.
    165  *
    166  * 3. The name "DOM4J" must not be used to endorse or promote products derived
    167  * from this Software without prior written permission of MetaStuff, Ltd. For
    168  * written permission, please contact dom4j-info@metastuff.com.
    169  *
    170  * 4. Products derived from this Software may not be called "DOM4J" nor may
    171  * "DOM4J" appear in their names without prior written permission of MetaStuff,
    172  * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
    173  *
    174  * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org
    175  *
    176  * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND
    177  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    178  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    179  * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE
    180  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    181  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    182  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    183  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    184  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    185  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    186  * POSSIBILITY OF SUCH DAMAGE.
    187  *
    188  * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
    189  */