OutputFormat


1   /*
2    * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
3    *
4    * This software is open source.
5    * See the bottom of this file for the licence.
6    */
7   
8   package org.dom4j.io;
9   
10  /**
11   * <p>
12   * <code>OutputFormat</code> represents the format configuration used by
13   * {@linkXMLWriter}and its base classes to format the XML output
14   * </p>
15   * 
16   * @author <a HREF="mailto:james.strachan@metastuff.com">James Strachan </a>
17   * @version $Revision: 1.17 $
18   */
19  public class OutputFormat implements Cloneable   {
20      /** standard value to indent by, if we are indenting */
21      protected static final String   STANDARD_INDENT = "  ";
22  
23      /**
24       * Whether or not to suppress the XML declaration - default is
25       * <code>false</code>
26       */
27      private boolean suppressDeclaration = false;
28  
29      /**
30       * Whether or not to print new line after the XML declaration - default is
31       * <code>true</code>
32       */
33      private boolean newLineAfterDeclaration = true;
34  
35      /** The encoding format */
36      private String   encoding = "UTF-8";
37  
38      /**
39       * Whether or not to output the encoding in the XML declaration - default is
40       * <code>false</code>
41       */
42      private boolean omitEncoding = false;
43  
44      /** The default indent is no spaces (as original document) */
45      private String   indent = null;
46  
47      /**
48       * Whether or not to expand empty elements to
49       * &lt;tagName&gt;&lt;/tagName&gt; - default is <code>false</code>
50       */
51      private boolean expandEmptyElements = false;
52  
53      /**
54       * The default new line flag, set to do new lines only as in original
55       * document
56       */
57      private boolean newlines = false;
58  
59      /** New line separator */
60      private String   lineSeparator = "\n";
61  
62      /** should we preserve whitespace or not in text nodes? */
63      private boolean trimText = false;
64  
65      /** pad string-element boundaries with whitespace */
66      private boolean padText = false;
67  
68      /** Whether or not to use XHTML standard. */
69      private boolean doXHTML = false;
70  
71      /**
72       * Controls when to output a line.separtor every so many tags in case of no
73       * lines and total text trimming.
74       */
75      private int newLineAfterNTags = 0; // zero means don't bother.
76  
77      /** Quote character to use when writing attributes. */
78      private char attributeQuoteChar = '\"';
79  
80      /**
81       * Creates an <code>OutputFormat</code> with no additional whitespace
82       * (indent or new lines) added. The whitespace from the element text content
83       * is fully preserved.
84       */
85      public OutputFormat() {
86      }
87  
88      /**
89       * Creates an <code>OutputFormat</code> with the given indent added but no
90       * new lines added. All whitespace from element text will be included.
91       * 
92       * @param indent
93       *            is the indent string to be used for indentation (usually a
94       *            number of spaces).
95       */
96      public OutputFormat(String   indent) {
97          this.indent = indent;
98      }
99  
100     /**
101      * Creates an <code>OutputFormat</code> with the given indent added with
102      * optional newlines between the Elements. All whitespace from element text
103      * will be included.
104      * 
105      * @param indent
106      *            is the indent string to be used for indentation (usually a
107      *            number of spaces).
108      * @param newlines
109      *            whether new lines are added to layout the
110      */
111     public OutputFormat(String   indent, boolean newlines) {
112         this.indent = indent;
113         this.newlines = newlines;
114     }
115 
116     /**
117      * Creates an <code>OutputFormat</code> with the given indent added with
118      * optional newlines between the Elements and the given encoding format.
119      * 
120      * @param indent
121      *            is the indent string to be used for indentation (usually a
122      *            number of spaces).
123      * @param newlines
124      *            whether new lines are added to layout the
125      * @param encoding
126      *            is the text encoding to use for writing the XML
127      */
128     public OutputFormat(String   indent, boolean newlines, String   encoding) {
129         this.indent = indent;
130         this.newlines = newlines;
131         this.encoding = encoding;
132     }
133 
134     public String   getLineSeparator() {
135         return lineSeparator;
136     }
137 
138     /**
139      * <p>
140      * This will set the new-line separator. The default is <code>\n</code>.
141      * Note that if the "newlines" property is false, this value is irrelevant.
142      * To make it output the system default line ending string, call
143      * <code>setLineSeparator(System.getProperty("line.separator"))</code>
144      * </p>
145      * 
146      * @param separator
147      *            <code>String</code> line separator to use.
148      * 
149      * @see #setNewlines(boolean)
150      */
151     public void setLineSeparator(String   separator) {
152         lineSeparator = separator;
153     }
154 
155     public boolean isNewlines() {
156         return newlines;
157     }
158 
159     /**
160      * DOCUMENT ME!
161      * 
162      * @param newlines
163      *            <code>true</code> indicates new lines should be printed,
164      *            else new lines are ignored (compacted).
165      * 
166      * @see #setLineSeparator(String)
167      */
168     public void setNewlines(boolean newlines) {
169         this.newlines = newlines;
170     }
171 
172     public String   getEncoding() {
173         return encoding;
174     }
175 
176     /**
177      * DOCUMENT ME!
178      * 
179      * @param encoding
180      *            encoding format
181      */
182     public void setEncoding(String   encoding) {
183         if (encoding != null) {
184             this.encoding = encoding;
185         }
186     }
187 
188     public boolean isOmitEncoding() {
189         return omitEncoding;
190     }
191 
192     /**
193      * <p>
194      * This will set whether the XML declaration (<code>&lt;?xml version="1.0"
195      * encoding="UTF-8"?&gt;</code>)
196      * includes the encoding of the document. It is common to suppress this in
197      * protocols such as WML and SOAP.
198      * </p>
199      * 
200      * @param omitEncoding
201      *            <code>boolean</code> indicating whether or not the XML
202      *            declaration should indicate the document encoding.
203      */
204     public void setOmitEncoding(boolean omitEncoding) {
205         this.omitEncoding = omitEncoding;
206     }
207 
208     /**
209      * <p>
210      * This will set whether the XML declaration (<code>&lt;?xml version="1.0"
211      * encoding="UTF-8"?&gt;</code>)
212      * is included or not. It is common to suppress this in protocols such as
213      * WML and SOAP.
214      * </p>
215      * 
216      * @param suppressDeclaration
217      *            <code>boolean</code> indicating whether or not the XML
218      *            declaration should be suppressed.
219      */
220     public void setSuppressDeclaration(boolean suppressDeclaration) {
221         this.suppressDeclaration = suppressDeclaration;
222     }
223 
224     /**
225      * DOCUMENT ME!
226      * 
227      * @return true if the output of the XML declaration (<code>&lt;?xml
228      *         version="1.0"?&gt;</code>)
229      *         should be suppressed else false.
230      */
231     public boolean isSuppressDeclaration() {
232         return suppressDeclaration;
233     }
234 
235     /**
236      * <p>
237      * This will set whether a new line is printed after the XML declaration
238      * (assuming it is not supressed.)
239      * </p>
240      * 
241      * @param newLineAfterDeclaration
242      *            <code>boolean</code> indicating whether or not to print new
243      *            line following the XML declaration. The default is true.
244      */
245     public void setNewLineAfterDeclaration(boolean newLineAfterDeclaration) {
246         this.newLineAfterDeclaration = newLineAfterDeclaration;
247     }
248 
249     /**
250      * DOCUMENT ME!
251      * 
252      * @return true if a new line should be printed following XML declaration
253      */
254     public boolean isNewLineAfterDeclaration() {
255         return newLineAfterDeclaration;
256     }
257 
258     public boolean isExpandEmptyElements() {
259         return expandEmptyElements;
260     }
261 
262     /**
263      * <p>
264      * This will set whether empty elements are expanded from
265      * <code>&lt;tagName&gt;</code> to
266      * <code>&lt;tagName&gt;&lt;/tagName&gt;</code>.
267      * </p>
268      * 
269      * @param expandEmptyElements
270      *            <code>boolean</code> indicating whether or not empty
271      *            elements should be expanded.
272      */
273     public void setExpandEmptyElements(boolean expandEmptyElements) {
274         this.expandEmptyElements = expandEmptyElements;
275     }
276 
277     public boolean isTrimText() {
278         return trimText;
279     }
280 
281     /**
282      * <p>
283      * This will set whether the text is output verbatim (false) or with
284      * whitespace stripped as per <code>{@link
285      * org.dom4j.Element#getTextTrim()}</code>.
286      * </p>
287      * 
288      * <p>
289      * </p>
290      * 
291      * <p>
292      * Default: false
293      * </p>
294      * 
295      * @param trimText
296      *            <code>boolean</code> true=>trim the whitespace, false=>use
297      *            text verbatim
298      */
299     public void setTrimText(boolean trimText) {
300         this.trimText = trimText;
301     }
302 
303     public boolean isPadText() {
304         return padText;
305     }
306 
307     /**
308      * <p>
309      * Ensure that text immediately preceded by or followed by an element will
310      * be "padded" with a single space. This is used to allow make
311      * browser-friendly HTML, avoiding trimText's transformation of, e.g.,
312      * <code>The quick &lt;b&gt;brown&lt;/b&gt; fox</code> into <code>The
313      * quick&lt;b&gt;brown&lt;/b&gt;fox</code>
314      * (the latter will run the three separate words together into a single
315      * word). This setting is not too useful if you haven't also called
316      * {@link #setTrimText}.
317      * </p>
318      * 
319      * <p>
320      * The padding string will only be added if the text itself starts or ends
321      * with some whitespace characters.
322      * </p>
323      * 
324      * <p>
325      * Default: false
326      * </p>
327      * 
328      * @param padText
329      *            <code>boolean</code> if true, pad string-element boundaries
330      */
331     public void setPadText(boolean padText) {
332         this.padText = padText;
333     }
334 
335     public String   getIndent() {
336         return indent;
337     }
338 
339     /**
340      * <p>
341      * This will set the indent <code>String</code> to use; this is usually a
342      * <code>String</code> of empty spaces. If you pass null, or the empty
343      * string (""), then no indentation will happen.
344      * </p>
345      * Default: none (null)
346      * 
347      * @param indent
348      *            <code>String</code> to use for indentation.
349      */
350     public void setIndent(String   indent) {
351         // nullify empty string to void unnecessary indentation code
352         if ((indent != null) && (indent.length() <= 0)) {
353             indent = null;
354         }
355 
356         this.indent = indent;
357     }
358 
359     /**
360      * Set the indent on or off. If setting on, will use the value of
361      * STANDARD_INDENT, which is usually two spaces.
362      * 
363      * @param doIndent
364      *            if true, set indenting on; if false, set indenting off
365      */
366     public void setIndent(boolean doIndent) {
367         if (doIndent) {
368             this.indent = STANDARD_INDENT;
369         } else {
370             this.indent = null;
371         }
372     }
373 
374     /**
375      * <p>
376      * This will set the indent <code>String</code>'s size; an indentSize of
377      * 4 would result in the indention being equivalent to the
378      * <code>String</code> "&nbsp;&nbsp;&nbsp;&nbsp;" (four space characters).
379      * </p>
380      * 
381      * @param indentSize
382      *            <code>int</code> number of spaces in indentation.
383      */
384     public void setIndentSize(int indentSize) {
385         StringBuffer   indentBuffer = new StringBuffer  ();
386 
387         for (int i = 0; i < indentSize; i++) {
388             indentBuffer.append(" ");
389         }
390 
391         this.indent = indentBuffer.toString();
392     }
393 
394     /**
395      * <p>
396      * Whether or not to use the XHTML standard: like HTML but passes an XML
397      * parser with real, closed tags. Also, XHTML CDATA sections will be output
398      * with the CDATA delimiters: ( &quot; <b>&lt;![CDATA[ </b>&quot; and &quot;
399      * <b>]]&gt; </b>&quot; ) otherwise, the class HTMLWriter will output the
400      * CDATA text, but not the delimiters.
401      * </p>
402      * 
403      * <p>
404      * Default is <code>false</code>
405      * </p>
406      * 
407      * @return DOCUMENT ME!
408      */
409     public boolean isXHTML() {
410         return doXHTML;
411     }
412 
413     /**
414      * <p>
415      * This will set whether or not to use the XHTML standard: like HTML but
416      * passes an XML parser with real, closed tags. Also, XHTML CDATA sections
417      * will be output with the CDATA delimiters: ( &quot; <b>&lt;[CDATA[
418      * </b>&quot; and &quot; <b>]]&lt; </b>) otherwise, the class HTMLWriter
419      * will output the CDATA text, but not the delimiters.
420      * </p>
421      * 
422      * <p>
423      * Default: false
424      * </p>
425      * 
426      * @param xhtml
427      *            <code>boolean</code> true=>conform to XHTML, false=>conform
428      *            to HTML, can have unclosed tags, etc.
429      */
430     public void setXHTML(boolean xhtml) {
431         doXHTML = xhtml;
432     }
433 
434     public int getNewLineAfterNTags() {
435         return newLineAfterNTags;
436     }
437 
438     /**
439      * Controls output of a line.separator every tagCount tags when isNewlines
440      * is false. If tagCount equals zero, it means don't do anything special. If
441      * greater than zero, then a line.separator will be output after tagCount
442      * tags have been output. Used when you would like to squeeze the html as
443      * much as possible, but some browsers don't like really long lines. A tag
444      * count of 10 would produce a line.separator in the output after 10 close
445      * tags (including single tags).
446      * 
447      * @param tagCount
448      *            DOCUMENT ME!
449      */
450     public void setNewLineAfterNTags(int tagCount) {
451         newLineAfterNTags = tagCount;
452     }
453 
454     public char getAttributeQuoteCharacter() {
455         return attributeQuoteChar;
456     }
457 
458     /**
459      * Sets the character used to quote attribute values. The specified
460      * character must be a valid XML attribute quote character, otherwise an
461      * <code>IllegalArgumentException</code> will be thrown.
462      * 
463      * @param quoteChar
464      *            The character to use when quoting attribute values.
465      * 
466      * @throws IllegalArgumentException
467      *             If the specified character is not a valid XML attribute quote
468      *             character.
469      */
470     public void setAttributeQuoteCharacter(char quoteChar) {
471         if ((quoteChar == '\'') || (quoteChar == '"')) {
472             attributeQuoteChar = quoteChar;
473         } else {
474             throw new IllegalArgumentException  ("Invalid attribute quote "
475                     + "character (" + quoteChar + ")");
476         }
477     }
478 
479     /**
480      * Parses command line arguments of the form <code>-omitEncoding
481      * -indentSize 3 -newlines -trimText</code>
482      * 
483      * @param args
484      *            is the array of command line arguments
485      * @param i
486      *            is the index in args to start parsing options
487      * 
488      * @return the index of first parameter that we didn't understand
489      */
490     public int parseOptions(String  [] args, int i) {
491         for (int size = args.length; i < size; i++) {
492             if (args[i].equals("-suppressDeclaration")) {
493                 setSuppressDeclaration(true);
494             } else if (args[i].equals("-omitEncoding")) {
495                 setOmitEncoding(true);
496             } else if (args[i].equals("-indent")) {
497                 setIndent(args[++i]);
498             } else if (args[i].equals("-indentSize")) {
499                 setIndentSize(Integer.parseInt(args[++i]));
500             } else if (args[i].startsWith("-expandEmpty")) {
501                 setExpandEmptyElements(true);
502             } else if (args[i].equals("-encoding")) {
503                 setEncoding(args[++i]);
504             } else if (args[i].equals("-newlines")) {
505                 setNewlines(true);
506             } else if (args[i].equals("-lineSeparator")) {
507                 setLineSeparator(args[++i]);
508             } else if (args[i].equals("-trimText")) {
509                 setTrimText(true);
510             } else if (args[i].equals("-padText")) {
511                 setPadText(true);
512             } else if (args[i].startsWith("-xhtml")) {
513                 setXHTML(true);
514             } else {
515                 return i;
516             }
517         }
518 
519         return i;
520     }
521 
522     /**
523      * A static helper method to create the default pretty printing format. This
524      * format consists of an indent of 2 spaces, newlines after each element and
525      * all other whitespace trimmed, and XMTML is false.
526      * 
527      * @return DOCUMENT ME!
528      */
529     public static OutputFormat createPrettyPrint() {
530         OutputFormat format = new OutputFormat();
531         format.setIndentSize(2);
532         format.setNewlines(true);
533         format.setTrimText(true);
534         format.setPadText(true);
535 
536         return format;
537     }
538 
539     /**
540      * A static helper method to create the default compact format. This format
541      * does not have any indentation or newlines after an alement and all other
542      * whitespace trimmed
543      * 
544      * @return DOCUMENT ME!
545      */
546     public static OutputFormat createCompactFormat() {
547         OutputFormat format = new OutputFormat();
548         format.setIndent(false);
549         format.setNewlines(false);
550         format.setTrimText(true);
551 
552         return format;
553     }
554 }
555 
556 /*
557  * Redistribution and use of this software and associated documentation
558  * ("Software"), with or without modification, are permitted provided that the
559  * following conditions are met:
560  * 
561  * 1. Redistributions of source code must retain copyright statements and
562  * notices. Redistributions must also contain a copy of this document.
563  * 
564  * 2. Redistributions in binary form must reproduce the above copyright notice,
565  * this list of conditions and the following disclaimer in the documentation
566  * and/or other materials provided with the distribution.
567  * 
568  * 3. The name "DOM4J" must not be used to endorse or promote products derived
569  * from this Software without prior written permission of MetaStuff, Ltd. For
570  * written permission, please contact dom4j-info@metastuff.com.
571  * 
572  * 4. Products derived from this Software may not be called "DOM4J" nor may
573  * "DOM4J" appear in their names without prior written permission of MetaStuff,
574  * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
575  * 
576  * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org
577  * 
578  * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND
579  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
580  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
581  * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE
582  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
583  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
584  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
585  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
586  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
587  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
588  * POSSIBILITY OF SUCH DAMAGE.
589  * 
590  * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
591  */
592
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags