001: package javax.xml.stream;
002:
003: import javax.xml.transform.Result;
004:
005: /**
006: * Defines an abstract implementation of a factory for
007: * getting XMLEventWriters and XMLStreamWriters.
008: *
009: * The following table defines the standard properties of this specification.
010: * Each property varies in the level of support required by each implementation.
011: * The level of support required is described in the 'Required' column.
012: *
013: * <table border="2" rules="all" cellpadding="4">
014: * <thead>
015: * <tr>
016: * <th align="center" colspan="2">
017: * Configuration parameters
018: * </th>
019: * </tr>
020: * </thead>
021: * <tbody>
022: * <tr>
023: * <th>Property Name</th>
024: * <th>Behavior</th>
025: * <th>Return type</th>
026: * <th>Default Value</th>
027: * <th>Required</th>
028: * </tr>
029: * <tr><td>javax.xml.stream.isRepairingNamespaces</td><td>defaults prefixes on the output side</td><td>Boolean</td><td>False</td><td>Yes</td></tr>
030: * </tbody>
031: * </table>
032: *
033: * <p>The following paragraphs describe the namespace and prefix repair algorithm:</p>
034: *
035: * <p>The property can be set with the following code line:
036: * <code>setProperty("javax.xml.stream.isRepairingNamespaces",new Boolean(true|false));</code></p>
037: *
038: * <p>This property specifies that the writer default namespace prefix declarations.
039: * The default value is false. </p>
040: *
041: * <p>If a writer isRepairingNamespaces it will create a namespace declaration
042: * on the current StartElement for
043: * any attribute that does not
044: * currently have a namespace declaration in scope. If the StartElement
045: * has a uri but no prefix specified a prefix will be assigned, if the prefix
046: * has not been declared in a parent of the current StartElement it will be declared
047: * on the current StartElement. If the defaultNamespace is bound and in scope
048: * and the default namespace matches the URI of the attribute or StartElement
049: * QName no prefix will be assigned.</p>
050: *
051: * <p>If an element or attribute name has a prefix, but is not
052: * bound to any namespace URI, then the prefix will be removed
053: * during serialization.</p>
054: *
055: * <p>If element and/or attribute names in the same start or
056: * empty-element tag are bound to different namespace URIs and
057: * are using the same prefix then the element or the first
058: * occurring attribute retains the original prefix and the
059: * following attributes have their prefixes replaced with a
060: * new prefix that is bound to the namespace URIs of those
061: * attributes. </p>
062: *
063: * <p>If an element or attribute name uses a prefix that is
064: * bound to a different URI than that inherited from the
065: * namespace context of the parent of that element and there
066: * is no namespace declaration in the context of the current
067: * element then such a namespace declaration is added. </p>
068: *
069: * <p>If an element or attribute name is bound to a prefix and
070: * there is a namespace declaration that binds that prefix
071: * to a different URI then that namespace declaration is
072: * either removed if the correct mapping is inherited from
073: * the parent context of that element, or changed to the
074: * namespace URI of the element or attribute using that prefix.</p>
075: *
076: * @version 1.0
077: * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
078: * @see XMLInputFactory
079: * @see XMLEventWriter
080: * @see XMLStreamWriter
081: */
082: public abstract class XMLOutputFactory {
083: /**
084: * Property used to set prefix defaulting on the output side
085: */
086: public static final String IS_REPAIRING_NAMESPACES = "javax.xml.stream.isRepairingNamespaces";
087:
088: protected XMLOutputFactory() {
089: }
090:
091: /**
092: * Create a new instance of the factory.
093: * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
094: */
095: public static XMLOutputFactory newInstance()
096: throws FactoryConfigurationError {
097: return (XMLOutputFactory) FactoryFinder.find(
098: "javax.xml.stream.XMLOutputFactory",
099: "com.bea.xml.stream.XMLOutputFactoryBase");
100: }
101:
102: /**
103: * Create a new instance of the factory
104: *
105: * @param factoryId Name of the factory to find, same as
106: * a property name
107: * @param classLoader classLoader to use
108: * @return the factory implementation
109: * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
110: */
111: public static XMLInputFactory newInstance(String factoryId,
112: ClassLoader classLoader) throws FactoryConfigurationError {
113: return (XMLInputFactory) FactoryFinder.find(factoryId,
114: "com.bea.xml.stream.XMLOutputFactoryBase", classLoader);
115: }
116:
117: /**
118: * Create a new XMLStreamWriter that writes to a writer
119: * @param stream the writer to write to
120: * @throws XMLStreamException
121: */
122: public abstract XMLStreamWriter createXMLStreamWriter(
123: java.io.Writer stream) throws XMLStreamException;
124:
125: /**
126: * Create a new XMLStreamWriter that writes to a stream
127: * @param stream the stream to write to
128: * @throws XMLStreamException
129: */
130: public abstract XMLStreamWriter createXMLStreamWriter(
131: java.io.OutputStream stream) throws XMLStreamException;
132:
133: /**
134: * Create a new XMLStreamWriter that writes to a stream
135: * @param stream the stream to write to
136: * @param encoding the encoding to use
137: * @throws XMLStreamException
138: */
139: public abstract XMLStreamWriter createXMLStreamWriter(
140: java.io.OutputStream stream, String encoding)
141: throws XMLStreamException;
142:
143: /**
144: * Create a new XMLStreamWriter that writes to a JAXP result. This method is optional.
145: * @param result the result to write to
146: * @throws UnsupportedOperationException if this method is not
147: * supported by this XMLOutputFactory
148: * @throws XMLStreamException
149: */
150: public abstract XMLStreamWriter createXMLStreamWriter(Result result)
151: throws XMLStreamException;
152:
153: /**
154: * Create a new XMLEventWriter that writes to a JAXP result. This method is optional.
155: * @param result the result to write to
156: * @throws UnsupportedOperationException if this method is not
157: * supported by this XMLOutputFactory
158: * @throws XMLStreamException
159: */
160: public abstract XMLEventWriter createXMLEventWriter(Result result)
161: throws XMLStreamException;
162:
163: /**
164: * Create a new XMLEventWriter that writes to a stream
165: * @param stream the stream to write to
166: * @throws XMLStreamException
167: */
168: public abstract XMLEventWriter createXMLEventWriter(
169: java.io.OutputStream stream) throws XMLStreamException;
170:
171: /**
172: * Create a new XMLEventWriter that writes to a stream
173: * @param stream the stream to write to
174: * @param encoding the encoding to use
175: * @throws XMLStreamException
176: */
177: public abstract XMLEventWriter createXMLEventWriter(
178: java.io.OutputStream stream, String encoding)
179: throws XMLStreamException;
180:
181: /**
182: * Create a new XMLEventWriter that writes to a writer
183: * @param stream the stream to write to
184: * @throws XMLStreamException
185: */
186: public abstract XMLEventWriter createXMLEventWriter(
187: java.io.Writer stream) throws XMLStreamException;
188:
189: /**
190: * Allows the user to set specific features/properties on the underlying implementation.
191: * @param name The name of the property
192: * @param value The value of the property
193: * @throws java.lang.IllegalArgumentException if the property is not supported
194: */
195: public abstract void setProperty(java.lang.String name, Object value)
196: throws IllegalArgumentException;
197:
198: /**
199: * Get a feature/property on the underlying implementation
200: * @param name The name of the property
201: * @return The value of the property
202: * @throws java.lang.IllegalArgumentException if the property is not supported
203: */
204: public abstract Object getProperty(java.lang.String name)
205: throws IllegalArgumentException;
206:
207: /**
208: * Query the set of properties that this factory supports.
209: *
210: * @param name The name of the property (may not be null)
211: * @return true if the property is supported and false otherwise
212: */
213: public abstract boolean isPropertySupported(String name);
214: }
|