XMLEventFactory


1   package javax.xml.stream;
2   import javax.xml.stream.events.*;
3   import javax.xml.namespace.NamespaceContext  ;
4   import javax.xml.namespace.QName  ;
5   import java.util.Iterator  ;
6   /**
7    * This interface defines a utility class for creating instances of
8    * XMLEvents
9    * @version 1.0
10   * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
11   * @see javax.xml.stream.events.StartElement
12   * @see javax.xml.stream.events.EndElement
13   * @see javax.xml.stream.events.ProcessingInstruction
14   * @see javax.xml.stream.events.Comment
15   * @see javax.xml.stream.events.Characters
16   * @see javax.xml.stream.events.StartDocument
17   * @see javax.xml.stream.events.EndDocument
18   * @see javax.xml.stream.events.DTD
19   * @since 1.6
20   */
21  public abstract class XMLEventFactory {
22    protected XMLEventFactory(){}
23  
24    /**
25     * Create a new instance of the factory 
26     * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
27     */
28    public static XMLEventFactory newInstance() 
29      throws FactoryConfigurationError
30    {
31      return (XMLEventFactory) FactoryFinder.find(
32        "javax.xml.stream.XMLEventFactory",
33        "com.sun.xml.internal.stream.events.XMLEventFactoryImpl");
34    }
35  
36    /**
37     * Create a new instance of the factory 
38     *
39     * @param factoryId             Name of the factory to find, same as
40     *                              a property name
41     * @param classLoader           classLoader to use
42     * @return the factory implementation
43     * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
44     */
45    public static XMLEventFactory newInstance(String   factoryId,
46            ClassLoader   classLoader)
47            throws FactoryConfigurationError {
48        try {
49            //do not fallback if given classloader can't find the class, throw exception
50            return (XMLEventFactory) FactoryFinder.newInstance(factoryId, classLoader, false);
51        } catch (FactoryFinder.ConfigurationError e) {
52            throw new FactoryConfigurationError(e.getException(),
53                    e.getMessage());
54        }
55    }
56  
57   /**
58     * This method allows setting of the Location on each event that
59     * is created by this factory.  The values are copied by value into
60     * the events created by this factory.  To reset the location 
61     * information set the location to null.
62     * @param location the location to set on each event created
63     */
64    public abstract void setLocation(Location location);
65  
66    /**
67     * Create a new Attribute
68     * @param prefix the prefix of this attribute, may not be null
69     * @param namespaceURI the attribute value is set to this value, may not be null
70     * @param localName the local name of the XML name of the attribute, localName cannot be null
71     * @param value the attribute value to set, may not be null
72     * @return the Attribute with specified values
73     */
74    public abstract Attribute createAttribute(String   prefix, String   namespaceURI, String   localName, String   value);
75  
76    /**
77     * Create a new Attribute
78     * @param localName the local name of the XML name of the attribute, localName cannot be null
79     * @param value the attribute value to set, may not be null
80     * @return the Attribute with specified values
81     */
82    public abstract Attribute createAttribute(String   localName, String   value);
83  
84    /**
85     * Create a new Attribute
86     * @param name the qualified name of the attribute, may not be null
87     * @param value the attribute value to set, may not be null
88     * @return the Attribute with specified values
89     */
90    public abstract Attribute createAttribute(QName   name, String   value);
91  
92    /**
93     * Create a new default Namespace
94     * @param namespaceURI the default namespace uri
95     * @return the Namespace with the specified value
96     */
97    public abstract Namespace createNamespace(String   namespaceURI);
98  
99    /**
100    * Create a new Namespace
101    * @param prefix the prefix of this namespace, may not be null
102    * @param namespaceUri the attribute value is set to this value, may not be null
103    * @return the Namespace with the specified values
104    */
105   public abstract Namespace createNamespace(String   prefix, String   namespaceUri);
106 
107   /**
108    * Create a new StartElement.  Namespaces can be added to this StartElement
109    * by passing in an Iterator that walks over a set of Namespace interfaces.
110    * Attributes can be added to this StartElement by passing an iterator 
111    * that walks over a set of Attribute interfaces.
112    *
113    * @param name the qualified name of the attribute, may not be null
114    * @param attributes an optional unordered set of objects that 
115    * implement Attribute to add to the new StartElement, may be null
116    * @param namespaces an optional unordered set of objects that 
117    * implement Namespace to add to the new StartElement, may be null
118    * @return an instance of the requested StartElement
119    */
120   public abstract StartElement createStartElement(QName   name,
121                                                   Iterator   attributes,
122                                                   Iterator   namespaces);
123 
124   /**
125    * Create a new StartElement.  This defaults the NamespaceContext to
126    * an empty NamespaceContext.  Querying this event for its namespaces or
127    * attributes will result in an empty iterator being returned.
128    *
129    * @param namespaceUri the uri of the QName of the new StartElement
130    * @param localName the local name of the QName of the new StartElement
131    * @param prefix the prefix of the QName of the new StartElement
132    * @return an instance of the requested StartElement
133    */
134   public abstract StartElement createStartElement(String   prefix,
135                                                   String   namespaceUri,
136                                                   String   localName);
137   /**
138    * Create a new StartElement.  Namespaces can be added to this StartElement
139    * by passing in an Iterator that walks over a set of Namespace interfaces.
140    * Attributes can be added to this StartElement by passing an iterator 
141    * that walks over a set of Attribute interfaces.
142    *
143    * @param namespaceUri the uri of the QName of the new StartElement
144    * @param localName the local name of the QName of the new StartElement
145    * @param prefix the prefix of the QName of the new StartElement
146    * @param attributes an unordered set of objects that implement 
147    * Attribute to add to the new StartElement
148    * @param namespaces an unordered set of objects that implement 
149    * Namespace to add to the new StartElement
150    * @return an instance of the requested StartElement
151    */
152   public abstract StartElement createStartElement(String   prefix,
153                                                   String   namespaceUri,
154                                                   String   localName,
155                                                   Iterator   attributes,
156                                                   Iterator   namespaces
157                                                   );
158   /**
159    * Create a new StartElement.  Namespaces can be added to this StartElement
160    * by passing in an Iterator that walks over a set of Namespace interfaces.
161    * Attributes can be added to this StartElement by passing an iterator 
162    * that walks over a set of Attribute interfaces.
163    *
164    * @param namespaceUri the uri of the QName of the new StartElement
165    * @param localName the local name of the QName of the new StartElement
166    * @param prefix the prefix of the QName of the new StartElement
167    * @param attributes an unordered set of objects that implement 
168    * Attribute to add to the new StartElement, may be null
169    * @param namespaces an unordered set of objects that implement 
170    * Namespace to add to the new StartElement, may be null
171    * @param context the namespace context of this element
172    * @return an instance of the requested StartElement
173    */
174   public abstract StartElement createStartElement(String   prefix,
175                                                   String   namespaceUri,
176                                                   String   localName,
177                                                   Iterator   attributes,
178                                                   Iterator   namespaces,
179                                                   NamespaceContext   context
180                                                   );
181 
182   /**
183    * Create a new EndElement
184    * @param name the qualified name of the EndElement
185    * @param namespaces an optional unordered set of objects that 
186    * implement Namespace that have gone out of scope, may be null
187    * @return an instance of the requested EndElement
188    */
189   public abstract EndElement createEndElement(QName   name, 
190                                               Iterator   namespaces);
191 
192   /**
193    * Create a new EndElement
194    * @param namespaceUri the uri of the QName of the new StartElement
195    * @param localName the local name of the QName of the new StartElement
196    * @param prefix the prefix of the QName of the new StartElement
197    * @return an instance of the requested EndElement
198    */
199   public abstract EndElement createEndElement(String   prefix, 
200                                               String   namespaceUri,
201                                               String   localName);
202   /**
203    * Create a new EndElement
204    * @param namespaceUri the uri of the QName of the new StartElement
205    * @param localName the local name of the QName of the new StartElement
206    * @param prefix the prefix of the QName of the new StartElement
207    * @param namespaces an unordered set of objects that implement 
208    * Namespace that have gone out of scope, may be null
209    * @return an instance of the requested EndElement
210    */
211   public abstract EndElement createEndElement(String   prefix, 
212                                               String   namespaceUri,
213                                               String   localName,
214                                               Iterator   namespaces);
215 
216   /**
217    * Create a Characters event, this method does not check if the content
218    * is all whitespace.  To create a space event use #createSpace(String)
219    * @param content the string to create
220    * @return a Characters event
221    */
222   public abstract Characters createCharacters(String   content);
223 
224   /**
225    * Create a Characters event with the CData flag set to true
226    * @param content the string to create
227    * @return a Characters event
228    */
229   public abstract Characters createCData(String   content);
230 
231   /**
232    * Create a Characters event with the isSpace flag set to true
233    * @param content the content of the space to create
234    * @return a Characters event
235    */
236   public abstract Characters createSpace(String   content);
237   /**
238    * Create an ignorable space
239    * @param content the space to create
240    * @return a Characters event
241    */
242   public abstract Characters createIgnorableSpace(String   content);
243 
244   /** 
245    * Creates a new instance of a StartDocument event
246    * @return a StartDocument event
247    */
248   public abstract StartDocument createStartDocument();
249 
250   /** 
251    * Creates a new instance of a StartDocument event
252    *
253    * @param encoding the encoding style
254    * @param version the XML version
255    * @param standalone the status of standalone may be set to "true" or "false"
256    * @return a StartDocument event
257    */
258   public abstract StartDocument createStartDocument(String   encoding,
259                                                   String   version,
260                                                   boolean standalone);
261 
262   /** 
263    * Creates a new instance of a StartDocument event
264    *
265    * @param encoding the encoding style
266    * @param version the XML version
267    * @return a StartDocument event
268    */
269   public abstract StartDocument createStartDocument(String   encoding,
270                                                   String   version);
271 
272   /** 
273    * Creates a new instance of a StartDocument event
274    *
275    * @param encoding the encoding style
276    * @return a StartDocument event
277    */
278   public abstract StartDocument createStartDocument(String   encoding);
279 
280   /**
281    * Creates a new instance of an EndDocument event
282    * @return an EndDocument event
283    */
284   public abstract EndDocument createEndDocument();
285 
286   /** Creates a new instance of a EntityReference event
287    *
288    * @param name The name of the reference
289    * @param declaration the declaration for the event
290    * @return an EntityReference event
291    */
292   public abstract EntityReference createEntityReference(String   name,
293                                                         EntityDeclaration declaration);
294   /**
295    * Create a comment
296    * @param text The text of the comment
297    * a Comment event
298    */
299   public abstract Comment createComment(String   text);
300 
301   /**
302    * Create a processing instruction
303    * @param target The target of the processing instruction
304    * @param data The text of the processing instruction
305    * @return a ProcessingInstruction event
306    */
307   public abstract ProcessingInstruction createProcessingInstruction(String   target,
308                                                                    String   data);
309 
310   /**
311    * Create a document type definition event
312    * This string contains the entire document type declaration that matches
313    * the doctypedecl in the XML 1.0 specification
314    * @param dtd the text of the document type definition
315    * @return a DTD event
316    */
317   public abstract DTD createDTD(String   dtd);
318 }
319 
320 
321 
322 
323
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags