tribble.io
Class Base64EncoderOutputStream

java.lang.Object
  extended by java.io.OutputStream
      extended by java.io.FilterOutputStream
          extended by tribble.io.Base64EncoderOutputStream
All Implemented Interfaces:
java.io.Closeable, java.io.Flushable

public class Base64EncoderOutputStream
extends java.io.FilterOutputStream

Base-64 encoding output stream.

Provides an I/O stream that encodes binary data as base-64 characters. 8-bit bytes (octets) are converted into printable 8-bit characters that encode the data as base-64 (a.k.a. radix-64) ASCII characters as they are written to the output stream.

See Base64Encoder for more information about base-64 encoding.

Source code:
http://david.tribble.com/src/java/tribble/io/Base64EncoderOutputStream.java
Documentation:
http://david.tribble.com/docs/tribble/io/Base64EncoderOutputStream.html

Since:
2003-02-26
Version:
$Revision: 1.9 $ $Date: 2009/02/04 03:35:42 $
Author:
David R. Tribble (david@tribble.com)

Copyright 2003-2009 by David R. Tribble, all rights reserved.
Permission is granted to any person or entity except those designated by by the United States Department of State as a terrorist, or terrorist government or agency, to use and distribute this source code provided that the original copyright notice remains present and unaltered.

See Also:
Base64EncoderInputStream, Base64DecoderOutputStream, Base64Encoder

Field Summary
protected  byte[] m_inBuf
          Pending input queue.
protected  short m_inLen
          Pending input queue length.
protected  short m_newlineStyle
          Newline output style.
protected  byte[] m_outBuf
          Output queue.
protected  short m_outLen
          Number of bytes from the output line written to the output.
protected static byte[] NEWLINE
          Platform-specific newline character sequence.
static short NEWLINE_BYTE
          Newline output style: Single byte ('\n').
protected static short NEWLINE_CALL
          Newline output style: Call out.newLine().
static short NEWLINE_NATIVE
          Newline output style: Native platform character sequence.
static short NEWLINE_NONE
          Newline output style: No newline sequences.
 
Fields inherited from class java.io.FilterOutputStream
out
 
Constructor Summary
Base64EncoderOutputStream(java.io.OutputStream out)
          Constructor.
Base64EncoderOutputStream(java.io.Writer out)
          Constructor.
 
Method Summary
 void close()
          Flush and close this output stream.
 void encode(java.io.InputStream in)
          Read and convert the contents of an input stream.
 void encode(java.io.InputStream in, int bufLen)
          Read and convert the contents of an input stream.
static void encode(java.io.InputStream in, java.io.OutputStream out)
          Read and convert the contents of an input stream.
static void encode(java.io.InputStream in, java.io.OutputStream out, int bufLen)
          Read and convert the contents of an input stream.
 void finish()
          Complete all pending output to this output stream.
 void flush()
          Flush all pending output to this output stream.
 java.io.OutputStream getOutput()
          Retrieve the underlying output stream for this output stream.
static void main(java.lang.String[] args)
          Test driver.
 void newLine()
          Write a newline sequence to this output stream.
 int setNewline(int style)
          Establish the handling of newline sequences for this output stream.
 void write(byte[] data, int off, int len)
          Write a set of bytes to this output stream.
 void write(int c)
          Write a byte to this output stream.
protected  void writePending(int len)
          Convert pending input data bytes into base-64 character bytes and write them to the output stream.
 
Methods inherited from class java.io.FilterOutputStream
write
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NEWLINE_NONE

public static final short NEWLINE_NONE
Newline output style: No newline sequences.

See Also:
Constant Field Values

NEWLINE_BYTE

public static final short NEWLINE_BYTE
Newline output style: Single byte ('\n').

See Also:
Constant Field Values

NEWLINE_NATIVE

public static final short NEWLINE_NATIVE
Newline output style: Native platform character sequence.

See Also:
Constant Field Values

NEWLINE_CALL

protected static final short NEWLINE_CALL
Newline output style: Call out.newLine().

See Also:
Constant Field Values

NEWLINE

protected static final byte[] NEWLINE
Platform-specific newline character sequence.


m_inBuf

protected byte[] m_inBuf
Pending input queue.


m_outBuf

protected byte[] m_outBuf
Output queue.


m_inLen

protected short m_inLen
Pending input queue length.


