001: package javax.xml.stream;
002:
003: import javax.xml.stream.events.*;
004: import javax.xml.namespace.NamespaceContext;
005: import javax.xml.namespace.QName;
006: import java.util.Iterator;
007:
008: /**
009: * This interface defines a utility class for creating instances of
010: * XMLEvents
011: * @version 1.0
012: * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
013: * @see javax.xml.stream.events.StartElement
014: * @see javax.xml.stream.events.EndElement
015: * @see javax.xml.stream.events.ProcessingInstruction
016: * @see javax.xml.stream.events.Comment
017: * @see javax.xml.stream.events.Characters
018: * @see javax.xml.stream.events.StartDocument
019: * @see javax.xml.stream.events.EndDocument
020: * @see javax.xml.stream.events.DTD
021: */
022: public abstract class XMLEventFactory {
023: protected XMLEventFactory() {
024: }
025:
026: /**
027: * Create a new instance of the factory
028: * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
029: */
030: public static XMLEventFactory newInstance()
031: throws FactoryConfigurationError {
032: return (XMLEventFactory) FactoryFinder.find(
033: "javax.xml.stream.XMLEventFactory",
034: "com.bea.xml.stream.EventFactory");
035: }
036:
037: /**
038: * Create a new instance of the factory
039: *
040: * @param factoryId Name of the factory to find, same as
041: * a property name
042: * @param classLoader classLoader to use
043: * @return the factory implementation
044: * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
045: */
046: public static XMLEventFactory newInstance(String factoryId,
047: ClassLoader classLoader) throws FactoryConfigurationError {
048: return (XMLEventFactory) FactoryFinder.find(factoryId,
049: "com.bea.xml.stream.EventFactory", classLoader);
050: }
051:
052: /**
053: * This method allows setting of the Location on each event that
054: * is created by this factory. The values are copied by value into
055: * the events created by this factory. To reset the location
056: * information set the location to null.
057: * @param location the location to set on each event created
058: */
059: public abstract void setLocation(Location location);
060:
061: /**
062: * Create a new Attribute
063: * @param prefix the prefix of this attribute, may not be null
064: * @param namespaceURI the attribute value is set to this value, may not be null
065: * @param localName the local name of the XML name of the attribute, localName cannot be null
066: * @param value the attribute value to set, may not be null
067: * @return the Attribute with specified values
068: */
069: public abstract Attribute createAttribute(String prefix,
070: String namespaceURI, String localName, String value);
071:
072: /**
073: * Create a new Attribute
074: * @param localName the local name of the XML name of the attribute, localName cannot be null
075: * @param value the attribute value to set, may not be null
076: * @return the Attribute with specified values
077: */
078: public abstract Attribute createAttribute(String localName,
079: String value);
080:
081: /**
082: * Create a new Attribute
083: * @param name the qualified name of the attribute, may not be null
084: * @param value the attribute value to set, may not be null
085: * @return the Attribute with specified values
086: */
087: public abstract Attribute createAttribute(QName name, String value);
088:
089: /**
090: * Create a new default Namespace
091: * @param namespaceURI the default namespace uri
092: * @return the Namespace with the specified value
093: */
094: public abstract Namespace createNamespace(String namespaceURI);
095:
096: /**
097: * Create a new Namespace
098: * @param prefix the prefix of this namespace, may not be null
099: * @param namespaceUri the attribute value is set to this value, may not be null
100: * @return the Namespace with the specified values
101: */
102: public abstract Namespace createNamespace(String prefix,
103: String namespaceUri);
104:
105: /**
106: * Create a new StartElement. Namespaces can be added to this StartElement
107: * by passing in an Iterator that walks over a set of Namespace interfaces.
108: * Attributes can be added to this StartElement by passing an iterator
109: * that walks over a set of Attribute interfaces.
110: *
111: * @param name the qualified name of the attribute, may not be null
112: * @param attributes an optional unordered set of objects that
113: * implement Attribute to add to the new StartElement, may be null
114: * @param namespaces an optional unordered set of objects that
115: * implement Namespace to add to the new StartElement, may be null
116: * @return an instance of the requested StartElement
117: */
118: public abstract StartElement createStartElement(QName name,
119: Iterator attributes, Iterator namespaces);
120:
121: /**
122: * Create a new StartElement. This defaults the NamespaceContext to
123: * an empty NamespaceContext. Querying this event for its namespaces or
124: * attributes will result in an empty iterator being returned.
125: *
126: * @param namespaceUri the uri of the QName of the new StartElement
127: * @param localName the local name of the QName of the new StartElement
128: * @param prefix the prefix of the QName of the new StartElement
129: * @return an instance of the requested StartElement
130: */
131: public abstract StartElement createStartElement(String prefix,
132: String namespaceUri, String localName);
133:
134: /**
135: * Create a new StartElement. Namespaces can be added to this StartElement
136: * by passing in an Iterator that walks over a set of Namespace interfaces.
137: * Attributes can be added to this StartElement by passing an iterator
138: * that walks over a set of Attribute interfaces.
139: *
140: * @param namespaceUri the uri of the QName of the new StartElement
141: * @param localName the local name of the QName of the new StartElement
142: * @param prefix the prefix of the QName of the new StartElement
143: * @param attributes an unordered set of objects that implement
144: * Attribute to add to the new StartElement
145: * @param namespaces an unordered set of objects that implement
146: * Namespace to add to the new StartElement
147: * @return an instance of the requested StartElement
148: */
149: public abstract StartElement createStartElement(String prefix,
150: String namespaceUri, String localName, Iterator attributes,
151: Iterator namespaces);
152:
153: /**
154: * Create a new StartElement. Namespaces can be added to this StartElement
155: * by passing in an Iterator that walks over a set of Namespace interfaces.
156: * Attributes can be added to this StartElement by passing an iterator
157: * that walks over a set of Attribute interfaces.
158: *
159: * @param namespaceUri the uri of the QName of the new StartElement
160: * @param localName the local name of the QName of the new StartElement
161: * @param prefix the prefix of the QName of the new StartElement
162: * @param attributes an unordered set of objects that implement
163: * Attribute to add to the new StartElement, may be null
164: * @param namespaces an unordered set of objects that implement
165: * Namespace to add to the new StartElement, may be null
166: * @param context the namespace context of this element
167: * @return an instance of the requested StartElement
168: */
169: public abstract StartElement createStartElement(String prefix,
170: String namespaceUri, String localName, Iterator attributes,
171: Iterator namespaces, NamespaceContext context);
172:
173: /**
174: * Create a new EndElement
175: * @param name the qualified name of the EndElement
176: * @param namespaces an optional unordered set of objects that
177: * implement Namespace that have gone out of scope, may be null
178: * @return an instance of the requested EndElement
179: */
180: public abstract EndElement createEndElement(QName name,
181: Iterator namespaces);
182:
183: /**
184: * Create a new EndElement
185: * @param namespaceUri the uri of the QName of the new StartElement
186: * @param localName the local name of the QName of the new StartElement
187: * @param prefix the prefix of the QName of the new StartElement
188: * @return an instance of the requested EndElement
189: */
190: public abstract EndElement createEndElement(String prefix,
191: String namespaceUri, String localName);
192:
193: /**
194: * Create a new EndElement
195: * @param namespaceUri the uri of the QName of the new StartElement
196: * @param localName the local name of the QName of the new StartElement
197: * @param prefix the prefix of the QName of the new StartElement
198: * @param namespaces an unordered set of objects that implement
199: * Namespace that have gone out of scope, may be null
200: * @return an instance of the requested EndElement
201: */
202: public abstract EndElement createEndElement(String prefix,
203: String namespaceUri, String localName, Iterator namespaces);
204:
205: /**
206: * Create a Characters event, this method does not check if the content
207: * is all whitespace. To create a space event use #createSpace(String)
208: * @param content the string to create
209: * @return a Characters event
210: */
211: public abstract Characters createCharacters(String content);
212:
213: /**
214: * Create a Characters event with the CData flag set to true
215: * @param content the string to create
216: * @return a Characters event
217: */
218: public abstract Characters createCData(String content);
219:
220: /**
221: * Create a Characters event with the isSpace flag set to true
222: * @param content the content of the space to create
223: * @return a Characters event
224: */
225: public abstract Characters createSpace(String content);
226:
227: /**
228: * Create an ignorable space
229: * @param content the space to create
230: * @return a Characters event
231: */
232: public abstract Characters createIgnorableSpace(String content);
233:
234: /**
235: * Creates a new instance of a StartDocument event
236: * @return a StartDocument event
237: */
238: public abstract StartDocument createStartDocument();
239:
240: /**
241: * Creates a new instance of a StartDocument event
242: *
243: * @param encoding the encoding style
244: * @param version the XML version
245: * @param standalone the status of standalone may be set to "true" or "false"
246: * @return a StartDocument event
247: */
248: public abstract StartDocument createStartDocument(String encoding,
249: String version, boolean standalone);
250:
251: /**
252: * Creates a new instance of a StartDocument event
253: *
254: * @param encoding the encoding style
255: * @param version the XML version
256: * @return a StartDocument event
257: */
258: public abstract StartDocument createStartDocument(String encoding,
259: String version);
260:
261: /**
262: * Creates a new instance of a StartDocument event
263: *
264: * @param encoding the encoding style
265: * @return a StartDocument event
266: */
267: public abstract StartDocument createStartDocument(String encoding);
268:
269: /**
270: * Creates a new instance of an EndDocument event
271: * @return an EndDocument event
272: */
273: public abstract EndDocument createEndDocument();
274:
275: /** Creates a new instance of a EntityReference event
276: *
277: * @param name The name of the reference
278: * @param declaration the declaration for the event
279: * @return an EntityReference event
280: */
281: public abstract EntityReference createEntityReference(String name,
282: EntityDeclaration declaration);
283:
284: /**
285: * Create a comment
286: * @param text The text of the comment
287: * a Comment event
288: */
289: public abstract Comment createComment(String text);
290:
291: /**
292: * Create a processing instruction
293: * @param target The target of the processing instruction
294: * @param data The text of the processing instruction
295: * @return a ProcessingInstruction event
296: */
297: public abstract ProcessingInstruction createProcessingInstruction(
298: String target, String data);
299:
300: /**
301: * Create a document type definition event
302: * This string contains the entire document type declaration that matches
303: * the doctypedecl in the XML 1.0 specification
304: * @param dtd the text of the document type definition
305: * @return a DTD event
306: */
307: public abstract DTD createDTD(String dtd);
308: }
|