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 import org.apache.rat.report.xml.XmlElements;
24
25 /**
26 * Simple interface for creating basic XML documents.
27 * Performs basic validation and escaping.
28 * Not namespace aware.
29 */
30 public interface IXmlWriter extends AutoCloseable {
31
32 /**
33 * Starts a document by writing a prolog.
34 * Calling this method is optional.
35 * When writing a document fragment, it should <em>not</em> be called.
36 * @return this object
37 * @throws OperationNotAllowedException
38 * if called after the first element has been written
39 * or once a prolog has already been written
40 */
41 IXmlWriter startDocument() throws IOException;
42
43 /**
44 * Writes the start of an element.
45 *
46 * @param elementName the name of the element, not null
47 * @return this object
48 * @throws InvalidXmlException if the name is not valid for a xml element
49 * @throws OperationNotAllowedException
50 * if called after the first element has been closed
51 */
52 IXmlWriter openElement(CharSequence elementName) throws IOException;
53
54 /**
55 * Writes the start of an element.
56 *
57 * @param element the element, not null
58 * @return this object
59 * @throws InvalidXmlException if the name is not valid for an xml element
60 * @throws OperationNotAllowedException
61 * if called after the first element has been closed
62 */
63 default IXmlWriter openElement(XmlElements.Elements element) throws IOException {
64 return openElement(element.getElementName());
65 }
66
67 /**
68 * Writes a comment
69 *
70 * @param text the comment text
71 * @return this object
72 * @throws OperationNotAllowedException
73 * if called after the first element has been closed
74 */
75 IXmlWriter comment(CharSequence text) throws IOException;
76
77 /**
78 * Writes an attribute of an element.
79 * Note that this is only allowed directly after {@link #openElement(CharSequence)}
80 * or {@link #attribute}.
81 *
82 * @param name the attribute name, not null
83 * @param value the attribute value, not null
84 * @return this object
85 * @throws InvalidXmlException if the name is not valid for a xml attribute
86 * or if a value for the attribute has already been written
87 * @throws OperationNotAllowedException if called after {@link #content(CharSequence)}
88 * or {@link #closeElement()} or before any call to {@link #openElement(CharSequence)}
89 */
90 IXmlWriter attribute(CharSequence name, CharSequence value) throws IOException;
91
92 /**
93 * Writes content.
94 * Note that this method does not support CDATA.
95 * This method automatically escapes characters.
96 *
97 * @param content the content to write
98 * @return this object
99 * @throws OperationNotAllowedException
100 * if called before any call to {@link #openElement}
101 * or after the first element has been closed
102 */
103 IXmlWriter content(CharSequence content) throws IOException;
104
105 /**
106 * Writes CDATA content.
107 * This method DOES NOT automatically escape characters.
108 * It will remove enclosed CDATA closing strings (e.g. {@code ]]>})
109 *
110 * @param content the content to write
111 * @return this object
112 * @throws OperationNotAllowedException
113 * if called before any call to {@link #openElement}
114 * or after the first element has been closed
115 */
116 IXmlWriter cdata(CharSequence content) throws IOException;
117
118 /**
119 * Closes the last element written.
120 *
121 * @return this object
122 * @throws OperationNotAllowedException
123 * if called before any call to {@link #openElement}
124 * or after the first element has been closed
125 */
126 IXmlWriter closeElement() throws IOException;
127
128 /**
129 * Closes all open elements back to and including the named element.
130 *
131 * @param name the last element to close
132 * @return this object
133 * @throws OperationNotAllowedException
134 * if called before any call to {@link #openElement}
135 * or after the first element has been closed
136 */
137 IXmlWriter closeElement(CharSequence name) throws IOException;
138
139 /**
140 * Closes all pending elements.
141 * When appropriate, resources are also flushed and closed.
142 * No exception is raised when called upon a document whose
143 * root element has already been closed.
144 *
145 * @return this object
146 * @throws OperationNotAllowedException
147 * if called before any call to {@link #openElement}
148 */
149 IXmlWriter closeDocument() throws IOException;
150 }