javax.xml.transform.stax.StAXResult Maven / Gradle / Ivy

/*
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the "License").  You may not use this file except
 * in compliance with the License.
 *
 * You can obtain a copy of the license at
 * https://jaxp.dev.java.net/CDDLv1.0.html.
 * See the License for the specific language governing
 * permissions and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * HEADER in each file and include the License file at
 * https://jaxp.dev.java.net/CDDLv1.0.html
 * If applicable add the following below this CDDL HEADER
 * with the fields enclosed by brackets "[]" replaced with
 * your own identifying information: Portions Copyright
 * [year] [name of copyright owner]
 */

/*
 * $Id: StAXResult.java,v 1.5 2006/06/28 15:00:35 ndw Exp $
 * %W% %E%
 *
 * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved.
 */

package javax.xml.transform.stax;

import javax.xml.stream.XMLEventWriter;
import javax.xml.stream.XMLStreamWriter;
import javax.xml.transform.Result;

/**
 * Acts as a holder for an XML {@link Result} in the
 * form of a StAX writer,i.e.
 * {@link XMLStreamWriter} or {@link XMLEventWriter}.
 * StAXResult can be used in all cases that accept
 * a Result, e.g. {@link javax.xml.transform.Transformer},
 * {@link javax.xml.validation.Validator} which accept
 * Result as input.
 *
 * @author Neeraj Bajaj
 * @author Jeff Suttor
 * @version $Revision: 1.5 $, $Date: 2006/06/28 15:00:35 $
 *
 * @see 
 *  JSR 173: Streaming API for XML
 * @see XMLStreamWriter
 * @see XMLEventWriter
 *
 * @since 1.6
 */
public class StAXResult implements Result {
    /** If {@link javax.xml.transform.TransformerFactory#getFeature(String name)}
     * returns true when passed this value as an argument,
     * the Transformer supports Result output of this type.
     */
    public static final String FEATURE =
        "http://javax.xml.transform.stax.StAXResult/feature";

    /**
     * 
XMLEventWriter to be used for
     * Result output.
     */
    private XMLEventWriter xmlEventWriter = null;

    /**
     * XMLStreamWriter to be used for
     * Result output.
     */
    private XMLStreamWriter xmlStreamWriter = null;

    /** System identifier for this StAXResult.
 */
    private String systemId = null;

    /**
     * 
Creates a new instance of a StAXResult
     * by supplying an {@link XMLEventWriter}.
     *
     * XMLEventWriter must be a
     * non-null reference.
     *
     * @param xmlEventWriter XMLEventWriter used to create
     *   this StAXResult.
     *
     * @throws IllegalArgumentException If xmlEventWriter ==
     *   null.
     */
    public StAXResult(final XMLEventWriter xmlEventWriter) {

        if (xmlEventWriter == null) {
            throw new IllegalArgumentException(
                    "StAXResult(XMLEventWriter) with XMLEventWriter == null");
        }

        this.xmlEventWriter = xmlEventWriter;
    }

    /**
     * Creates a new instance of a StAXResult
     * by supplying an {@link XMLStreamWriter}.
     *
     * XMLStreamWriter must be a
     * non-null reference.
     *
     * @param xmlStreamWriter XMLStreamWriter used to create
     *   this StAXResult.
     *
     * @throws IllegalArgumentException If xmlStreamWriter ==
     *   null.
     */
    public StAXResult(final XMLStreamWriter xmlStreamWriter) {

        if (xmlStreamWriter == null) {
            throw new IllegalArgumentException(
                    "StAXResult(XMLStreamWriter) with XMLStreamWriter == null");
        }

        this.xmlStreamWriter = xmlStreamWriter;
    }

    /**
     * Get the XMLEventWriter used by this
     * StAXResult.
     *
     * XMLEventWriter will be null
     * if this StAXResult was created with a
     * XMLStreamWriter.
     *
     * @return XMLEventWriter used by this
     *   StAXResult.
     */
    public XMLEventWriter getXMLEventWriter() {

        return xmlEventWriter;
    }

    /**
     * Get the XMLStreamWriter used by this
     * StAXResult.
     *
     * XMLStreamWriter will be null
     * if this StAXResult was created with a
     * XMLEventWriter.
     *
     * @return XMLStreamWriter used by this
     *   StAXResult.
     */
    public XMLStreamWriter getXMLStreamWriter() {

        return xmlStreamWriter;
    }

    /**
     * In the context of a StAXResult, it is not appropriate
     * to explicitly set the system identifier.
     * The XMLEventWriter or XMLStreamWriter
     * used to construct this StAXResult determines the
     * system identifier of the XML result.
     *
     * An {@link UnsupportedOperationException} is always
     * thrown by this method.
     *
     * @param systemId Ignored.
     *
     * @throws UnsupportedOperationException Is always
     *   thrown by this method.
     */
    public void setSystemId(final String systemId) {

        throw new UnsupportedOperationException(
                "StAXResult#setSystemId(systemId) cannot set the "
                + "system identifier for a StAXResult");
    }

    /**
     * The returned system identifier is always null.
     *
     * @return The returned system identifier is always null.
     */
    public String getSystemId() {

        return null;
    }
}