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 26 package javax.xml.transform.stax; 27 28 import javax.xml.stream.XMLEventWriter; 29 import javax.xml.stream.XMLStreamWriter; 30 import 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 */ 51 public 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 }