m_outLen

protected short m_outLen
Number of bytes from the output line written to the output.


m_newlineStyle

protected short m_newlineStyle
Newline output style.

Constructor Detail

Base64EncoderOutputStream

public Base64EncoderOutputStream(java.io.OutputStream out)
Constructor.

Parameters:
out - The underlying output stream for this output stream.
Throws:
java.lang.NullPointerException - (unchecked) Thrown if out is null.
Since:
1.4, 2005-04-08

Base64EncoderOutputStream

public Base64EncoderOutputStream(java.io.Writer out)
Constructor.

Parameters:
out - The underlying output writer for this output stream.
Throws:
java.lang.NullPointerException - (unchecked) Thrown if out is null.
Since:
1.5, 2005-04-08
Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException
Test driver. Read one or more input files and write them in base-64 output form.

Usage

java tribble.io.Base64EncoderOutputStream [-o outfile] file...

Parameters:
args - Command line arguments.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.2, 2005-04-01

encode

public static void encode(java.io.InputStream in,
                          java.io.OutputStream out)
                   throws java.io.IOException
Read and convert the contents of an input stream. This method is equivalent to the call: encode(in, out, 0).

Parameters:
in - An input stream containing 8-bit octet data to be converted into base-64 character output.
out - An output stream to which the converted base-64 character output is to be written.
Throws:
java.io.IOException - Thrown if an I/O (read or write) error occurs.
java.lang.NullPointerException - (unchecked) Thrown if in or out is null.
Since:
1.9, 2009-02-03
See Also:
encode()

encode

public static void encode(java.io.InputStream in,
                          java.io.OutputStream out,
                          int bufLen)
                   throws java.io.IOException
Read and convert the contents of an input stream.

The entire contents of an input stream are read as 8-bit octets and converted into base-64 encoded characters, which are then written to an output stream.

Note that the output stream is finished and flushed after the converted data is written, but is not closed, i.e., methods finish() and flush() are called but close() is not.

Parameters:
in - An input stream containing 8-bit octet data to be converted into base-64 character output.
out - An output stream to which the converted base-64 character output is to be written.
bufLen - Specifies the size, in bytes, of the internal buffer to use for reading data from the input stream. Specifying a value less than 3 causes a default size of 64K (65,536) to be used.
Throws:
java.io.IOException - Thrown if an I/O (read or write) error occurs.
java.lang.NullPointerException - (unchecked) Thrown if in or out is null.
Since:
1.9, 2009-02-03

finish

public void finish()
            throws java.io.IOException
Complete all pending output to this output stream.

All pending base-64 character output is completed, and final padding characters (if any) are appended to the underlying output stream.

Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
java.lang.NullPointerException - (unchecked) Thrown if the underlying output stream is closed.
Since:
1.7, 2005-07-18
See Also:
flush()

flush

public void flush()
           throws java.io.IOException
Flush all pending output to this output stream.

Any pending base-64 character output is written to the underlying output stream, then the underlying output stream itself is flushed.

Note that output characters may still remain pending after this operation if the last bytes written to this stream do not constitute a complete 24-bit octet group. Use the finish() method to force completion of the output stream.

Specified by:
flush in interface java.io.Flushable
Overrides:
flush in class java.io.FilterOutputStream
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
java.lang.NullPointerException - (unchecked) Thrown if the underlying output stream is closed.
Since:
1.1, 2005-04-01
See Also:
finish()

close

public void close()
           throws java.io.IOException
Flush and close this output stream.

Any pending base-64 character output is completed, and the final padding characters (if any) are written to the underlying output stream.

Subsequent attempts to write to this output stream will cause exceptions to be thrown.

Specified by:
close in interface java.io.Closeable
Overrides:
close in class java.io.FilterOutputStream
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.1, 2003-02-26
See Also:
finish(), flush()

write

public void write(int c)
           throws java.io.IOException
Write a byte to this output stream.

The 8-bit byte is converted into its corresponding base-64 character encoding before being written to the underlying output stream.

Overrides:
write in class java.io.FilterOutputStream
Parameters:
c - A character code. Note that only the lower 8 bits are written to the underlying output stream, and the upper 24 bits are ignored.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
java.lang.NullPointerException - (unchecked) Thrown if the underlying output stream is closed.
Since:
1.1, 2003-02-26

write

