View Javadoc

1   package org.apache.maven.shared.utils.xml;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *  http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
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      /**
31       * Sets the encoding of the document.
32       * If not set, UTF-8 is being used
33       *
34       * @param encoding the encoding
35       * @throws IllegalStateException if the generation of the document has already started
36       */
37      void setEncoding( String encoding );
38  
39      /**
40       * Sets the docType of the document.
41       *
42       * @param docType the docType
43       * @throws IllegalStateException if the generation of the document has already started
44       */
45      void setDocType( String docType );
46  
47  
48      /**
49       * Start an XML Element tag.
50       * @param name
51       */
52      void startElement( String name );
53  
54  
55      /**
56       * Add a XML attribute to the current XML Element.
57       * This method must get called immediately after {@link #startElement(String)}
58       * @param key
59       * @param value
60       * @throws IllegalStateException if no element tag is currently in process
61       */
62      void addAttribute( String key, String value );
63  
64      /**
65       * Add a value text to the current element tag
66       * This will perform XML escaping to guarantee valid content
67       * @param text
68       * @throws IllegalStateException if no element tag got started yet
69       */
70      void writeText( String text );
71  
72      /**
73       * Add a preformatted markup to the current element tag
74       * @param text
75       * @throws IllegalStateException if no element tag got started yet
76       */
77      void writeMarkup( String text );
78  
79      /**
80       * End the previously opened element.
81       * @see #startElement(String)
82       */
83      void endElement();
84  }