1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one *
3 * or more contributor license agreements. See the NOTICE file *
4 * distributed with this work for additional information *
5 * regarding copyright ownership. The ASF licenses this file *
6 * to you under the Apache License, Version 2.0 (the *
7 * "License"); you may not use this file except in compliance *
8 * with the License. You may obtain a copy of the License at *
9 * *
10 * http://www.apache.org/licenses/LICENSE-2.0 *
11 * *
12 * Unless required by applicable law or agreed to in writing, *
13 * software distributed under the License is distributed on an *
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
15 * KIND, either express or implied. See the License for the *
16 * specific language governing permissions and limitations *
17 * under the License. *
18 */
19 package org.apache.rat.report.xml.writer;
20
21 import java.io.IOException;
22
23 /**
24 * Simple interface for creating basic XML documents.
25 * Performs basic validation and escaping.
26 * Not namespace aware.
27 */
28 public interface IXmlWriter extends AutoCloseable {
29
30 /**
31 * Starts a document by writing a prolog.
32 * Calling this method is optional.
33 * When writing a document fragment, it should <em>not</em> be called.
34 * @return this object
35 * @throws OperationNotAllowedException
36 * if called after the first element has been written
37 * or once a prolog has already been written
38 */
39 IXmlWriter startDocument() throws IOException;
40
41 /**
42 * Writes the start of an element.
43 *
44 * @param elementName the name of the element, not null
45 * @return this object
46 * @throws InvalidXmlException if the name is not valid for an xml element
47 * @throws OperationNotAllowedException
48 * if called after the first element has been closed
49 */
50 IXmlWriter openElement(CharSequence elementName) throws IOException;
51
52 /**
53 * Writes a comment
54 *
55 * @param text the comment text
56 * @return this object
57 * @throws OperationNotAllowedException
58 * if called after the first element has been closed
59 */
60 IXmlWriter comment(CharSequence text) throws IOException;
61
62 /**
63 * Writes an attribute of an element.
64 * Note that this is only allowed directly after {@link #openElement(CharSequence)}
65 * or {@link #attribute}.
66 *
67 * @param name the attribute name, not null
68 * @param value the attribute value, not null
69 * @return this object
70 * @throws InvalidXmlException if the name is not valid for an xml attribute
71 * or if a value for the attribute has already been written
72 * @throws OperationNotAllowedException if called after {@link #content(CharSequence)}
73 * or {@link #closeElement()} or before any call to {@link #openElement(CharSequence)}
74 */
75 IXmlWriter attribute(CharSequence name, CharSequence value) throws IOException;
76
77 /**
78 * Writes content.
79 * Note that this method does not support CDATA.
80 * This method automatically escapes characters.
81 *
82 * @param content the content to write
83 * @return this object
84 * @throws OperationNotAllowedException
85 * if called before any call to {@link #openElement}
86 * or after the first element has been closed
87 */
88 IXmlWriter content(CharSequence content) throws IOException;
89
90 /**
91 * Writes CDATA content.
92 * This method DOES NOT automatically escapes characters.
93 * It will removed enclosed CDATA closing strings (e.g. {@code ]]>}
94 *
95 * @param content the content to write
96 * @return this object
97 * @throws OperationNotAllowedException
98 * if called before any call to {@link #openElement}
99 * or after the first element has been closed
100 */
101 IXmlWriter cdata(CharSequence content) throws IOException;
102
103 /**
104 * Closes the last element written.
105 *
106 * @return this object
107 * @throws OperationNotAllowedException
108 * if called before any call to {@link #openElement}
109 * or after the first element has been closed
110 */
111 IXmlWriter closeElement() throws IOException;
112
113 /**
114 * Closes all pending elements.
115 * When appropriate, resources are also flushed and closed.
116 * No exception is raised when called upon a document whose
117 * root element has already been closed.
118 *
119 * @return this object
120 * @throws OperationNotAllowedException
121 * if called before any call to {@link #openElement}
122 */
123 IXmlWriter closeDocument() throws IOException;
124 }