https://openjdk.java.net/ 
/*
 * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.xml.transform.stream;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.Reader;
import javax.xml.transform.Result;

import javax.xml.transform.Source;


Acts as an holder for a transformation Source in the form
of a stream of XML markup.


Note: Due to their internal use of either a Reader or InputStream instance, StreamSource instances may only be used once.


Author:Jeff Suttor
Since:1.4
/**
 * <p>Acts as an holder for a transformation Source in the form
 * of a stream of XML markup.</p>
 *
 * <p><em>Note:</em> Due to their internal use of either a {@link Reader} or {@link InputStream} instance,
 * <code>StreamSource</code> instances may only be used once.</p>
 *
 * @author Jeff Suttor
 * @since 1.4
 */
public class StreamSource implements Source {

    
If TransformerFactory.getFeature returns true when passed this value as an argument, the Transformer supports Source input of this type. 
/** If {@link javax.xml.transform.TransformerFactory#getFeature}
     * returns true when passed this value as an argument,
     * the Transformer supports Source input of this type.
     */
    public static final String FEATURE =
        "http://javax.xml.transform.stream.StreamSource/feature";

    
Zero-argument default constructor. If this constructor is used, and no Stream source is set using setInputStream(InputStream inputStream) or setReader(Reader reader), then the Transformer will create an empty source InputStream using new InputStream().


See Also:
/**
     * <p>Zero-argument default constructor.  If this constructor is used, and
     * no Stream source is set using
     * {@link #setInputStream(java.io.InputStream inputStream)} or
     * {@link #setReader(java.io.Reader reader)}, then the
     * <code>Transformer</code> will
     * create an empty source {@link java.io.InputStream} using
     * {@link java.io.InputStream#InputStream() new InputStream()}.</p>
     *
     * @see javax.xml.transform.Transformer#transform(Source xmlSource, Result outputTarget)
     */
    public StreamSource() { }

    
Construct a StreamSource from a byte stream.  Normally,
a stream should be used rather than a reader, so
the XML parser can resolve character encoding specified
by the XML declaration.

If this constructor is used to process a stylesheet, normally
setSystemId should also be called, so that relative URI references
can be resolved.


Params:
  • inputStream – A valid InputStream reference to an XML stream.
/**
     * Construct a StreamSource from a byte stream.  Normally,
     * a stream should be used rather than a reader, so
     * the XML parser can resolve character encoding specified
     * by the XML declaration.
     *
     * <p>If this constructor is used to process a stylesheet, normally
     * setSystemId should also be called, so that relative URI references
     * can be resolved.</p>
     *
     * @param inputStream A valid InputStream reference to an XML stream.
     */
    public StreamSource(InputStream inputStream) {
        setInputStream(inputStream);
    }

    
Construct a StreamSource from a byte stream.  Normally,
a stream should be used rather than a reader, so that
the XML parser can resolve character encoding specified
by the XML declaration.

This constructor allows the systemID to be set in addition
to the input stream, which allows relative URIs
to be processed.


Params:
  • inputStream – A valid InputStream reference to an XML stream.
  • systemId – Must be a String that conforms to the URI syntax.
/**
     * Construct a StreamSource from a byte stream.  Normally,
     * a stream should be used rather than a reader, so that
     * the XML parser can resolve character encoding specified
     * by the XML declaration.
     *
     * <p>This constructor allows the systemID to be set in addition
     * to the input stream, which allows relative URIs
     * to be processed.</p>
     *
     * @param inputStream A valid InputStream reference to an XML stream.
     * @param systemId Must be a String that conforms to the URI syntax.
     */
    public StreamSource(InputStream inputStream, String systemId) {
        setInputStream(inputStream);
        setSystemId(systemId);
    }

    
Construct a StreamSource from a character reader.  Normally,
a stream should be used rather than a reader, so that
the XML parser can resolve character encoding specified
by the XML declaration.  However, in many cases the encoding
of the input stream is already resolved, as in the case of
reading XML from a StringReader.

Params:
  • reader – A valid Reader reference to an XML character stream.
/**
     * Construct a StreamSource from a character reader.  Normally,
     * a stream should be used rather than a reader, so that
     * the XML parser can resolve character encoding specified
     * by the XML declaration.  However, in many cases the encoding
     * of the input stream is already resolved, as in the case of
     * reading XML from a StringReader.
     *
     * @param reader A valid Reader reference to an XML character stream.
     */
    public StreamSource(Reader reader) {
        setReader(reader);
    }

    
Construct a StreamSource from a character reader.  Normally,
a stream should be used rather than a reader, so that
the XML parser may resolve character encoding specified
by the XML declaration.  However, in many cases the encoding
of the input stream is already resolved, as in the case of
reading XML from a StringReader.

Params:
  • reader – A valid Reader reference to an XML character stream.
  • systemId – Must be a String that conforms to the URI syntax.
/**
     * Construct a StreamSource from a character reader.  Normally,
     * a stream should be used rather than a reader, so that
     * the XML parser may resolve character encoding specified
     * by the XML declaration.  However, in many cases the encoding
     * of the input stream is already resolved, as in the case of
     * reading XML from a StringReader.
     *
     * @param reader A valid Reader reference to an XML character stream.
     * @param systemId Must be a String that conforms to the URI syntax.
     */
    public StreamSource(Reader reader, String systemId) {
        setReader(reader);
        setSystemId(systemId);
    }

    
Construct a StreamSource from a URL.

Params:
  • systemId – Must be a String that conforms to the URI syntax.
/**
     * Construct a StreamSource from a URL.
     *
     * @param systemId Must be a String that conforms to the URI syntax.
     */
    public StreamSource(String systemId) {
        this.systemId = systemId;
    }

    
Construct a StreamSource from a File.

Params:
  • f – Must a non-null File reference.
/**
     * Construct a StreamSource from a File.
     *
     * @param f Must a non-null File reference.
     */
    public StreamSource(File f) {
        //convert file to appropriate URI, f.toURI().toASCIIString()
        //converts the URI to string as per rule specified in
        //RFC 2396,
        setSystemId(f.toURI().toASCIIString());
    }

    
Set the byte stream to be used as input.  Normally,
a stream should be used rather than a reader, so that
the XML parser can resolve character encoding specified
by the XML declaration.

If this Source object is used to process a stylesheet, normally
setSystemId should also be called, so that relative URL references
can be resolved.


Params:
  • inputStream – A valid InputStream reference to an XML stream.
/**
     * Set the byte stream to be used as input.  Normally,
     * a stream should be used rather than a reader, so that
     * the XML parser can resolve character encoding specified
     * by the XML declaration.
     *
     * <p>If this Source object is used to process a stylesheet, normally
     * setSystemId should also be called, so that relative URL references
     * can be resolved.</p>
     *
     * @param inputStream A valid InputStream reference to an XML stream.
     */
    public void setInputStream(InputStream inputStream) {
        this.inputStream = inputStream;
    }

    
Get the byte stream that was set with setByteStream.

Returns:The byte stream that was set with setByteStream, or null
if setByteStream or the ByteStream constructor was not called.
/**
     * Get the byte stream that was set with setByteStream.
     *
     * @return The byte stream that was set with setByteStream, or null
     * if setByteStream or the ByteStream constructor was not called.
     */
    public InputStream getInputStream() {
        return inputStream;
    }

    
Set the input to be a character reader.  Normally,
a stream should be used rather than a reader, so that
the XML parser can resolve character encoding specified
by the XML declaration.  However, in many cases the encoding
of the input stream is already resolved, as in the case of
reading XML from a StringReader.

Params:
  • reader – A valid Reader reference to an XML CharacterStream.
/**
     * Set the input to be a character reader.  Normally,
     * a stream should be used rather than a reader, so that
     * the XML parser can resolve character encoding specified
     * by the XML declaration.  However, in many cases the encoding
     * of the input stream is already resolved, as in the case of
     * reading XML from a StringReader.
     *
     * @param reader A valid Reader reference to an XML CharacterStream.
     */
    public void setReader(Reader reader) {
        this.reader = reader;
    }

    
Get the character stream that was set with setReader.

Returns:The character stream that was set with setReader, or null
if setReader or the Reader constructor was not called.
/**
     * Get the character stream that was set with setReader.
     *
     * @return The character stream that was set with setReader, or null
     * if setReader or the Reader constructor was not called.
     */
    public Reader getReader() {
        return reader;
    }

    
Set the public identifier for this Source.

The public identifier is always optional: if the application
writer includes one, it will be provided as part of the
location information.


Params:
  • publicId – The public identifier as a string.
/**
     * Set the public identifier for this Source.
     *
     * <p>The public identifier is always optional: if the application
     * writer includes one, it will be provided as part of the
     * location information.</p>
     *
     * @param publicId The public identifier as a string.
     */
    public void setPublicId(String publicId) {
        this.publicId = publicId;
    }

    
Get the public identifier that was set with setPublicId.

Returns:The public identifier that was set with setPublicId, or null
if setPublicId was not called.
/**
     * Get the public identifier that was set with setPublicId.
     *
     * @return The public identifier that was set with setPublicId, or null
     * if setPublicId was not called.
     */
    public String getPublicId() {
        return publicId;
    }

    
Set the system identifier for this Source.

The system identifier is optional if there is a byte stream
or a character stream, but it is still useful to provide one,
since the application can use it to resolve relative URIs
and can include it in error messages and warnings (the parser
will attempt to open a connection to the URI only if
there is no byte stream or character stream specified).


Params:
  • systemId – The system identifier as a URL string.
/**
     * Set the system identifier for this Source.
     *
     * <p>The system identifier is optional if there is a byte stream
     * or a character stream, but it is still useful to provide one,
     * since the application can use it to resolve relative URIs
     * and can include it in error messages and warnings (the parser
     * will attempt to open a connection to the URI only if
     * there is no byte stream or character stream specified).</p>
     *
     * @param systemId The system identifier as a URL string.
     */
    @Override
    public void setSystemId(String systemId) {
        this.systemId = systemId;
    }

    
Get the system identifier that was set with setSystemId.

Returns:The system identifier that was set with setSystemId, or null
if setSystemId was not called.
/**
     * Get the system identifier that was set with setSystemId.
     *
     * @return The system identifier that was set with setSystemId, or null
     * if setSystemId was not called.
     */
    @Override
    public String getSystemId() {
        return systemId;
    }

    
Set the system ID from a File reference.

Params:
  • f – Must a non-null File reference.
/**
     * Set the system ID from a File reference.
     *
     * @param f Must a non-null File reference.
     */
    public void setSystemId(File f) {
        //convert file to appropriate URI, f.toURI().toASCIIString()
        //converts the URI to string as per rule specified in
        //RFC 2396,
        this.systemId = f.toURI().toASCIIString();
    }

    
Indicates whether the StreamSource object is empty. Empty is defined as follows: 
    

