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 an attribute of an element.
54 * Note that this is only allowed directly after {@link #openElement(CharSequence)}
55 * or {@link #attribute}.
56 *
57 * @param name the attribute name, not null
58 * @param value the attribute value, not null
59 * @return this object
60 * @throws InvalidXmlException if the name is not valid for an xml attribute
61 * or if a value for the attribute has already been written
62 * @throws OperationNotAllowedException if called after {@link #content(CharSequence)}
63 * or {@link #closeElement()} or before any call to {@link #openElement(CharSequence)}
64 */
65 IXmlWriter attribute(CharSequence name, CharSequence value) throws IOException;
66
67 /**
68 * Writes content.
69 * Calling this method will automatically
70 * Note that this method does not use CDATA.
71 *
72 * @param content the content to write
73 * @return this object
74 * @throws OperationNotAllowedException
75 * if called before any call to {@link #openElement}
76 * or after the first element has been closed
77 */
78 IXmlWriter content(CharSequence content) throws IOException;
79
80 /**
81 * Closes the last element written.
82 *
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 closeElement() throws IOException;
89
90 /**
91 * Closes all pending elements.
92 * When appropriate, resources are also flushed and closed.
93 * No exception is raised when called upon a document whose
94 * root element has already been closed.
95 *
96 * @return this object
97 * @throws OperationNotAllowedException
98 * if called before any call to {@link #openElement}
99 */
100 IXmlWriter closeDocument() throws IOException;
101 }