KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
3  * Copyright (C) 2006 - 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.OutputStream JavaDoc;
12 import java.io.Writer JavaDoc;
13
14 import javolution.context.ObjectFactory;
15
16 /**
17  * <p> The class represents the factory for getting {@link XMLStreamWriter}
18  * intances.</p>
19  *
20  * <p> The {@link #newInstance() default implementation} automatically
21  * {@link ObjectFactory#recycle recycles} any writer which has been
22  * {@link XMLStreamWriter#close() closed}.</p>
23  *
24  * <P> Usage example:[code]
25  *
26  * // Lets format to an appendable.
27  * TextBuilder xml = new TextBuilder();
28  * AppendableWriter out = new AppendableWriter(xml);
29  *
30  * // Creates a factory producing writers using tab indentation.
31  * XMLOutpuFactory factory = XMLOutputFactory.newInstance();
32  * factory.setProperty(XMLOutputFactory.INDENTATION, "/t");
33  *
34  * // Creates a new writer (potentially recycled).
35  * XMLStreamWriter writer = factory.createXMLStreamReader(out);
36  *
37  * // Formats to XML.
38  * writer.writeStartDocument();
39  * writer.writeStartElement(...);
40  * ...
41  * writer.close(); // Automatically recycles this writer.
42  * out.close(); // Underlying output should be closed explicitly.
43  *
44  * // Displays the formatted output.
45  * System.out.println(xml);
46  * [/code]</p>
47  *
48  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
49  * @version 4.0, September 4, 2006
50  */
51 public abstract class XMLOutputFactory {
52
53     /**
54      * Property used to set prefix defaulting on the output side
55      * (type: <code>Boolean</code>, default: <code>FALSE</code>).
56      */
57     public static final String JavaDoc IS_REPAIRING_NAMESPACES = "javolution.xml.stream.isRepairingNamespaces";
58
59     /**
60      * Property used to specify the prefix to be appended by a trailing
61      * part (a sequence number) in order to make it unique to be usable as
62      * a temporary non-colliding prefix when repairing namespaces
63      * (type: <code>String</code>, default: <code>"ns"</code>).
64      */
65     public final static String JavaDoc REPAIRING_PREFIX = "javolution.xml.stream.repairingPrefix";
66
67     /**
68      * Property used to specify an indentation string; non-null indentation
69      * forces the writer to write elements into separate lines
70      * (type: <code>String</code>, default: <code>null</code>).
71      */
72     public static final String JavaDoc INDENTATION = "javolution.xml.stream.indentation";
73
74     /**
75      * Property indicating if the stream writers are allowed to automatically
76      * output empty elements when a start element is immediately followed by
77      * matching end element
78      * (type: <code>Boolean</code>, default: <code>FALSE</code>).
79      */
80     public final static String JavaDoc AUTOMATIC_EMPTY_ELEMENTS = "javolution.xml.stream.automaticEmptyElements";
81
82      /**
83      * Default constructor.
84      */
85     protected XMLOutputFactory() {
86     }
87
88     /**
89      * Returns a new instance of the default factory which may be configurated
90      * by the user (see {@link #setProperty(String, Object)}).
91      *
92      * @return a new factory instance.
93      */
94     public static XMLOutputFactory newInstance() {
95         return new Default();
96     }
97
98     /**
99      * Returns a XML stream writer to the specified i/o writer.
100      *
101      * @param writer the writer to write to.
102      * @throws XMLStreamException
103      */
104     public abstract XMLStreamWriter createXMLStreamWriter(Writer JavaDoc writer)
105             throws XMLStreamException;
106
107     /**
108      * Returns a XML stream writer to the specified output stream (UTF-8
109      * encoding).
110      *
111      * @param stream the stream to write to.
112      * @throws XMLStreamException
113      */
114     public abstract XMLStreamWriter createXMLStreamWriter(OutputStream JavaDoc stream)
115             throws XMLStreamException;
116
117     /**
118      * Returns a XML stream writer to the specified output stream using the
119      * specified encoding.
120      *
121      * @param stream the stream to write to.
122      * @param encoding the encoding to use.
123      * @throws XMLStreamException
124      */
125     public abstract XMLStreamWriter createXMLStreamWriter(OutputStream JavaDoc stream,
126             String JavaDoc encoding) throws XMLStreamException;
127
128     /**
129      * Allows the user to set specific features/properties on the underlying
130      * implementation.
131      *
132      * @param name the name of the property.
133      * @param value the value of the property.
134      * @throws IllegalArgumentException if the property is not supported.
135      */
136     public abstract void setProperty(String JavaDoc name, Object JavaDoc value)
137             throws IllegalArgumentException JavaDoc;
138
139     /**
140      * Gets a feature/property on the underlying implementation.
141      *
142      * @param name the name of the property
143      * @return the value of the property
144      * @throws IllegalArgumentException if the property is not supported.
145      */
146     public abstract Object JavaDoc getProperty(String JavaDoc name)
147             throws IllegalArgumentException JavaDoc;
148
149     /**
150      * Queries the set of properties that this factory supports.
151      *
152      * @param name the name of the property (may not be null).
153      * @return <code>true</code> if the property is supported;
154      * <code>false</code> otherwise.
155      */
156     public abstract boolean isPropertySupported(String JavaDoc name);
157
158     /**
159      * This class represents the default implementation.
160      */
161     private static final class Default extends XMLOutputFactory {
162
163         // Property setting.
164 private Boolean JavaDoc _isRepairingNamespaces = new Boolean JavaDoc(false);
165
166         // Property setting.
167 private String JavaDoc _repairingPrefix = "ns";
168
169         // Property setting.
170 private Boolean JavaDoc _automaticEmptyElements = new Boolean JavaDoc(false);
171
172         // Property setting.
173 private String JavaDoc _indentation;
174
175         // Implements XMLOutputFactory abstract method.
176 public XMLStreamWriter createXMLStreamWriter(Writer JavaDoc writer)
177                 throws XMLStreamException {
178             XMLStreamWriterImpl xmlWriter = newWriter();
179             xmlWriter.setOutput(writer);
180             return xmlWriter;
181         }
182
183         // Implements XMLOutputFactory abstract method.
184 public XMLStreamWriter createXMLStreamWriter(OutputStream JavaDoc stream)
185                 throws XMLStreamException {
186             XMLStreamWriterImpl xmlWriter = newWriter();
187             xmlWriter.setOutput(stream);
188             return xmlWriter;
189         }
190
191         // Implements XMLOutputFactory abstract method.
192 public XMLStreamWriter createXMLStreamWriter(OutputStream JavaDoc stream,
193                 String JavaDoc encoding) throws XMLStreamException {
194             if ((encoding == null) || encoding.equals("UTF-8")
195                     || encoding.equals("utf-8"))
196                 return createXMLStreamWriter(stream);
197             XMLStreamWriterImpl xmlWriter = newWriter();
198             xmlWriter.setOutput(stream, encoding);
199             return xmlWriter;
200         }
201         
202         private XMLStreamWriterImpl newWriter() {
203             XMLStreamWriterImpl xmlWriter = (XMLStreamWriterImpl) XML_WRITER_FACTORY
204             .object();
205             xmlWriter._objectFactory = XML_WRITER_FACTORY;
206             xmlWriter.setRepairingNamespaces(_isRepairingNamespaces.booleanValue());
207             xmlWriter.setRepairingPrefix(_repairingPrefix);
208             xmlWriter.setIndentation(_indentation);
209             xmlWriter.setAutomaticEmptyElements(_automaticEmptyElements.booleanValue());
210             return xmlWriter;
211         }
212
213         // Implements XMLOutputFactory abstract method.
214 public void setProperty(String JavaDoc name, Object JavaDoc value)
215                 throws IllegalArgumentException JavaDoc {
216             if (name.equals(IS_REPAIRING_NAMESPACES)) {
217                 _isRepairingNamespaces = (Boolean JavaDoc) value;
218             } else if (name.equals(REPAIRING_PREFIX)) {
219                 _repairingPrefix = (String JavaDoc) value;
220             } else if (name.equals(AUTOMATIC_EMPTY_ELEMENTS)) {
221                 _automaticEmptyElements = (Boolean JavaDoc) value;
222             } else if (name.equals(INDENTATION)) {
223                 _indentation = (String JavaDoc) value;
224             } else {
225                 throw new IllegalArgumentException JavaDoc("Property: " + name
226                         + " not supported");
227             }
228         }
229
230         // Implements XMLOutputFactory abstract method.
231 public Object JavaDoc getProperty(String JavaDoc name) throws IllegalArgumentException JavaDoc {
232             if (name.equals(IS_REPAIRING_NAMESPACES)) {
233                 return _isRepairingNamespaces;
234             } else if (name.equals(REPAIRING_PREFIX)) {
235                 return _repairingPrefix;
236             } else if (name.equals(AUTOMATIC_EMPTY_ELEMENTS)) {
237                 return _automaticEmptyElements;
238             } else if (name.equals(INDENTATION)) {
239                 return _indentation;
240             } else {
241                 throw new IllegalArgumentException JavaDoc("Property: " + name
242                         + " not supported");
243             }
244         }
245
246         // Implements XMLOutputFactory abstract method.
247 public boolean isPropertySupported(String JavaDoc name) {
248             return name.equals(IS_REPAIRING_NAMESPACES)
249                     || name.equals(REPAIRING_PREFIX)
250                     || name.equals(AUTOMATIC_EMPTY_ELEMENTS)
251                     || name.equals(INDENTATION);
252         }
253
254     }
255
256     /**
257      * Holds a factory producing reusable writer instances.
258      */
259     private static final ObjectFactory XML_WRITER_FACTORY = new ObjectFactory() {
260
261         protected Object JavaDoc create() {
262             return new XMLStreamWriterImpl();
263         }
264
265         protected void cleanup(Object JavaDoc obj) {
266             ((XMLStreamWriterImpl) obj).reset();
267         }
268
269     };
270
271 }
Popular Tags