public void write(byte[] data,
                  int off,
                  int len)
           throws java.io.IOException
Write a set of bytes to this output stream.

The 8-bit bytes are converted into their corresponding base-64 character encoding before being written to the underlying output stream.

Overrides:
write in class java.io.FilterOutputStream
Parameters:
data - An array of bytes to write.
off - Index of the first byte within data to write.
len - Number of bytes from data to write.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
java.lang.NullPointerException - (unchecked) Thrown if the underlying output stream is closed.
java.lang.IndexOutOfBoundsException - (unchecked) Thrown if off or len specify a negative offset or length.
Since:
1.1, 2003-02-26

getOutput

public java.io.OutputStream getOutput()
Retrieve the underlying output stream for this output stream.

Note that this method is not specified by the standard FilterOutputStream library class, but is provided as a convenient enhancement.

Returns:
The underlying output stream for this stream, or null if it has been closed.
Since:
1.2, 2005-04-01

setNewline

public int setNewline(int style)
Establish the handling of newline sequences for this output stream.

Note that newline character sequences are not encoded as base-64 character codes, but is simply written as is to the underlying output stream. Thus this method provides a means for "prettying up" the character output of this stream.

The default style is NEWLINE_NATIVE.

Parameters:
style - Specifies the way that newlines are written to the output stream. This value must be one of the NEWLINE_XXX constants:
NEWLINE_NONE
No newlines are written to the output.
NEWLINE_BYTE
A single newline character byte ('\n') is written after every 64 bytes of output.
NEWLINE_NATIVE
The native character sequence is written after every 64 bytes of output. The sequence is defined by the "line.separator" system property (see System.getProperty()).
Returns:
The previous setting.
Throws:
java.lang.IllegalArgumentException - (unchecked) Thrown if style is not a valid NEWLINE_XXX constant.
Since:
1.1, 2005-04-01

newLine

public void newLine()
             throws java.io.IOException
Write a newline sequence to this output stream.

The behavior of this method depends on the current newline output style setting, which was set by the last call to setNewline().

If the underlying output stream is a Writer object and the newline output mode is set to NEWLINE_NATIVE, then the appropriate method of the output writer is called. If the writer is a PrintWriter, its println() method is called; if it is a BufferedWriter, its newLine() method is called; otherwise, the native newline character sequence is written to it.

Note that the newline character sequence is not encoded as base-64 character codes, but is simply written as is to the underlying output stream. Thus this method provides a means for "prettying up" the character output of this stream.

Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
java.lang.NullPointerException - (unchecked) Thrown if the underlying output stream is closed.
Since:
1.1, 2003-02-26

encode

public void encode(java.io.InputStream in)
            throws java.io.IOException
Read and convert the contents of an input stream. This method is equivalent to the call: encode(in, 0).

Parameters:
in - An input stream containing 8-bit octet data to be converted into base-64 character output.
Throws:
java.io.IOException - Thrown if an I/O (read or write) error occurs.
java.lang.NullPointerException - (unchecked) Thrown if in is null.
Since:
1.6, 2005-04-16
See Also:
encode()

encode

public void encode(java.io.InputStream in,
                   int bufLen)
            throws java.io.IOException
Read and convert the contents of an input stream.

The entire contents of an input stream are read as 8-bit octets and converted into base-64 encoded characters, which are then written to this output stream.

Note that the output stream is finished and flushed after the converted data is written, but is not closed, i.e., methods finish() and flush() are called but close() is not.

Parameters:
in - An input stream containing 8-bit octet data to be converted into base-64 character output.
bufLen - Specifies the size, in bytes, of the internal buffer to use for reading data from the input stream. Specifying a value less than 3 causes a default size of 64K (65,536) to be used.
Throws:
java.io.IOException - Thrown if an I/O (read or write) error occurs.
java.lang.NullPointerException - (unchecked) Thrown if in is null.
Since:
1.6, 2005-04-16

writePending

protected void writePending(int len)
                     throws java.io.IOException
Convert pending input data bytes into base-64 character bytes and write them to the output stream. Final padding characters, if necessary, are appended to the underlying output stream.

Parameters:
len - The number of bytes to convert and write from the pending output buffer (m_inBuf). This should not be greater than the current value of m_inLen.
Throws:
java.io.IOException - Thrown if an I/O (write) error occurs.
Since:
1.7, 2005-07-18