001: /*--
002:
003: $Id: JDOMFactory.java,v 1.8 2004/09/01 05:25:38 jhunter Exp $
004:
005: Copyright (C) 2000-2004 Jason Hunter & Brett McLaughlin.
006: All rights reserved.
007:
008: Redistribution and use in source and binary forms, with or without
009: modification, are permitted provided that the following conditions
010: are met:
011:
012: 1. Redistributions of source code must retain the above copyright
013: notice, this list of conditions, and the following disclaimer.
014:
015: 2. Redistributions in binary form must reproduce the above copyright
016: notice, this list of conditions, and the disclaimer that follows
017: these conditions in the documentation and/or other materials
018: provided with the distribution.
019:
020: 3. The name "JDOM" must not be used to endorse or promote products
021: derived from this software without prior written permission. For
022: written permission, please contact <request_AT_jdom_DOT_org>.
023:
024: 4. Products derived from this software may not be called "JDOM", nor
025: may "JDOM" appear in their name, without prior written permission
026: from the JDOM Project Management <request_AT_jdom_DOT_org>.
027:
028: In addition, we request (but do not require) that you include in the
029: end-user documentation provided with the redistribution and/or in the
030: software itself an acknowledgement equivalent to the following:
031: "This product includes software developed by the
032: JDOM Project (http://www.jdom.org/)."
033: Alternatively, the acknowledgment may be graphical using the logos
034: available at http://www.jdom.org/images/logos.
035:
036: THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
037: WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
038: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
039: DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
040: CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
041: SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
042: LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
043: USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
044: ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
045: OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
046: OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
047: SUCH DAMAGE.
048:
049: This software consists of voluntary contributions made by many
050: individuals on behalf of the JDOM Project and was originally
051: created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
052: Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information
053: on the JDOM Project, please see <http://www.jdom.org/>.
054:
055: */
056:
057: package org.jdom;
058:
059: import java.util.*;
060:
061: /**
062: * An interface to be used by builders when constructing JDOM objects. The
063: * <code>DefaultJDOMFactory</code> creates the standard top-level JDOM classes
064: * (Element, Document, Comment, etc). Another implementation of this factory
065: * could be used to create custom classes.
066: *
067: * @version $Revision: 1.8 $, $Date: 2004/09/01 05:25:38 $
068: * @author Ken Rune Holland
069: * @author Phil Nelson
070: * @author Bradley S. Huffman
071: */
072: public interface JDOMFactory {
073:
074: // **** constructing Attributes ****
075:
076: /**
077: * <p>
078: * This will create a new <code>Attribute</code> with the
079: * specified (local) name and value, and in the provided
080: * <code>{@link org.jdom.Namespace}</code>.
081: * </p>
082: *
083: * @param name <code>String</code> name of <code>Attribute</code>.
084: * @param value <code>String</code> value for new attribute.
085: */
086: public Attribute attribute(String name, String value,
087: Namespace namespace);
088:
089: /**
090: * This will create a new <code>Attribute</code> with the
091: * specified (local) name, value, and type, and in the provided
092: * <code>{@link org.jdom.Namespace}</code>.
093: *
094: * @param name <code>String</code> name of <code>Attribute</code>.
095: * @param value <code>String</code> value for new attribute.
096: * @param type <code>int</code> type for new attribute.
097: * @param namespace <code>Namespace</code> namespace for new attribute.
098: */
099: public Attribute attribute(String name, String value, int type,
100: Namespace namespace);
101:
102: /**
103: * This will create a new <code>Attribute</code> with the
104: * specified (local) name and value, and does not place
105: * the attribute in a <code>{@link org.jdom.Namespace}</code>.
106: * <p>
107: * <b>Note</b>: This actually explicitly puts the
108: * <code>Attribute</code> in the "empty" <code>Namespace</code>
109: * (<code>{@link org.jdom.Namespace#NO_NAMESPACE}</code>).
110: * </p>
111: *
112: * @param name <code>String</code> name of <code>Attribute</code>.
113: * @param value <code>String</code> value for new attribute.
114: */
115: public Attribute attribute(String name, String value);
116:
117: /**
118: * This will create a new <code>Attribute</code> with the
119: * specified (local) name, value and type, and does not place
120: * the attribute in a <code>{@link org.jdom.Namespace}</code>.
121: * <p>
122: * <b>Note</b>: This actually explicitly puts the
123: * <code>Attribute</code> in the "empty" <code>Namespace</code>
124: * (<code>{@link org.jdom.Namespace#NO_NAMESPACE}</code>).
125: * </p>
126: *
127: * @param name <code>String</code> name of <code>Attribute</code>.
128: * @param value <code>String</code> value for new attribute.
129: * @param type <code>int</code> type for new attribute.
130: */
131: public Attribute attribute(String name, String value, int type);
132:
133: // **** constructing CDATA ****
134:
135: /**
136: * This creates the CDATA with the supplied text.
137: *
138: * @param str <code>String</code> content of CDATA.
139: */
140: public CDATA cdata(String str);
141:
142: // **** constructing Text ****
143:
144: /**
145: * This creates the Text with the supplied text.
146: *
147: * @param str <code>String</code> content of Text.
148: */
149: public Text text(String str);
150:
151: // **** constructing Comment ****
152:
153: /**
154: * This creates the comment with the supplied text.
155: *
156: * @param text <code>String</code> content of comment.
157: */
158: public Comment comment(String text);
159:
160: // **** constructing DocType
161:
162: /**
163: * This will create the <code>DocType</code> with
164: * the specified element name and a reference to an
165: * external DTD.
166: *
167: * @param elementName <code>String</code> name of
168: * element being constrained.
169: * @param publicID <code>String</code> public ID of
170: * referenced DTD
171: * @param systemID <code>String</code> system ID of
172: * referenced DTD
173: */
174: public DocType docType(String elementName, String publicID,
175: String systemID);
176:
177: /**
178: * This will create the <code>DocType</code> with
179: * the specified element name and reference to an
180: * external DTD.
181: *
182: * @param elementName <code>String</code> name of
183: * element being constrained.
184: * @param systemID <code>String</code> system ID of
185: * referenced DTD
186: */
187: public DocType docType(String elementName, String systemID);
188:
189: /**
190: * This will create the <code>DocType</code> with
191: * the specified element name
192: *
193: * @param elementName <code>String</code> name of
194: * element being constrained.
195: */
196: public DocType docType(String elementName);
197:
198: // **** constructing Document
199:
200: /**
201: * This will create a new <code>Document</code>,
202: * with the supplied <code>{@link org.jdom.Element}</code>
203: * as the root element and the supplied
204: * <code>{@link org.jdom.DocType}</code> declaration.
205: *
206: * @param rootElement <code>Element</code> for document root.
207: * @param docType <code>DocType</code> declaration.
208: */
209: public Document document(Element rootElement, DocType docType);
210:
211: /**
212: * This will create a new <code>Document</code>,
213: * with the supplied <code>{@link org.jdom.Element}</code>
214: * as the root element and the supplied
215: * <code>{@link org.jdom.DocType}</code> declaration.
216: *
217: * @param rootElement <code>Element</code> for document root.
218: * @param docType <code>DocType</code> declaration.
219: * @param baseURI the URI from which this doucment was loaded.
220: */
221: public Document document(Element rootElement, DocType docType,
222: String baseURI);
223:
224: /**
225: * This will create a new <code>Document</code>,
226: * with the supplied <code>{@link org.jdom.Element}</code>
227: * as the root element, and no <code>{@link org.jdom.DocType}</code>
228: * declaration.
229: *
230: * @param rootElement <code>Element</code> for document root
231: */
232: public Document document(Element rootElement);
233:
234: // **** constructing Elements ****
235:
236: /**
237: * This will create a new <code>Element</code>
238: * with the supplied (local) name, and define
239: * the <code>{@link org.jdom.Namespace}</code> to be used.
240: *
241: * @param name <code>String</code> name of element.
242: * @param namespace <code>Namespace</code> to put element in.
243: */
244: public Element element(String name, Namespace namespace);
245:
246: /**
247: * This will create an <code>Element</code> in no
248: * <code>{@link org.jdom.Namespace}</code>.
249: *
250: * @param name <code>String</code> name of element.
251: */
252: public Element element(String name);
253:
254: /**
255: * This will create a new <code>Element</code> with
256: * the supplied (local) name, and specifies the URI
257: * of the <code>{@link org.jdom.Namespace}</code> the <code>Element</code>
258: * should be in, resulting it being unprefixed (in the default
259: * namespace).
260: *
261: * @param name <code>String</code> name of element.
262: * @param uri <code>String</code> URI for <code>Namespace</code> element
263: * should be in.
264: */
265: public Element element(String name, String uri);
266:
267: /**
268: * This will create a new <code>Element</code> with
269: * the supplied (local) name, and specifies the prefix and URI
270: * of the <code>{@link org.jdom.Namespace}</code> the <code>Element</code>
271: * should be in.
272: *
273: * @param name <code>String</code> name of element.
274: * @param uri <code>String</code> URI for <code>Namespace</code> element
275: * should be in.
276: */
277: public Element element(String name, String prefix, String uri);
278:
279: // **** constructing ProcessingInstruction ****
280:
281: /**
282: * This will create a new <code>ProcessingInstruction</code>
283: * with the specified target and data.
284: *
285: * @param target <code>String</code> target of PI.
286: * @param data <code>Map</code> data for PI, in
287: * name/value pairs
288: */
289: public ProcessingInstruction processingInstruction(String target,
290: Map data);
291:
292: /**
293: * This will create a new <code>ProcessingInstruction</code>
294: * with the specified target and data.
295: *
296: * @param target <code>String</code> target of PI.
297: * @param data <code>String</code> data for PI.
298: */
299: public ProcessingInstruction processingInstruction(String target,
300: String data);
301:
302: // **** constructing EntityRef ****
303:
304: /**
305: * This will create a new <code>EntityRef</code>
306: * with the supplied name.
307: *
308: * @param name <code>String</code> name of element.
309: */
310: public EntityRef entityRef(String name);
311:
312: /**
313: * This will create a new <code>EntityRef</code>
314: * with the supplied name, public ID, and system ID.
315: *
316: * @param name <code>String</code> name of element.
317: * @param publicID <code>String</code> public ID of element.
318: * @param systemID <code>String</code> system ID of element.
319: */
320: public EntityRef entityRef(String name, String publicID,
321: String systemID);
322:
323: /**
324: * This will create a new <code>EntityRef</code>
325: * with the supplied name and system ID.
326: *
327: * @param name <code>String</code> name of element.
328: * @param systemID <code>String</code> system ID of element.
329: */
330: public EntityRef entityRef(String name, String systemID);
331:
332: // =====================================================================
333: // List manipulation
334: // =====================================================================
335:
336: public void addContent(Parent parent, Content content);
337:
338: public void setAttribute(Element element, Attribute a);
339:
340: public void addNamespaceDeclaration(Element element,
341: Namespace additional);
342: }
|