  • All of the input sources, including the public identifier, system identifier, byte stream, and character stream, are null. 
    • 

  • The public identifier and system identifier are null, and byte and character stream are either null or contain no byte or character. 
    
Note that this method will reset the byte stream if it is provided, or
the character stream if the byte stream is not provided.

    • 




In case of error while checking the byte or character stream, the method
will return false to allow the XML processor to handle the error.

Returns:true if the StreamSource object is empty, false otherwise
/**
     * Indicates whether the {@code StreamSource} object is empty. Empty is
     * defined as follows:
     * <ul>
     * <li>All of the input sources, including the public identifier, system
     * identifier, byte stream, and character stream, are {@code null}.
     * </li>
     * <li>The public identifier and system identifier are {@code null}, and
     * byte and character stream are either {@code null} or contain no byte or
     * character.
     * <p>
     * Note that this method will reset the byte stream if it is provided, or
     * the character stream if the byte stream is not provided.
     * </li>
     * </ul>
     * <p>
     * In case of error while checking the byte or character stream, the method
     * will return false to allow the XML processor to handle the error.
     *
     * @return true if the {@code StreamSource} object is empty, false otherwise
     */
    @Override
    public boolean isEmpty() {
        return (publicId == null && systemId == null && isStreamEmpty());
    }

    private boolean isStreamEmpty() {
        boolean empty = true;
        try {
            if (inputStream != null) {
                inputStream.reset();
                int bytesRead = inputStream.available();
                if (bytesRead > 0) {
                    return false;
                }
            }

            if (reader != null) {
                reader.reset();
                int c = reader.read();
                reader.reset();
                if (c != -1) {
                    return false;
                }
            }
        } catch (IOException ex) {
            //in case of error, return false
            return false;
        }

        return empty;
    }

    //////////////////////////////////////////////////////////////////////
    // Internal state.
    //////////////////////////////////////////////////////////////////////

    
The public identifier for this input source, or null.

/**
     * The public identifier for this input source, or null.
     */
    private String publicId;

    
The system identifier as a URL string, or null.

/**
     * The system identifier as a URL string, or null.
     */
    private String systemId;

    
The byte stream for this Source, or null.

/**
     * The byte stream for this Source, or null.
     */
    private InputStream inputStream;

    
The character stream for this Source, or null.

/**
     * The character stream for this Source, or null.
     */
    private Reader reader;
}