001 package javax.xml.stream;
002
003 import javax.xml.stream.events.*;
004 import javax.xml.stream.util.XMLEventConsumer;
005 import javax.xml.namespace.NamespaceContext;
006
007 /**
008 *
009 * This is the top level interface for writing XML documents.
010 *
011 * Instances of this interface are not required to validate the
012 * form of the XML.
013 *
014 * @version 1.0
015 * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
016 * @see XMLEventReader
017 * @see javax.xml.stream.events.XMLEvent
018 * @see javax.xml.stream.events.Characters
019 * @see javax.xml.stream.events.ProcessingInstruction
020 * @see javax.xml.stream.events.StartElement
021 * @see javax.xml.stream.events.EndElement
022 * @since 1.6
023 */
024 public interface XMLEventWriter extends XMLEventConsumer {
025
026 /**
027 * Writes any cached events to the underlying output mechanism
028 * @throws XMLStreamException
029 */
030 public void flush() throws XMLStreamException;
031
032 /**
033 * Frees any resources associated with this stream
034 * @throws XMLStreamException
035 */
036 public void close() throws XMLStreamException;
037
038 /**
039 * Add an event to the output stream
040 * Adding a START_ELEMENT will open a new namespace scope that
041 * will be closed when the corresponding END_ELEMENT is written.
042 * <table border="2" rules="all" cellpadding="4">
043 * <thead>
044 * <tr>
045 * <th align="center" colspan="2">
046 * Required and optional fields for events added to the writer
047 * </th>
048 * </tr>
049 * </thead>
050 * <tbody>
051 * <tr>
052 * <th>Event Type</th>
053 * <th>Required Fields</th>
054 * <th>Optional Fields</th>
055 * <th>Required Behavior</th>
056 * </tr>
057 * <tr>
058 * <td> START_ELEMENT </td>
059 * <td> QName name </td>
060 * <td> namespaces , attributes </td>
061 * <td> A START_ELEMENT will be written by writing the name,
062 * namespaces, and attributes of the event in XML 1.0 valid
063 * syntax for START_ELEMENTs.
064 * The name is written by looking up the prefix for
065 * the namespace uri. The writer can be configured to
066 * respect prefixes of QNames. If the writer is respecting
067 * prefixes it must use the prefix set on the QName. The
068 * default behavior is to lookup the value for the prefix
069 * on the EventWriter's internal namespace context.
070 * Each attribute (if any)
071 * is written using the behavior specified in the attribute
072 * section of this table. Each namespace (if any) is written
073 * using the behavior specified in the namespace section of this
074 * table.
075 * </td>
076 * </tr>
077 * <tr>
078 * <td> END_ELEMENT </td>
079 * <td> Qname name </td>
080 * <td> None </td>
081 * <td> A well formed END_ELEMENT tag is written.
082 * The name is written by looking up the prefix for
083 * the namespace uri. The writer can be configured to
084 * respect prefixes of QNames. If the writer is respecting
085 * prefixes it must use the prefix set on the QName. The
086 * default behavior is to lookup the value for the prefix
087 * on the EventWriter's internal namespace context.
088 * If the END_ELEMENT name does not match the START_ELEMENT
089 * name an XMLStreamException is thrown.
090 * </td>
091 * </tr>
092 * <tr>
093 * <td> ATTRIBUTE </td>
094 * <td> QName name , String value </td>
095 * <td> QName type </td>
096 * <td> An attribute is written using the same algorithm
097 * to find the lexical form as used in START_ELEMENT.
098 * The default is to use double quotes to wrap attribute
099 * values and to escape any double quotes found in the
100 * value. The type value is ignored.
101 * </td>
102 * </tr>
103 * <tr>
104 * <td> NAMESPACE </td>
105 * <td> String prefix, String namespaceURI,
106 * boolean isDefaultNamespaceDeclaration
107 * </td>
108 * <td> None </td>
109 * <td> A namespace declaration is written. If the
110 * namespace is a default namespace declaration
111 * (isDefault is true) then xmlns="$namespaceURI"
112 * is written and the prefix is optional. If
113 * isDefault is false, the prefix must be declared
114 * and the writer must prepend xmlns to the prefix
115 * and write out a standard prefix declaration.
116 * </td>
117 * </tr>
118 * <tr>
119 * <td> PROCESSING_INSTRUCTION </td>
120 * <td> None</td>
121 * <td> String target, String data</td>
122 * <td> The data does not need to be present and may be
123 * null. Target is required and many not be null.
124 * The writer
125 * will write data section
126 * directly after the target,
127 * enclosed in appropriate XML 1.0 syntax
128 * </td>
129 * </tr>
130 * <tr>
131 * <td> COMMENT </td>
132 * <td> None </td>
133 * <td> String comment </td>
134 * <td> If the comment is present (not null) it is written, otherwise an
135 * an empty comment is written
136 * </td>
137 * </tr>
138 * <tr>
139 * <td> START_DOCUMENT </td>
140 * <td> None </td>
141 * <td> String encoding , boolean standalone, String version </td>
142 * <td> A START_DOCUMENT event is not required to be written to the
143 * stream. If present the attributes are written inside
144 * the appropriate XML declaration syntax
145 * </td>
146 * </tr>
147 * <tr>
148 * <td> END_DOCUMENT </td>
149 * <td> None </td>
150 * <td> None </td>
151 * <td> Nothing is written to the output </td>
152 * </tr>
153 * <tr>
154 * <td> DTD </td>
155 * <td> String DocumentTypeDefinition </td>
156 * <td> None </td>
157 * <td> The DocumentTypeDefinition is written to the output </td>
158 * </tr>
159 * </tbody>
160 * </table>
161 * @param event the event to be added
162 * @throws XMLStreamException
163 */
164 public void add(XMLEvent event) throws XMLStreamException;
165
166 /**
167 * Adds an entire stream to an output stream,
168 * calls next() on the inputStream argument until hasNext() returns false
169 * This should be treated as a convenience method that will
170 * perform the following loop over all the events in an
171 * event reader and call add on each event.
172 *
173 * @param reader the event stream to add to the output
174 * @throws XMLStreamException
175 */
176
177 public void add(XMLEventReader reader) throws XMLStreamException;
178
179 /**
180 * Gets the prefix the uri is bound to
181 * @param uri the uri to look up
182 * @throws XMLStreamException
183 */
184 public String getPrefix(String uri) throws XMLStreamException;
185
186 /**
187 * Sets the prefix the uri is bound to. This prefix is bound
188 * in the scope of the current START_ELEMENT / END_ELEMENT pair.
189 * If this method is called before a START_ELEMENT has been written
190 * the prefix is bound in the root scope.
191 * @param prefix the prefix to bind to the uri
192 * @param uri the uri to bind to the prefix
193 * @throws XMLStreamException
194 */
195 public void setPrefix(String prefix, String uri)
196 throws XMLStreamException;
197
198 /**
199 * Binds a URI to the default namespace
200 * This URI is bound
201 * in the scope of the current START_ELEMENT / END_ELEMENT pair.
202 * If this method is called before a START_ELEMENT has been written
203 * the uri is bound in the root scope.
204 * @param uri the uri to bind to the default namespace
205 * @throws XMLStreamException
206 */
207 public void setDefaultNamespace(String uri)
208 throws XMLStreamException;
209
210 /**
211 * Sets the current namespace context for prefix and uri bindings.
212 * This context becomes the root namespace context for writing and
213 * will replace the current root namespace context. Subsequent calls
214 * to setPrefix and setDefaultNamespace will bind namespaces using
215 * the context passed to the method as the root context for resolving
216 * namespaces.
217 * @param context the namespace context to use for this writer
218 * @throws XMLStreamException
219 */
220 public void setNamespaceContext(NamespaceContext context)
221 throws XMLStreamException;
222
223 /**
224 * Returns the current namespace context.
225 * @return the current namespace context
226 */
227 public NamespaceContext getNamespaceContext();
228
229 }
|