1 /*
   2  * Copyright (c) 1997, 2015, 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>{@code
  82  * <?xml version="1.0" standalone="yes"?>
  83  *
  84  * <Person>
  85  *   <name>Jane Smith</name>
  86  *   <date-of-birth>1965-05-23</date-of-birth>
  87  *   <citizenship>US</citizenship>
  88  * </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
--- EOF ---