tribble.io
Class Base64EncoderOutputStream

java.lang.Object
  java.io.OutputStream
      java.io.FilterOutputStream
          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