/*
 * Copyright (c) 1997-2018 Oracle and/or its affiliates and others.
 * All rights reserved.
 * Copyright 2004 The Apache Software Foundation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package javax.servlet;

import java.io.CharConversionException;
import java.io.IOException;
import java.io.OutputStream;
import java.text.MessageFormat;
import java.util.ResourceBundle;

Provides an output stream for sending binary data to the client. A ServletOutputStream object is normally retrieved via the ServletResponse.getOutputStream method. 

This is an abstract class that the servlet container implements. Subclasses of this class must implement the
java.io.OutputStream.write(int) method.
Author:
Various
See Also:
ServletResponse/**
 * Provides an output stream for sending binary data to the client. A <code>ServletOutputStream</code> object is
 * normally retrieved via the {@link ServletResponse#getOutputStream} method.
 *
 * <p>
 * This is an abstract class that the servlet container implements. Subclasses of this class must implement the
 * <code>java.io.OutputStream.write(int)</code> method.
 *
 *
 * @author Various
 *
 * @see ServletResponse
 *
 */
public abstract class ServletOutputStream extends OutputStream {

    private static final String LSTRING_FILE = "javax.servlet.LocalStrings";
    private static ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE);

    
Does nothing, because this is an abstract class.
/**
     *
     * Does nothing, because this is an abstract class.
     *
     */
    protected ServletOutputStream() {
    }

    
Writes a String to the client, without a carriage return-line feed (CRLF) character at the end.
Params:
s – the String to send to the client
Throws:
IOException – if an input or output exception occurred/**
     * Writes a <code>String</code> to the client, without a carriage return-line feed (CRLF) character at the end.
     *
     *
     * @param s the <code>String</code> to send to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void print(String s) throws IOException {
        if (s == null)
            s = "null";
        int len = s.length();
        byte[] out = new byte[len];
        for (int i = 0; i < len; i++) {
            char c = s.charAt(i);

            //
            // XXX NOTE: This is clearly incorrect for many strings,
            // but is the only consistent approach within the current
            // servlet framework. It must suffice until servlet output
            // streams properly encode their output.
            //
            if ((c & 0xff00) != 0) { // high order byte must be zero
                String errMsg = lStrings.getString("err.not_iso8859_1");
                Object[] errArgs = new Object[1];
                errArgs[0] = Character.valueOf(c);
                errMsg = MessageFormat.format(errMsg, errArgs);
                throw new CharConversionException(errMsg);
            }
            out[i] = (byte) (0xff & c);
        }
        write(out,0,len);
    }

    
Writes a boolean value to the client, with no carriage return-line feed (CRLF) character at the end.
Params:
b – the boolean value to send to the client
Throws:
IOException – if an input or output exception occurred/**
     * Writes a <code>boolean</code> value to the client, with no carriage return-line feed (CRLF) character at the end.
     *
     * @param b the <code>boolean</code> value to send to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void print(boolean b) throws IOException {
        print(lStrings.getString(b ? "value.true" : "value.false"));
    }

    
Writes a character to the client, with no carriage return-line feed (CRLF) at the end.
Params:
c – the character to send to the client
Throws:
IOException – if an input or output exception occurred/**
     * Writes a character to the client, with no carriage return-line feed (CRLF) at the end.
     *
     * @param c the character to send to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void print(char c) throws IOException {
        print(String.valueOf(c));
    }

    
Writes an int to the client, with no carriage return-line feed (CRLF) at the end.
Params:
i – the int to send to the client
Throws:
IOException – if an input or output exception occurred/**
     *
     * Writes an int to the client, with no carriage return-line feed (CRLF) at the end.
     *
     * @param i the int to send to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void print(int i) throws IOException {
        print(String.valueOf(i));
    }

    
Writes a long value to the client, with no carriage return-line feed (CRLF) at the end.
Params:
l – the long value to send to the client
Throws:
IOException – if an input or output exception occurred/**
     *
     * Writes a <code>long</code> value to the client, with no carriage return-line feed (CRLF) at the end.
     *
     * @param l the <code>long</code> value to send to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void print(long l) throws IOException {
        print(String.valueOf(l));
    }

    
Writes a float value to the client, with no carriage return-line feed (CRLF) at the end.
Params:
f – the float value to send to the client
Throws:
IOException – if an input or output exception occurred/**
     *
     * Writes a <code>float</code> value to the client, with no carriage return-line feed (CRLF) at the end.
     *
     * @param f the <code>float</code> value to send to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     *
     */
    public void print(float f) throws IOException {
        print(String.valueOf(f));
    }

    
