KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javolution > xml > stream > XMLInputFactory


1 /*
2  * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
3  * Copyright (C) 2005 - Javolution (http://javolution.org/)
4  * All rights reserved.
5  *
6  * Permission to use, copy, modify, and distribute this software is
7  * freely granted, provided that this notice is preserved.
8  */
9 package javolution.xml.stream;
10
11 import java.io.InputStream JavaDoc;
12 import java.io.Reader JavaDoc;
13 import j2me.util.Map;
14 import javolution.context.ObjectFactory;
15
16 /**
17  * <p> The class represents the factory for getting {@link XMLStreamReader}
18  * intances.
19  *
20  * <p> The {@link #newInstance() default implementation} automatically
21  * {@link ObjectFactory#recycle recycles} any reader which has been
22  * {@link XMLStreamReader#close() closed}.</p>
23  *
24  * <P> Usage example:[code]
25  *
26  * // Lets read a CharSequence input.
27  * String xml = "...";
28  * CharSequenceReader in = new CharSequenceReader().setInput(xml);
29
30  * // Creates a factory of readers coalescing adjacent character data.
31  * XMLInputFactory factory = XMLInputFactory.newInstance();
32  * factory.setProperty(XMLInputFactory.IS_COALESCING, true);
33  *
34  * // Creates a new reader (potentially recycled).
35  * XMLStreamReader reader = factory.createXMLStreamReader(in);
36  *
37  * // Parses XML.
38  * for (int e=reader.next(); e != XMLStreamConstants.END_DOCUMENT; e = reader.next()) {
39  * switch (e) { // Event.
40  * ...
41  * }
42  * }
43  * reader.close(); // Automatically recycles this writer.
44  * in.close(); // Underlying input should be closed explicitly.
45  * [/code]</p>
46  *
47  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
48  * @version 4.0, September 4, 2006
49  */
50 public abstract class XMLInputFactory {
51
52     /**
53      * The property that requires the parser to coalesce adjacent character data
54      * sections (type: <code>Boolean</code>, default: <code>FALSE</code>)
55      */
56     public static final String JavaDoc IS_COALESCING = "javolution.xml.stream.isCoalescing";
57
58     /**
59      * Property used to specify additional entities to be recognized by the
60      * readers (type: <code>java.util.Map</code>, default: <code>null</code>).
61      * For example:[code]
62      * FastMap<String, String> HTML_ENTITIES = new FastMap<String, String>();
63      * HTML_ENTITIES.put("nbsp", " ");
64      * HTML_ENTITIES.put("copy", "©");
65      * HTML_ENTITIES.put("eacute", "é");
66      * ...
67      * XMLInputFactory factory = XMLInputFactory.newInstance();
68      * factory.setProperty(ENTITIES, HTML_ENTITIES);
69      * [/code]
70      */
71     public static final String JavaDoc ENTITIES = "javolution.xml.stream.entities";
72
73     /**
74      * Default constructor.
75      */
76     protected XMLInputFactory() {
77     }
78
79     /**
80      * Returns a new instance of the default factory which may be configurated
81      * by the user (see {@link #setProperty(String, Object)}).
82      *
83      * @return a new factory instance.
84      */
85     public static XMLInputFactory newInstance() {
86         return new Default();
87     }
88
89     /**
90      * Returns a XML stream reader for the specified I/O reader.
91      *
92      * @param reader the XML data to read from.
93      * @throws XMLStreamException
94      */
95     public abstract XMLStreamReader createXMLStreamReader(Reader JavaDoc reader)
96             throws XMLStreamException;
97
98     /**
99      * Returns a XML stream reader for the specified input stream
100      * (encoding autodetected).
101      *
102      * @param stream the input stream to read from.
103      * @throws XMLStreamException
104      */
105     public abstract XMLStreamReader createXMLStreamReader(InputStream JavaDoc stream)
106             throws XMLStreamException;
107
108     /**
109      * Returns a XML stream reader for the specified input stream using the
110      * specified encoding.
111      *
112      * @param stream the input stream to read from.
113      * @param encoding the character encoding of the stream.
114      * @throws XMLStreamException
115      */
116     public abstract XMLStreamReader createXMLStreamReader(InputStream JavaDoc stream,
117             String JavaDoc encoding) throws XMLStreamException;
118
119     /**
120      * Allows the user to set specific feature/property on the underlying
121      * implementation. The underlying implementation is not required to support
122      * every setting of every property in the specification and may use
123      * <code>IllegalArgumentException</code> to signal that an unsupported
124      * property may not be set with the specified value.
125      *
126      * @param name the name of the property.
127      * @param value the value of the property
128      * @throws IllegalArgumentException if the property is not supported.
129      */
130     public abstract void setProperty(String JavaDoc name, Object JavaDoc value)
131             throws IllegalArgumentException JavaDoc;
132
133     /**
134      * Gets the value of a feature/property from the underlying implementation.
135      *
136      * @param name the name of the property (may not be null).
137      * @return the value of the property.
138      * @throws IllegalArgumentException if the property is not supported.
139      */
140     public abstract Object JavaDoc getProperty(String JavaDoc name)
141             throws IllegalArgumentException JavaDoc;
142
143     /**
144      * Queries the set of properties that this factory supports.
145      *
146      * @param name the name of the property.
147      * @return <code>true</code> if the property is supported;
148      * <code>false</code> otherwise.
149      */
150     public abstract boolean isPropertySupported(String JavaDoc name);
151
152     /**
153      * This class represents the default factory implementation.
154      */
155     private static class Default extends XMLInputFactory {
156         
157         Map _entities = null;
158
159         // Implements XMLInputFactory abstract method.
160 public XMLStreamReader createXMLStreamReader(Reader JavaDoc reader)
161                 throws XMLStreamException {
162             XMLStreamReaderImpl xmlReader = newReader();
163             xmlReader.setInput(reader);
164             return xmlReader;
165         }
166
167         // Implements XMLInputFactory abstract method.
168 public XMLStreamReader createXMLStreamReader(InputStream JavaDoc stream)
169                 throws XMLStreamException {
170             XMLStreamReaderImpl xmlReader = newReader();
171             xmlReader.setInput(stream);
172             return xmlReader;
173         }
174
175         // Implements XMLInputFactory abstract method.
176 public XMLStreamReader createXMLStreamReader(InputStream JavaDoc stream,
177                 String JavaDoc encoding) throws XMLStreamException {
178             XMLStreamReaderImpl xmlReader = newReader();
179             xmlReader.setInput(stream, encoding);
180             return xmlReader;
181         }
182
183         // Implements XMLInputFactory abstract method.
184 public void setProperty(String JavaDoc name, Object JavaDoc value)
185                 throws IllegalArgumentException JavaDoc {
186             if (name.equals(IS_COALESCING)) {
187                 // Do nothing, always coalescing.
188 } else if (name.equals(ENTITIES)) {
189                  _entities = (Map) value;
190             } else {
191                 throw new IllegalArgumentException JavaDoc("Property: " + name
192                         + " not supported");
193             }
194         }
195
196         // Implements XMLInputFactory abstract method.
197 public Object JavaDoc getProperty(String JavaDoc name) throws IllegalArgumentException JavaDoc {
198             if (name.equals(IS_COALESCING)) {
199                 return new Boolean JavaDoc(true);
200             } else if (name.equals(ENTITIES)) {
201                 return _entities;
202             } else {
203                 throw new IllegalArgumentException JavaDoc("Property: " + name
204                         + " not supported");
205             }
206         }
207
208         // Implements XMLInputFactory abstract method.
209 public boolean isPropertySupported(String JavaDoc name) {
210             return name.equals(IS_COALESCING) ||
211                name.equals(ENTITIES);
212         }
213         
214         private XMLStreamReaderImpl newReader() {
215             XMLStreamReaderImpl xmlReader
216                 = (XMLStreamReaderImpl) XML_READER_FACTORY.object();
217             if (_entities != null) {
218                 xmlReader.setEntities(_entities);
219             }
220             xmlReader._objectFactory = XML_READER_FACTORY;
221             return xmlReader;
222         }
223     }
224
225     private static ObjectFactory XML_READER_FACTORY = new ObjectFactory() {
226
227         protected Object JavaDoc create() {
228             return new XMLStreamReaderImpl();
229         }
230
231         protected void cleanup(Object JavaDoc obj) {
232             ((XMLStreamReaderImpl) obj).reset();
233         }
234     };
235
236 }
Popular Tags