1/*
2 * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package javax.xml.transform.stax;
27
28import javax.xml.stream.XMLEventWriter;
29import javax.xml.stream.XMLStreamWriter;
30import javax.xml.transform.Result;
31
32/**
33 * <p>Acts as a holder for an XML {@link Result} in the
34 * form of a StAX writer,i.e.
35 * {@link XMLStreamWriter} or {@link XMLEventWriter}.
36 * <code>StAXResult</code> can be used in all cases that accept
37 * a <code>Result</code>, e.g. {@link javax.xml.transform.Transformer},
38 * {@link javax.xml.validation.Validator} which accept
39 * <code>Result</code> as input.
40 *
41 * @author <a href="mailto:Neeraj.Bajaj@Sun.com">Neeraj Bajaj</a>
42 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
43 *
44 * @see <a href="http://jcp.org/en/jsr/detail?id=173">
45 *  JSR 173: Streaming API for XML</a>
46 * @see XMLStreamWriter
47 * @see XMLEventWriter
48 *
49 * @since 1.6
50 */
51public class StAXResult implements Result {
52    /** If {@link javax.xml.transform.TransformerFactory#getFeature(String name)}
53     * returns true when passed this value as an argument,
54     * the Transformer supports Result output of this type.
55     */
56    public static final String FEATURE =
57        "http://javax.xml.transform.stax.StAXResult/feature";
58
59    /**
60     * <p><code>XMLEventWriter</code> to be used for
61     * <code>Result</code> output.</p>
62     */
63    private XMLEventWriter xmlEventWriter = null;
64
65    /**
66     * <p><code>XMLStreamWriter</code> to be used for
67     * <code>Result</code> output.</p>
68     */
69    private XMLStreamWriter xmlStreamWriter = null;
70
71    /** <p>System identifier for this <code>StAXResult</code>.<p> */
72    private String systemId = null;
73
74    /**
75     * <p>Creates a new instance of a <code>StAXResult</code>
76     * by supplying an {@link XMLEventWriter}.</p>
77     *
78     * <p><code>XMLEventWriter</code> must be a
79     * non-<code>null</code> reference.</p>
80     *
81     * @param xmlEventWriter <code>XMLEventWriter</code> used to create
82     *   this <code>StAXResult</code>.
83     *
84     * @throws IllegalArgumentException If <code>xmlEventWriter</code> ==
85     *   <code>null</code>.
86     */
87    public StAXResult(final XMLEventWriter xmlEventWriter) {
88
89        if (xmlEventWriter == null) {
90            throw new IllegalArgumentException(
91                    "StAXResult(XMLEventWriter) with XMLEventWriter == null");
92        }
93
94        this.xmlEventWriter = xmlEventWriter;
95    }
96
97    /**
98     * <p>Creates a new instance of a <code>StAXResult</code>
99     * 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}
184