View Javadoc

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