Writes a double value to the client, with no carriage return-line feed (CRLF) at the end.
Params:
d – the double value to send to the client
Throws:
IOException – if an input or output exception occurred/**
     *
     * Writes a <code>double</code> value to the client, with no carriage return-line feed (CRLF) at the end.
     *
     * @param d the <code>double</code> value to send to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void print(double d) throws IOException {
        print(String.valueOf(d));
    }

    
Writes a carriage return-line feed (CRLF) to the client.
Throws:
IOException – if an input or output exception occurred/**
     * Writes a carriage return-line feed (CRLF) to the client.
     *
     *
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void println() throws IOException {
        print("\r\n");
    }

    
Writes a String to the client, followed by a carriage return-line feed (CRLF).
Params:
s – the String to write to the client
Throws:
IOException – if an input or output exception occurred/**
     * Writes a <code>String</code> to the client, followed by a carriage return-line feed (CRLF).
     *
     *
     * @param s the <code>String</code> to write to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void println(String s) throws IOException {
        print(s == null ? "null\r\n" : (s + "\r\n"));
    }

    
Writes a boolean value to the client, followed by a carriage return-line feed (CRLF).
Params:
b – the boolean value to write to the client
Throws:
IOException – if an input or output exception occurred/**
     *
     * Writes a <code>boolean</code> value to the client, followed by a carriage return-line feed (CRLF).
     *
     *
     * @param b the <code>boolean</code> value to write to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void println(boolean b) throws IOException {
        println(lStrings.getString(b ? "value.true" : "value.false"));
    }

    
Writes a character to the client, followed by a carriage return-line feed (CRLF).
Params:
c – the character to write to the client
Throws:
IOException – if an input or output exception occurred/**
     *
     * Writes a character to the client, followed by a carriage return-line feed (CRLF).
     *
     * @param c the character to write to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void println(char c) throws IOException {
        println(String.valueOf(c));
    }

    
Writes an int to the client, followed by a carriage return-line feed (CRLF) character.
Params:
i – the int to write to the client
Throws:
IOException – if an input or output exception occurred/**
     *
     * Writes an int to the client, followed by a carriage return-line feed (CRLF) character.
     *
     *
     * @param i the int to write to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void println(int i) throws IOException {
        println(String.valueOf(i));
    }

    
Writes a long value to the client, followed by a carriage return-line feed (CRLF).
Params:
l – the long value to write to the client
Throws:
IOException – if an input or output exception occurred/**
     *
     * Writes a <code>long</code> value to the client, followed by a carriage return-line feed (CRLF).
     *
     *
     * @param l the <code>long</code> value to write to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void println(long l) throws IOException {
        println(String.valueOf(l));
    }

    
Writes a float value to the client, followed by a carriage return-line feed (CRLF).
Params:
f – the float value to write to the client
Throws:
IOException – if an input or output exception occurred/**
     *
     * Writes a <code>float</code> value to the client, followed by a carriage return-line feed (CRLF).
     *
     * @param f the <code>float</code> value to write to the client
     *
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void println(float f) throws IOException {
        println(String.valueOf(f));
    }

    
Writes a double value to the client, followed by a carriage return-line feed (CRLF).
Params:
d – the double value to write to the client
Throws:
IOException – if an input or output exception occurred/**
     *
     * Writes a <code>double</code> value to the client, followed by a carriage return-line feed (CRLF).
     *
     *
     * @param d the <code>double</code> value to write to the client
     *
     * @exception IOException if an input or output exception occurred
     *
     */
    public void println(double d) throws IOException {
        println(String.valueOf(d));
    }

    
This method can be used to determine if data can be written without blocking.
Returns:
true if a write to this ServletOutputStream will succeed, otherwise returns
        false.
Since:
Servlet 3.1/**
     * This method can be used to determine if data can be written without blocking.
     *
     * @return <code>true</code> if a write to this <code>ServletOutputStream</code> will succeed, otherwise returns
     *         <code>false</code>.
     *
     * @since Servlet 3.1
     */
    public abstract boolean isReady();

    
Instructs the ServletOutputStream to invoke the provided WriteListener when it is possible to write 
Params:
writeListener – the WriteListener that should be notified when it's possible to write
Throws:
IllegalStateException – if one of the following conditions is true
                                 

                                 
the associated request is neither upgraded nor the async started
                                 
setWriteListener is called more than once within the scope of the same
                                 request.
                                 
NullPointerException – if writeListener is null
Since:
Servlet 3.1/**
     * Instructs the <code>ServletOutputStream</code> to invoke the provided {@link WriteListener} when it is possible
     * to write
     *
     *
     * @param writeListener the {@link WriteListener} that should be notified when it's possible to write
     *
     * @exception IllegalStateException if one of the following conditions is true
     *                                  <ul>
     *                                  <li>the associated request is neither upgraded nor the async started
     *                                  <li>setWriteListener is called more than once within the scope of the same
     *                                  request.
     *                                  </ul>
     *
     * @throws NullPointerException if writeListener is null
     *
     * @since Servlet 3.1
     */
    public abstract void setWriteListener(WriteListener writeListener);

}