View Javadoc

1   /*
2    * Copyright (c) 2003, Henri Yandell
3    * All rights reserved.
4    * 
5    * Redistribution and use in source and binary forms, with or 
6    * without modification, are permitted provided that the 
7    * following conditions are met:
8    * 
9    * + Redistributions of source code must retain the above copyright notice, 
10   *   this list of conditions and the following disclaimer.
11   * 
12   * + Redistributions in binary form must reproduce the above copyright notice, 
13   *   this list of conditions and the following disclaimer in the documentation 
14   *   and/or other materials provided with the distribution.
15   * 
16   * + Neither the name of XmlWriter nor the names of its contributors 
17   *   may be used to endorse or promote products derived from this software 
18   *   without specific prior written permission.
19   * 
20   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
21   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
22   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
23   * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
24   * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
25   * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
26   * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
27   * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
28   * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
29   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
30   * POSSIBILITY OF SUCH DAMAGE.
31   */
32  package com.generationjava.io.xml;
33  
34  import java.io.IOException;
35  import java.io.Writer;
36  
37  /***
38   * Interface for anything which is able to output Xml. 
39   * Implementations of this interface are expected to either be 
40   * filters on other XmlWriters, ie) subclasses of DelegatingXmlWriter, 
41   * or actual outputters themselves, ie) subclasses of AbstractXmlWriter. 
42   */
43  public interface XmlWriter {
44  
45      /***
46       * Makes it easy to output the xml version if such a thing is desired.
47       * While it usually is desired, it is less surprising not to handle it.
48       */
49      public XmlWriter writeXmlVersion() throws IOException;
50  
51      /*** @see XmlWriter.writeXmlVersion(String, String, String) */
52      public XmlWriter writeXmlVersion(String version, String encoding) throws IOException;
53  
54      /***
55       * Output the version, encoding and standalone nature of an xml file.
56       */
57      public XmlWriter writeXmlVersion(String version, String encoding, String standalone) throws IOException;
58  
59      /***
60       * A helper method. It writes out an entity which contains only text.
61       *
62       * @param name String name of tag
63       * @param text String of text to go inside the tag
64       */
65      public XmlWriter writeEntityWithText(String name, Object text) throws IOException;
66  
67      /***
68       * A helper method. It writes out empty entities.
69       *
70       * @param name String name of tag
71       */
72      public XmlWriter writeEmptyEntity(String name) throws IOException;
73  
74      /***
75       * Begin to write out an entity. Unlike the helper tags, this tag 
76       * will need to be ended with the endEntity method.
77       *
78       * @param name String name of tag
79       */
80      public XmlWriter writeEntity(String name) throws IOException;
81  
82      /***
83       * Write an attribute out for the current entity. 
84       * Any xml characters in the value are escaped.
85       * Currently it does not actually throw the exception, but 
86       * the api is set that way for future changes.
87       *
88       * @param String name of attribute.
89       * @param Object value of attribute.
90       */
91      public XmlWriter writeAttribute(String attr, Object value) throws IOException;
92  
93      /***
94       * End the current entity. This will throw an exception 
95       * if it is called when there is not a currently open 
96       * entity.
97       */
98      public XmlWriter endEntity() throws IOException;
99  
100     /***
101      * Close this writer. It does not close the underlying 
102      * writer, but does throw an exception if there are 
103      * as yet unclosed tags.
104      */
105     public void close() throws IOException;
106 
107     /***
108      * Output body text. Any xml characters are escaped. 
109      */
110     public XmlWriter writeText(Object text) throws IOException;
111 
112     /***
113      * Write out a chunk of CDATA. This helper method surrounds the 
114      * passed in data with the CDATA tag.
115      *
116      * @param String of CDATA text.
117      */
118     public XmlWriter writeCData(String cdata) throws IOException;
119 
120     /***
121      * Write out a chunk of comment. This helper method surrounds the 
122      * passed in data with the xml comment tag.
123      *
124      * @param String of text to comment.
125      */
126     public XmlWriter writeComment(String comment) throws IOException;
127 
128     /***
129      * Obtain the Writer that is at the lowest level of this XmlWriter chain
130      */
131     public Writer getWriter();
132 
133 }