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.XMLEventReader;
029 import javax.xml.stream.XMLStreamConstants;
030 import javax.xml.stream.XMLStreamException;
031 import javax.xml.stream.XMLStreamReader;
032 import javax.xml.stream.events.XMLEvent;
033 import javax.xml.transform.Source;
034
035 /**
036 * <p>Acts as a holder for an XML {@link Source} in the
037 * form of a StAX reader,i.e.
038 * {@link XMLStreamReader} or {@link XMLEventReader}.
039 * <code>StAXSource</code> can be used in all cases that accept
040 * a <code>Source</code>, e.g. {@link javax.xml.transform.Transformer},
041 * {@link javax.xml.validation.Validator} which accept
042 * <code>Source</code> as input.
043 *
044 * <p><code>StAXSource</code>s are consumed during processing
045 * and are not reusable.</p>
046 *
047 * @author <a href="mailto:Neeraj.Bajaj@Sun.com">Neeraj Bajaj</a>
048 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
049 * @version $Revision: 1.4 $, $Date: 2006/04/24 13:42:27 $
050 *
051 * @see <a href="http://jcp.org/en/jsr/detail?id=173">
052 * JSR 173: Streaming API for XML</a>
053 * @see XMLStreamReader
054 * @see XMLEventReader
055 *
056 * @since 1.6
057 */
058 public class StAXSource implements Source {
059
060 /** If {@link javax.xml.transform.TransformerFactory#getFeature(String name)}
061 * returns true when passed this value as an argument,
062 * the Transformer supports Source input of this type.
063 */
064 public static final String FEATURE = "http://javax.xml.transform.stax.StAXSource/feature";
065
066 /** <p><code>XMLEventReader</code> to be used for source input.</p> */
067 private XMLEventReader xmlEventReader = null;
068
069 /** <p><code>XMLStreamReader</code> to be used for source input.</p> */
070 private XMLStreamReader xmlStreamReader = null;
071
072 /** <p>System identifier of source input.</p> */
073 private String systemId = null;
074
075 /**
076 * <p>Creates a new instance of a <code>StAXSource</code>
077 * by supplying an {@link XMLEventReader}.</p>
078 *
079 * <p><code>XMLEventReader</code> must be a
080 * non-<code>null</code> reference.</p>
081 *
082 * <p><code>XMLEventReader</code> must be in
083 * {@link XMLStreamConstants#START_DOCUMENT} or
084 * {@link XMLStreamConstants#START_ELEMENT} state.</p>
085 *
086 * @param xmlEventReader <code>XMLEventReader</code> used to create
087 * this <code>StAXSource</code>.
088 *
089 * @throws XMLStreamException If <code>xmlEventReader</code> access
090 * throws an <code>Exception</code>.
091 * @throws IllegalArgumentException If <code>xmlEventReader</code> ==
092 * <code>null</code>.
093 * @throws IllegalStateException If <code>xmlEventReader</code>
094 * is not in <code>XMLStreamConstants.START_DOCUMENT</code> or
095 * <code>XMLStreamConstants.START_ELEMENT</code> state.
096 */
097 public StAXSource(final XMLEventReader xmlEventReader)
098 throws XMLStreamException {
099
100 if (xmlEventReader == null) {
101 throw new IllegalArgumentException(
102 "StAXSource(XMLEventReader) with XMLEventReader == null");
103 }
104
105 // TODO: This is ugly ...
106 // there is no way to know the current position(event) of
107 // XMLEventReader. peek() is the only way to know the next event.
108 // The next event on the input stream should be
109 // XMLStreamConstants.START_DOCUMENT or
110 // XMLStreamConstants.START_ELEMENT.
111 XMLEvent event = xmlEventReader.peek();
112 int eventType = event.getEventType();
113 if (eventType != XMLStreamConstants.START_DOCUMENT
114 && eventType != XMLStreamConstants.START_ELEMENT) {
115 throw new IllegalStateException(
116 "StAXSource(XMLEventReader) with XMLEventReader "
117 + "not in XMLStreamConstants.START_DOCUMENT or "
118 + "XMLStreamConstants.START_ELEMENT state");
119 }
120
121 this .xmlEventReader = xmlEventReader;
122 systemId = event.getLocation().getSystemId();
123 }
124
125 /**
126 * <p>Creates a new instance of a <code>StAXSource</code>
127 * by supplying an {@link XMLStreamReader}.</p>
128 *
129 * <p><code>XMLStreamReader</code> must be a
130 * non-<code>null</code> reference.</p>
131 *
132 * <p><code>XMLStreamReader</code> must be in
133 * {@link XMLStreamConstants#START_DOCUMENT} or
134 * {@link XMLStreamConstants#START_ELEMENT} state.</p>
135 *
136 * @param xmlStreamReader <code>XMLStreamReader</code> used to create
137 * this <code>StAXSource</code>.
138 *
139 * @throws IllegalArgumentException If <code>xmlStreamReader</code> ==
140 * <code>null</code>.
141 * @throws IllegalStateException If <code>xmlStreamReader</code>
142 * is not in <code>XMLStreamConstants.START_DOCUMENT</code> or
143 * <code>XMLStreamConstants.START_ELEMENT</code> state.
144 */
145 public StAXSource(final XMLStreamReader xmlStreamReader) {
146
147 if (xmlStreamReader == null) {
148 throw new IllegalArgumentException(
149 "StAXSource(XMLStreamReader) with XMLStreamReader == null");
150 }
151
152 int eventType = xmlStreamReader.getEventType();
153 if (eventType != XMLStreamConstants.START_DOCUMENT
154 && eventType != XMLStreamConstants.START_ELEMENT) {
155 throw new IllegalStateException(
156 "StAXSource(XMLStreamReader) with XMLStreamReader"
157 + "not in XMLStreamConstants.START_DOCUMENT or "
158 + "XMLStreamConstants.START_ELEMENT state");
159 }
160
161 this .xmlStreamReader = xmlStreamReader;
162 systemId = xmlStreamReader.getLocation().getSystemId();
163 }
164
165 /**
166 * <p>Get the <code>XMLEventReader</code> used by this
167 * <code>StAXSource</code>.</p>
168 *
169 * <p><code>XMLEventReader</code> will be <code>null</code>.
170 * if this <code>StAXSource</code> was created with a
171 * <code>XMLStreamReader</code>.</p>
172 *
173 * @return <code>XMLEventReader</code> used by this
174 * <code>StAXSource</code>.
175 */
176 public XMLEventReader getXMLEventReader() {
177
178 return xmlEventReader;
179 }
180
181 /**
182 * <p>Get the <code>XMLStreamReader</code> used by this
183 * <code>StAXSource</code>.</p>
184 *
185 * <p><code>XMLStreamReader</code> will be <code>null</code>
186 * if this <code>StAXSource</code> was created with a
187 * <code>XMLEventReader</code>.</p>
188 *
189 * @return <code>XMLStreamReader</code> used by this
190 * <code>StAXSource</code>.
191 */
192 public XMLStreamReader getXMLStreamReader() {
193
194 return xmlStreamReader;
195 }
196
197 /**
198 * <p>In the context of a <code>StAXSource</code>, it is not appropriate
199 * to explicitly set the system identifier.
200 * The <code>XMLStreamReader</code> or <code>XMLEventReader</code>
201 * used to construct this <code>StAXSource</code> determines the
202 * system identifier of the XML source.</p>
203 *
204 * <p>An {@link UnsupportedOperationException} is <strong>always</strong>
205 * thrown by this method.</p>
206 *
207 * @param systemId Ignored.
208 *
209 * @throws UnsupportedOperationException Is <strong>always</strong>
210 * thrown by this method.
211 */
212 public void setSystemId(final String systemId) {
213
214 throw new UnsupportedOperationException(
215 "StAXSource#setSystemId(systemId) cannot set the "
216 + "system identifier for a StAXSource");
217 }
218
219 /**
220 * <p>Get the system identifier used by this
221 * <code>StAXSource</code>.</p>
222 *
223 * <p>The <code>XMLStreamReader</code> or <code>XMLEventReader</code>
224 * used to construct this <code>StAXSource</code> is queried to determine
225 * the system identifier of the XML source.</p>
226 *
227 * <p>The system identifier may be <code>null</code> or
228 * an empty <code>""</code> <code>String</code>.</p>
229 *
230 * @return System identifier used by this <code>StAXSource</code>.
231 */
232 public String getSystemId() {
233
234 return systemId;
235 }
236 }
|