|
0
|
1 /*--
|
|
|
2
|
|
|
3 $Id: JDOMFactory.java,v 1.9 2007/11/10 05:28:59 jhunter Exp $
|
|
|
4
|
|
|
5 Copyright (C) 2000-2007 Jason Hunter & Brett McLaughlin.
|
|
|
6 All rights reserved.
|
|
|
7
|
|
|
8 Redistribution and use in source and binary forms, with or without
|
|
|
9 modification, are permitted provided that the following conditions
|
|
|
10 are met:
|
|
|
11
|
|
|
12 1. Redistributions of source code must retain the above copyright
|
|
|
13 notice, this list of conditions, and the following disclaimer.
|
|
|
14
|
|
|
15 2. Redistributions in binary form must reproduce the above copyright
|
|
|
16 notice, this list of conditions, and the disclaimer that follows
|
|
|
17 these conditions in the documentation and/or other materials
|
|
|
18 provided with the distribution.
|
|
|
19
|
|
|
20 3. The name "JDOM" must not be used to endorse or promote products
|
|
|
21 derived from this software without prior written permission. For
|
|
|
22 written permission, please contact <request_AT_jdom_DOT_org>.
|
|
|
23
|
|
|
24 4. Products derived from this software may not be called "JDOM", nor
|
|
|
25 may "JDOM" appear in their name, without prior written permission
|
|
|
26 from the JDOM Project Management <request_AT_jdom_DOT_org>.
|
|
|
27
|
|
|
28 In addition, we request (but do not require) that you include in the
|
|
|
29 end-user documentation provided with the redistribution and/or in the
|
|
|
30 software itself an acknowledgement equivalent to the following:
|
|
|
31 "This product includes software developed by the
|
|
|
32 JDOM Project (http://www.jdom.org/)."
|
|
|
33 Alternatively, the acknowledgment may be graphical using the logos
|
|
|
34 available at http://www.jdom.org/images/logos.
|
|
|
35
|
|
|
36 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
|
|
|
37 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
|
38 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
|
39 DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
|
|
|
40 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
|
41 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
|
42 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
|
|
|
43 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
|
44 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
|
45 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
|
|
46 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
|
47 SUCH DAMAGE.
|
|
|
48
|
|
|
49 This software consists of voluntary contributions made by many
|
|
|
50 individuals on behalf of the JDOM Project and was originally
|
|
|
51 created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
|
|
|
52 Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information
|
|
|
53 on the JDOM Project, please see <http://www.jdom.org/>.
|
|
|
54
|
|
|
55 */
|
|
|
56
|
|
|
57 package org.jdom;
|
|
|
58
|
|
|
59 import java.util.*;
|
|
|
60
|
|
|
61 /**
|
|
|
62 * An interface to be used by builders when constructing JDOM objects. The
|
|
|
63 * <code>DefaultJDOMFactory</code> creates the standard top-level JDOM classes
|
|
|
64 * (Element, Document, Comment, etc). Another implementation of this factory
|
|
|
65 * could be used to create custom classes.
|
|
|
66 *
|
|
|
67 * @version $Revision: 1.9 $, $Date: 2007/11/10 05:28:59 $
|
|
|
68 * @author Ken Rune Holland
|
|
|
69 * @author Phil Nelson
|
|
|
70 * @author Bradley S. Huffman
|
|
|
71 */
|
|
|
72 public interface JDOMFactory {
|
|
|
73
|
|
|
74 // **** constructing Attributes ****
|
|
|
75
|
|
|
76 /**
|
|
|
77 * <p>
|
|
|
78 * This will create a new <code>Attribute</code> with the
|
|
|
79 * specified (local) name and value, and in the provided
|
|
|
80 * <code>{@link org.jdom.Namespace}</code>.
|
|
|
81 * </p>
|
|
|
82 *
|
|
|
83 * @param name <code>String</code> name of <code>Attribute</code>.
|
|
|
84 * @param value <code>String</code> value for new attribute.
|
|
|
85 */
|
|
|
86 public Attribute attribute(String name, String value, Namespace namespace);
|
|
|
87
|
|
|
88 /**
|
|
|
89 * This will create a new <code>Attribute</code> with the
|
|
|
90 * specified (local) name, value, and type, and in the provided
|
|
|
91 * <code>{@link org.jdom.Namespace}</code>.
|
|
|
92 *
|
|
|
93 * @param name <code>String</code> name of <code>Attribute</code>.
|
|
|
94 * @param value <code>String</code> value for new attribute.
|
|
|
95 * @param type <code>int</code> type for new attribute.
|
|
|
96 * @param namespace <code>Namespace</code> namespace for new attribute.
|
|
|
97 */
|
|
|
98 public Attribute attribute(String name, String value,
|
|
|
99 int type, Namespace namespace);
|
|
|
100
|
|
|
101 /**
|
|
|
102 * This will create a new <code>Attribute</code> with the
|
|
|
103 * specified (local) name and value, and does not place
|
|
|
104 * the attribute in a <code>{@link org.jdom.Namespace}</code>.
|
|
|
105 * <p>
|
|
|
106 * <b>Note</b>: This actually explicitly puts the
|
|
|
107 * <code>Attribute</code> in the "empty" <code>Namespace</code>
|
|
|
108 * (<code>{@link org.jdom.Namespace#NO_NAMESPACE}</code>).
|
|
|
109 * </p>
|
|
|
110 *
|
|
|
111 * @param name <code>String</code> name of <code>Attribute</code>.
|
|
|
112 * @param value <code>String</code> value for new attribute.
|
|
|
113 */
|
|
|
114 public Attribute attribute(String name, String value);
|
|
|
115
|
|
|
116 /**
|
|
|
117 * This will create a new <code>Attribute</code> with the
|
|
|
118 * specified (local) name, value and type, and does not place
|
|
|
119 * the attribute in a <code>{@link org.jdom.Namespace}</code>.
|
|
|
120 * <p>
|
|
|
121 * <b>Note</b>: This actually explicitly puts the
|
|
|
122 * <code>Attribute</code> in the "empty" <code>Namespace</code>
|
|
|
123 * (<code>{@link org.jdom.Namespace#NO_NAMESPACE}</code>).
|
|
|
124 * </p>
|
|
|
125 *
|
|
|
126 * @param name <code>String</code> name of <code>Attribute</code>.
|
|
|
127 * @param value <code>String</code> value for new attribute.
|
|
|
128 * @param type <code>int</code> type for new attribute.
|
|
|
129 */
|
|
|
130 public Attribute attribute(String name, String value, int type);
|
|
|
131
|
|
|
132 // **** constructing CDATA ****
|
|
|
133
|
|
|
134 /**
|
|
|
135 * This creates the CDATA with the supplied text.
|
|
|
136 *
|
|
|
137 * @param str <code>String</code> content of CDATA.
|
|
|
138 */
|
|
|
139 public CDATA cdata(String str);
|
|
|
140
|
|
|
141 // **** constructing Text ****
|
|
|
142
|
|
|
143 /**
|
|
|
144 * This creates the Text with the supplied text.
|
|
|
145 *
|
|
|
146 * @param str <code>String</code> content of Text.
|
|
|
147 */
|
|
|
148 public Text text(String str);
|
|
|
149
|
|
|
150 // **** constructing Comment ****
|
|
|
151
|
|
|
152 /**
|
|
|
153 * This creates the comment with the supplied text.
|
|
|
154 *
|
|
|
155 * @param text <code>String</code> content of comment.
|
|
|
156 */
|
|
|
157 public Comment comment(String text);
|
|
|
158
|
|
|
159 // **** constructing DocType
|
|
|
160
|
|
|
161 /**
|
|
|
162 * This will create the <code>DocType</code> with
|
|
|
163 * the specified element name and a reference to an
|
|
|
164 * external DTD.
|
|
|
165 *
|
|
|
166 * @param elementName <code>String</code> name of
|
|
|
167 * element being constrained.
|
|
|
168 * @param publicID <code>String</code> public ID of
|
|
|
169 * referenced DTD
|
|
|
170 * @param systemID <code>String</code> system ID of
|
|
|
171 * referenced DTD
|
|
|
172 */
|
|
|
173 public DocType docType(String elementName,
|
|
|
174 String publicID, String systemID);
|
|
|
175
|
|
|
176 /**
|
|
|
177 * This will create the <code>DocType</code> with
|
|
|
178 * the specified element name and reference to an
|
|
|
179 * external DTD.
|
|
|
180 *
|
|
|
181 * @param elementName <code>String</code> name of
|
|
|
182 * element being constrained.
|
|
|
183 * @param systemID <code>String</code> system ID of
|
|
|
184 * referenced DTD
|
|
|
185 */
|
|
|
186 public DocType docType(String elementName, String systemID);
|
|
|
187
|
|
|
188 /**
|
|
|
189 * This will create the <code>DocType</code> with
|
|
|
190 * the specified element name
|
|
|
191 *
|
|
|
192 * @param elementName <code>String</code> name of
|
|
|
193 * element being constrained.
|
|
|
194 */
|
|
|
195 public DocType docType(String elementName);
|
|
|
196
|
|
|
197 // **** constructing Document
|
|
|
198
|
|
|
199 /**
|
|
|
200 * This will create a new <code>Document</code>,
|
|
|
201 * with the supplied <code>{@link org.jdom.Element}</code>
|
|
|
202 * as the root element and the supplied
|
|
|
203 * <code>{@link org.jdom.DocType}</code> declaration.
|
|
|
204 *
|
|
|
205 * @param rootElement <code>Element</code> for document root.
|
|
|
206 * @param docType <code>DocType</code> declaration.
|
|
|
207 */
|
|
|
208 public Document document(Element rootElement, DocType docType);
|
|
|
209
|
|
|
210 /**
|
|
|
211 * This will create a new <code>Document</code>,
|
|
|
212 * with the supplied <code>{@link org.jdom.Element}</code>
|
|
|
213 * as the root element and the supplied
|
|
|
214 * <code>{@link org.jdom.DocType}</code> declaration.
|
|
|
215 *
|
|
|
216 * @param rootElement <code>Element</code> for document root.
|
|
|
217 * @param docType <code>DocType</code> declaration.
|
|
|
218 * @param baseURI the URI from which this doucment was loaded.
|
|
|
219 */
|
|
|
220 public Document document(Element rootElement, DocType docType, String baseURI);
|
|
|
221
|
|
|
222 /**
|
|
|
223 * This will create a new <code>Document</code>,
|
|
|
224 * with the supplied <code>{@link org.jdom.Element}</code>
|
|
|
225 * as the root element, and no <code>{@link org.jdom.DocType}</code>
|
|
|
226 * declaration.
|
|
|
227 *
|
|
|
228 * @param rootElement <code>Element</code> for document root
|
|
|
229 */
|
|
|
230 public Document document(Element rootElement);
|
|
|
231
|
|
|
232 // **** constructing Elements ****
|
|
|
233
|
|
|
234 /**
|
|
|
235 * This will create a new <code>Element</code>
|
|
|
236 * with the supplied (local) name, and define
|
|
|
237 * the <code>{@link org.jdom.Namespace}</code> to be used.
|
|
|
238 *
|
|
|
239 * @param name <code>String</code> name of element.
|
|
|
240 * @param namespace <code>Namespace</code> to put element in.
|
|
|
241 */
|
|
|
242 public Element element(String name, Namespace namespace);
|
|
|
243
|
|
|
244 /**
|
|
|
245 * This will create an <code>Element</code> in no
|
|
|
246 * <code>{@link org.jdom.Namespace}</code>.
|
|
|
247 *
|
|
|
248 * @param name <code>String</code> name of element.
|
|
|
249 */
|
|
|
250 public Element element(String name);
|
|
|
251
|
|
|
252 /**
|
|
|
253 * This will create a new <code>Element</code> with
|
|
|
254 * the supplied (local) name, and specifies the URI
|
|
|
255 * of the <code>{@link org.jdom.Namespace}</code> the <code>Element</code>
|
|
|
256 * should be in, resulting it being unprefixed (in the default
|
|
|
257 * namespace).
|
|
|
258 *
|
|
|
259 * @param name <code>String</code> name of element.
|
|
|
260 * @param uri <code>String</code> URI for <code>Namespace</code> element
|
|
|
261 * should be in.
|
|
|
262 */
|
|
|
263 public Element element(String name, String uri);
|
|
|
264
|
|
|
265 /**
|
|
|
266 * This will create a new <code>Element</code> with
|
|
|
267 * the supplied (local) name, and specifies the prefix and URI
|
|
|
268 * of the <code>{@link org.jdom.Namespace}</code> the <code>Element</code>
|
|
|
269 * should be in.
|
|
|
270 *
|
|
|
271 * @param name <code>String</code> name of element.
|
|
|
272 * @param uri <code>String</code> URI for <code>Namespace</code> element
|
|
|
273 * should be in.
|
|
|
274 */
|
|
|
275 public Element element(String name, String prefix, String uri);
|
|
|
276
|
|
|
277 // **** constructing ProcessingInstruction ****
|
|
|
278
|
|
|
279 /**
|
|
|
280 * This will create a new <code>ProcessingInstruction</code>
|
|
|
281 * with the specified target and data.
|
|
|
282 *
|
|
|
283 * @param target <code>String</code> target of PI.
|
|
|
284 * @param data <code>Map</code> data for PI, in
|
|
|
285 * name/value pairs
|
|
|
286 */
|
|
|
287 public ProcessingInstruction processingInstruction(String target,
|
|
|
288 Map data);
|
|
|
289
|
|
|
290 /**
|
|
|
291 * This will create a new <code>ProcessingInstruction</code>
|
|
|
292 * with the specified target and data.
|
|
|
293 *
|
|
|
294 * @param target <code>String</code> target of PI.
|
|
|
295 * @param data <code>String</code> data for PI.
|
|
|
296 */
|
|
|
297 public ProcessingInstruction processingInstruction(String target,
|
|
|
298 String data);
|
|
|
299
|
|
|
300 // **** constructing EntityRef ****
|
|
|
301
|
|
|
302 /**
|
|
|
303 * This will create a new <code>EntityRef</code>
|
|
|
304 * with the supplied name.
|
|
|
305 *
|
|
|
306 * @param name <code>String</code> name of element.
|
|
|
307 */
|
|
|
308 public EntityRef entityRef(String name);
|
|
|
309
|
|
|
310 /**
|
|
|
311 * This will create a new <code>EntityRef</code>
|
|
|
312 * with the supplied name, public ID, and system ID.
|
|
|
313 *
|
|
|
314 * @param name <code>String</code> name of element.
|
|
|
315 * @param publicID <code>String</code> public ID of element.
|
|
|
316 * @param systemID <code>String</code> system ID of element.
|
|
|
317 */
|
|
|
318 public EntityRef entityRef(String name, String publicID, String systemID);
|
|
|
319
|
|
|
320 /**
|
|
|
321 * This will create a new <code>EntityRef</code>
|
|
|
322 * with the supplied name and system ID.
|
|
|
323 *
|
|
|
324 * @param name <code>String</code> name of element.
|
|
|
325 * @param systemID <code>String</code> system ID of element.
|
|
|
326 */
|
|
|
327 public EntityRef entityRef(String name, String systemID);
|
|
|
328
|
|
|
329 // =====================================================================
|
|
|
330 // List manipulation
|
|
|
331 // =====================================================================
|
|
|
332
|
|
|
333 public void addContent(Parent parent, Content content);
|
|
|
334
|
|
|
335 public void setAttribute(Element element, Attribute a);
|
|
|
336
|
|
|
337 public void addNamespaceDeclaration(Element element, Namespace additional);
|
|
|
338 }
|
