001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.transform.stax;
027
028 import javax.xml.stream.XMLEventWriter;
029 import javax.xml.stream.XMLStreamWriter;
030 import javax.xml.transform.Result;
031
032 /**
033 * <p>Acts as a holder for an XML {@link Result} in the
034 * form of a StAX writer,i.e.
035 * {@link XMLStreamWriter} or {@link XMLEventWriter}.
036 * <code>StAXResult</code> can be used in all cases that accept
037 * a <code>Result</code>, e.g. {@link javax.xml.transform.Transformer},
038 * {@link javax.xml.validation.Validator} which accept
039 * <code>Result</code> as input.
040 *
041 * @author <a href="mailto:Neeraj.Bajaj@Sun.com">Neeraj Bajaj</a>
042 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
043 * @version $Revision: 1.4 $, $Date: 2006/04/24 13:42:26 $
044 *
045 * @see <a href="http://jcp.org/en/jsr/detail?id=173">
046 * JSR 173: Streaming API for XML</a>
047 * @see XMLStreamWriter
048 * @see XMLEventWriter
049 *
050 * @since 1.6
051 */
052 public class StAXResult implements Result {
053 /** If {@link javax.xml.transform.TransformerFactory#getFeature(String name)}
054 * returns true when passed this value as an argument,
055 * the Transformer supports Result output of this type.
056 */
057 public static final String FEATURE = "http://javax.xml.transform.stax.StAXResult/feature";
058
059 /**
060 * <p><code>XMLEventWriter</code> to be used for
061 * <code>Result</code> output.</p>
062 */
063 private XMLEventWriter xmlEventWriter = null;
064
065 /**
066 * <p><code>XMLStreamWriter</code> to be used for
067 * <code>Result</code> output.</p>
068 */
069 private XMLStreamWriter xmlStreamWriter = null;
070
071 /** <p>System identifier for this <code>StAXResult</code>.<p> */
072 private String systemId = null;
073
074 /**
075 * <p>Creates a new instance of a <code>StAXResult</code>
076 * by supplying an {@link XMLEventWriter}.</p>
077 *
078 * <p><code>XMLEventWriter</code> must be a
079 * non-<code>null</code> reference.</p>
080 *
081 * @param xmlEventWriter <code>XMLEventWriter</code> used to create
082 * this <code>StAXResult</code>.
083 *
084 * @throws IllegalArgumentException If <code>xmlEventWriter</code> ==
085 * <code>null</code>.
086 */
087 public StAXResult(final XMLEventWriter xmlEventWriter) {
088
089 if (xmlEventWriter == null) {
090 throw new IllegalArgumentException(
091 "StAXResult(XMLEventWriter) with XMLEventWriter == null");
092 }
093
094 this .xmlEventWriter = xmlEventWriter;
095 }
096
097 /**
098 * <p>Creates a new instance of a <code>StAXResult</code>
099 * by supplying an {@link XMLStreamWriter}.</p>
100 *
101 * <p><code>XMLStreamWriter</code> must be a
102 * non-<code>null</code> reference.</p>
103 *
104 * @param xmlStreamWriter <code>XMLStreamWriter</code> used to create
105 * this <code>StAXResult</code>.
106 *
107 * @throws IllegalArgumentException If <code>xmlStreamWriter</code> ==
108 * <code>null</code>.
109 */
110 public StAXResult(final XMLStreamWriter xmlStreamWriter) {
111
112 if (xmlStreamWriter == null) {
113 throw new IllegalArgumentException(
114 "StAXResult(XMLStreamWriter) with XMLStreamWriter == null");
115 }
116
117 this .xmlStreamWriter = xmlStreamWriter;
118 }
119
120 /**
121 * <p>Get the <code>XMLEventWriter</code> used by this
122 * <code>StAXResult</code>.</p>
123 *
124 * <p><code>XMLEventWriter</code> will be <code>null</code>
125 * if this <code>StAXResult</code> was created with a
126 * <code>XMLStreamWriter</code>.</p>
127 *
128 * @return <code>XMLEventWriter</code> used by this
129 * <code>StAXResult</code>.
130 */
131 public XMLEventWriter getXMLEventWriter() {
132
133 return xmlEventWriter;
134 }
135
136 /**
137 * <p>Get the <code>XMLStreamWriter</code> used by this
138 * <code>StAXResult</code>.</p>
139 *
140 * <p><code>XMLStreamWriter</code> will be <code>null</code>
141 * if this <code>StAXResult</code> was created with a
142 * <code>XMLEventWriter</code>.</p>
143 *
144 * @return <code>XMLStreamWriter</code> used by this
145 * <code>StAXResult</code>.
146 */
147 public XMLStreamWriter getXMLStreamWriter() {
148
149 return xmlStreamWriter;
150 }
151
152 /**
153 * <p>In the context of a <code>StAXResult</code>, it is not appropriate
154 * to explicitly set the system identifier.
155 * The <code>XMLEventWriter</code> or <code>XMLStreamWriter</code>
156 * used to construct this <code>StAXResult</code> determines the
157 * system identifier of the XML result.</p>
158 *
159 * <p>An {@link UnsupportedOperationException} is <strong>always</strong>
160 * thrown by this method.</p>
161 *
162 * @param systemId Ignored.
163 *
164 * @throws UnsupportedOperationException Is <strong>always</strong>
165 * thrown by this method.
166 */
167 public void setSystemId(final String systemId) {
168
169 throw new UnsupportedOperationException(
170 "StAXResult#setSystemId(systemId) cannot set the "
171 + "system identifier for a StAXResult");
172 }
173
174 /**
175 * <p>The returned system identifier is always <code>null</code>.</p>
176 *
177 * @return The returned system identifier is always <code>null</code>.
178 */
179 public String getSystemId() {
180
181 return null;
182 }
183 }
|