View Javadoc
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.maven.shared.utils.xml;
20  
21  import java.io.IOException;
22  
23  /**
24   * Interface for tools writing XML files.
25   * XMLWriters are not thread safe and must not be accessed concurrently.
26   */
27  public interface XMLWriter {
28  
29      /**
30       * Sets the encoding of the document.
31       * If not set, UTF-8 is used.
32       *
33       * @param encoding the encoding
34       * @throws IllegalStateException if the generation of the document has already started
35       */
36      void setEncoding(String encoding);
37  
38      /**
39       * Sets the DOCTYPE of the document.
40       *
41       * @param docType the docType
42       * @throws IllegalStateException if the generation of the document has already started
43       */
44      void setDocType(String docType);
45  
46      /**
47       * Start an XML Element tag.
48       *
49       * @param name the name of the tag
50       * @throws IOException if starting the element fails
51       */
52      void startElement(String name) throws IOException;
53  
54      /**
55       * Add a XML attribute to the current XML Element.
56       * This method must get called immediately after {@link #startElement(String)}.
57       *
58       * @param key The key of the attribute.
59       * @param value The value of the attribute.
60       * @throws IllegalStateException if no element tag is currently in process
61       * @throws IOException if adding the attribute fails.
62       */
63      void addAttribute(String key, String value) throws IOException;
64  
65      /**
66       * Add text to the current element tag.
67       * This performs XML escaping to guarantee well-formed content.
68       *
69       * @param text The text which should be written.
70       * @throws IllegalStateException if no element tag got started yet
71       * @throws IOException if writing the text fails.
72       */
73      void writeText(String text) throws IOException;
74  
75      /**
76       * Add preformatted markup to the current element tag.
77       *
78       * @param text the text which should be written
79       * @throws IllegalStateException if no element tag is started yet
80       * @throws IOException if writing the markup fails
81       */
82      void writeMarkup(String text) throws IOException;
83  
84      /**
85       * End the previously opened element.
86       * @see #startElement(String)
87       * @throws IOException if ending the element fails.
88       */
89      void endElement() throws IOException;
90  }