JDOMFactory


1   /*--
2   
3    $Id: JDOMFactory.java,v 1.8 2004/09/01 05:25:38 jhunter Exp $
4   
5    Copyright (C) 2000-2004 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.8 $, $Date: 2004/09/01 05:25:38 $
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 }
339
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags