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