View Javadoc
1   /*
2    * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  //@@3RD PARTY CODE@@
27  
28  // DataWriter.java - XML writer for data-oriented files.
29  
30  package com.sun.xml.internal.bind.marshaller;
31  
32  import java.io.IOException;
33  import java.io.Writer;
34  import java.util.Stack;
35  
36  import org.xml.sax.Attributes;
37  import org.xml.sax.SAXException;
38  
39  
40  /**
41   * Write data- or field-oriented XML.
42   *
43   * <p>This filter pretty-prints field-oriented XML without mixed content.
44   * all added indentation and newlines will be passed on down
45   * the filter chain (if any).</p>
46   *
47   * <p>In general, all whitespace in an XML document is potentially
48   * significant, so a general-purpose XML writing tool like the
49   * {@link XMLWriter} class cannot
50   * add newlines or indentation.</p>
51   *
52   * <p>There is, however, a large class of XML documents where information
53   * is strictly fielded: each element contains either character data
54   * or other elements, but not both.  For this special case, it is possible
55   * for a writing tool to provide automatic indentation and newlines
56   * without requiring extra work from the user.  Note that this class
57   * will likely not yield appropriate results for document-oriented
58   * XML like XHTML pages, which mix character data and elements together.</p>
59   *
60   * <p>This writer will automatically place each start tag on a new line,
61   * optionally indented if an indent step is provided (by default, there
62   * is no indentation).  If an element contains other elements, the end
63   * tag will also appear on a new line with leading indentation.  Consider,
64   * for example, the following code:</p>
65   *
66   * <pre>
67   * DataWriter w = new DataWriter();
68   *
69   * w.setIndentStep(2);
70   * w.startDocument();
71   * w.startElement("Person");
72   * w.dataElement("name", "Jane Smith");
73   * w.dataElement("date-of-birth", "1965-05-23");
74   * w.dataElement("citizenship", "US");
75   * w.endElement("Person");
76   * w.endDocument();
77   * </pre>
78   *
79   * <p>This code will produce the following document:</p>
80   *
81   * <pre>
82   * &lt;?xml version="1.0" standalone="yes"?>
83   *
84   * &lt;Person>
85   *   &lt;name>Jane Smith&lt;/name>
86   *   &lt;date-of-birth>1965-05-23&lt;/date-of-birth>
87   *   &lt;citizenship>US&lt;/citizenship>
88   * &lt;/Person>
89   * </pre>
90   *
91   * <p>This class inherits from {@link XMLWriter},
92   * and provides all of the same support for Namespaces.</p>
93   *
94   * @since 1.0
95   * @author David Megginson, david@megginson.com
96   * @version 0.2
97   * @see XMLWriter
98   */
99  public class DataWriter extends XMLWriter
100 {
101 
102 
103 
104     ////////////////////////////////////////////////////////////////////
105     // Constructors.
106     ////////////////////////////////////////////////////////////////////
107 
108 
109     /**
110      * Create a new data writer for the specified output.
111      *
112      * @param writer The character stream where the XML document
113      *        will be written.
114      * @param encoding
115      *      If non-null string is specified, it is written as a part
116      *      of the XML declaration.
117      */
118     public DataWriter ( Writer writer, String encoding, CharacterEscapeHandler _escapeHandler )
119     {
120         super(writer,encoding,_escapeHandler);
121     }
122 
123 
124     public DataWriter (Writer writer, String encoding ) {
125         this( writer, encoding, DumbEscapeHandler.theInstance );
126     }
127 
128 
129 
130     ////////////////////////////////////////////////////////////////////
131     // Accessors and setters.
132     ////////////////////////////////////////////////////////////////////
133 
134 
135     /**
136      * Return the current indent step.
137      *
138      * <p>Return the current indent step: each start tag will be
139      * indented by this number of spaces times the number of
140      * ancestors that the element has.</p>
141      *
142      * @return The number of spaces in each indentation step,
143      *         or 0 or less for no indentation.
144      * @see #setIndentStep(int)
145      *
146      * @deprecated
147      *      Only return the length of the indent string.
148      */
149     public int getIndentStep ()
150     {
151         return indentStep.length();
152     }
153 
154 
155     /**
156      * Set the current indent step.
157      *
158      * @param indentStep The new indent step (0 or less for no
159      *        indentation).
160      * @see #getIndentStep()
161      *
162      * @deprecated
163      *      Should use the version that takes string.
164      */
165     public void setIndentStep (int indentStep)
166     {
167         StringBuilder buf = new StringBuilder();
168         for( ; indentStep>0; indentStep-- )
169             buf.append(' ');
170         setIndentStep(buf.toString());
171     }
172 
173     public void setIndentStep(String s) {
174         this.indentStep = s;
175     }
176 
177 
178 
179     ////////////////////////////////////////////////////////////////////
180     // Override methods from XMLWriter.
181     ////////////////////////////////////////////////////////////////////
182 
183 
184     /**
185      * Reset the writer so that it can be reused.
186      *
187      * <p>This method is especially useful if the writer failed
188      * with an exception the last time through.</p>
189      *
190      * @see XMLWriter#reset()
191      */
192     public void reset ()
193     {
194         depth = 0;
195         state = SEEN_NOTHING;
196         stateStack = new Stack<Object>();
197         super.reset();
198     }
199 
200     protected void writeXmlDecl(String decl) throws IOException {
201         super.writeXmlDecl(decl);
202         write('\n');
203     }
204 
205 
206     /**
207      * Write a start tag.
208      *
209      * <p>Each tag will begin on a new line, and will be
210      * indented by the current indent step times the number
211      * of ancestors that the element has.</p>
212      *
213      * <p>The newline and indentation will be passed on down
214      * the filter chain through regular characters events.</p>
215      *
216      * @param uri The element's Namespace URI.
217      * @param localName The element's local name.
218      * @param qName The element's qualified (prefixed) name.
219      * @param atts The element's attribute list.
220      * @exception org.xml.sax.SAXException If there is an error
221      *            writing the start tag, or if a filter further
222      *            down the chain raises an exception.
223      * @see XMLWriter#startElement(String, String, String, Attributes)
224      */
225     public void startElement (String uri, String localName,
226                               String qName, Attributes atts)
227         throws SAXException
228     {
229         stateStack.push(SEEN_ELEMENT);
230         state = SEEN_NOTHING;
231         if (depth > 0) {
232             super.characters("\n");
233         }
234         doIndent();
235         super.startElement(uri, localName, qName, atts);
236         depth++;
237     }
238 
239 
240     /**
241      * Write an end tag.
242      *
243      * <p>If the element has contained other elements, the tag
244      * will appear indented on a new line; otherwise, it will
245      * appear immediately following whatever came before.</p>
246      *
247      * <p>The newline and indentation will be passed on down
248      * the filter chain through regular characters events.</p>
249      *
250      * @param uri The element's Namespace URI.
251      * @param localName The element's local name.
252      * @param qName The element's qualified (prefixed) name.
253      * @exception org.xml.sax.SAXException If there is an error
254      *            writing the end tag, or if a filter further
255      *            down the chain raises an exception.
256      * @see XMLWriter#endElement(String, String, String)
257      */
258     public void endElement (String uri, String localName, String qName)
259         throws SAXException
260     {
261         depth--;
262         if (state == SEEN_ELEMENT) {
263             super.characters("\n");
264             doIndent();
265         }
266         super.endElement(uri, localName, qName);
267         state = stateStack.pop();
268     }
269 
270     public void endDocument() throws SAXException {
271         try {
272             write('\n');
273         } catch( IOException e ) {
274             throw new SAXException(e);
275         }
276         super.endDocument();
277     }
278 
279 //    /**
280 //     * Write a empty element tag.
281 //     *
282 //     * <p>Each tag will appear on a new line, and will be
283 //     * indented by the current indent step times the number
284 //     * of ancestors that the element has.</p>
285 //     *
286 //     * <p>The newline and indentation will be passed on down
287 //     * the filter chain through regular characters events.</p>
288 //     *
289 //     * @param uri The element's Namespace URI.
290 //     * @param localName The element's local name.
291 //     * @param qName The element's qualified (prefixed) name.
292 //     * @param atts The element's attribute list.
293 //     * @exception org.xml.sax.SAXException If there is an error
294 //     *            writing the empty tag, or if a filter further
295 //     *            down the chain raises an exception.
296 //     * @see XMLWriter#emptyElement(String, String, String, Attributes)
297 //     */
298 //    public void emptyElement (String uri, String localName,
299 //                              String qName, Attributes atts)
300 //        throws SAXException
301 //    {
302 //        state = SEEN_ELEMENT;
303 //        if (depth > 0) {
304 //            super.characters("\n");
305 //        }
306 //        doIndent();
307 //        super.emptyElement(uri, localName, qName, atts);
308 //    }
309 
310 
311     /**
312      * Write a sequence of characters.
313      *
314      * @param ch The characters to write.
315      * @param start The starting position in the array.
316      * @param length The number of characters to use.
317      * @exception org.xml.sax.SAXException If there is an error
318      *            writing the characters, or if a filter further
319      *            down the chain raises an exception.
320      * @see XMLWriter#characters(char[], int, int)
321      */
322     public void characters (char ch[], int start, int length)
323         throws SAXException
324     {
325         state = SEEN_DATA;
326         super.characters(ch, start, length);
327     }
328 
329 
330 
331     ////////////////////////////////////////////////////////////////////
332     // Internal methods.
333     ////////////////////////////////////////////////////////////////////
334 
335 
336     /**
337      * Print indentation for the current level.
338      *
339      * @exception org.xml.sax.SAXException If there is an error
340      *            writing the indentation characters, or if a filter
341      *            further down the chain raises an exception.
342      */
343     private void doIndent ()
344         throws SAXException
345     {
346         if (depth > 0) {
347             char[] ch = indentStep.toCharArray();
348             for( int i=0; i<depth; i++ )
349                 characters(ch, 0, ch.length);
350         }
351     }
352 
353 
354 
355     ////////////////////////////////////////////////////////////////////
356     // Constants.
357     ////////////////////////////////////////////////////////////////////
358 
359     private final static Object SEEN_NOTHING = new Object();
360     private final static Object SEEN_ELEMENT = new Object();
361     private final static Object SEEN_DATA = new Object();
362 
363 
364 
365     ////////////////////////////////////////////////////////////////////
366     // Internal state.
367     ////////////////////////////////////////////////////////////////////
368 
369     private Object state = SEEN_NOTHING;
370     private Stack<Object> stateStack = new Stack<Object>();
371 
372     private String indentStep = "";
373     private int depth = 0;
374 
375 }
376 
377 // end of DataWriter.java