Document


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  */
190
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags