Package nom.tam.util

Class BufferedDataOutputStream

java.lang.Object

java.io.OutputStream

java.io.FilterOutputStream

java.io.BufferedOutputStream

nom.tam.util.BufferedDataOutputStream

All Implemented Interfaces:

java.io.Closeable, java.io.DataOutput, java.io.Flushable, java.lang.AutoCloseable, ArrayDataOutput, FitsIO

public class BufferedDataOutputStream
extends java.io.BufferedOutputStream
implements ArrayDataOutput

This class is intended for high performance I/O in scientific applications. It combines the functionality of the BufferedOutputStream and the DataOutputStream as well as more efficient handling of arrays. This minimizes the number of method calls that are required to write data. Informal tests of this method show that it can be as much as 10 times faster than using a DataOutputStream layered on a BufferedOutputStream for writing large arrays. The performance gain on scalars or small arrays will be less but there should probably never be substantial degradation of performance.

Note that there is substantial duplication of code to minimize method invocations. However simple output methods were used where empirical tests seemed to indicate that the simpler method did not cost any time. It seems likely that most of these variations will be washed out across different compilers and users who wish to tune the method for their particular system may wish to compare the the implementation of write(int[], int, int) with write(float[], int, int).

Testing and timing for this class is performed in the nom.tam.util.test.BufferedFileTester class.

Field Summary

Fields

Modifier and Type	Field	Description
private BufferEncoder	bufferEncoder
private BufferPointer	bufferPointer

Fields inherited from class java.io.BufferedOutputStream

buf, count

Fields inherited from class java.io.FilterOutputStream

out

Fields inherited from interface nom.tam.util.FitsIO

BITS_OF_1_BYTE, BITS_OF_2_BYTES, BITS_OF_3_BYTES, BITS_OF_4_BYTES, BITS_OF_5_BYTES, BITS_OF_6_BYTES, BITS_OF_7_BYTES, BYTE_1_OF_LONG_MASK, BYTE_2_OF_LONG_MASK, BYTE_3_OF_LONG_MASK, BYTE_4_OF_LONG_MASK, BYTE_MASK, BYTES_IN_BOOLEAN, BYTES_IN_BYTE, BYTES_IN_CHAR, BYTES_IN_DOUBLE, BYTES_IN_FLOAT, BYTES_IN_INTEGER, BYTES_IN_LONG, BYTES_IN_SHORT, DEFAULT_BUFFER_SIZE, HIGH_INTEGER_MASK, INTEGER_MASK, SHORT_MASK, SHORT_OF_LONG_MASK

Constructor Summary

Constructors

Constructor	Description
BufferedDataOutputStream(java.io.OutputStream o)	Use the BufferedOutputStream constructor
BufferedDataOutputStream(java.io.OutputStream o, int bufLength)	Use the BufferedOutputStream constructor

Method Summary

Modifier and Type	Method	Description
protected void	checkBuf(int need)	See if there is enough space to add something to the buffer.
void	write(boolean[] b)	Write an array of boolean's.
void	write(boolean[] b, int start, int length)	Write a segment of an array of boolean's.
void	write(char[] c)	Write an array of char's.
void	write(char[] c, int start, int length)	Write a segment of an array of char's.
void	write(double[] d)	Write an array of double's.
void	write(double[] d, int start, int length)	Write a segment of an array of double's.
void	write(float[] f)	Write an array of float's.
void	write(float[] f, int start, int length)	Write a segment of an array of float's.
void	write(int[] i)	Write an array of int's.
void	write(int[] i, int start, int length)	Write a segment of an array of int's.
void	write(long[] l)	Write an array of longs.
void	write(long[] l, int start, int length)	Write a segment of an array of longs.
void	write(short[] s)	Write an array of shorts.
void	write(short[] s, int start, int length)	Write a segment of an array of shorts.
void	write(java.lang.String[] s)	Write an array of Strings.
void	write(java.lang.String[] s, int start, int len)	Write a segment of an array of Strings.
void	writeArray(java.lang.Object o)	This routine provides efficient writing of arrays of any primitive type.
void	writeBoolean(boolean b)
void	writeByte(int b)
void	writeBytes(java.lang.String s)
void	writeChar(int c)
void	writeChars(java.lang.String s)
void	writeDouble(double d)
void	writeFloat(float f)
void	writeInt(int i)
void	writeLong(long l)
void	writePrimitiveArray(java.lang.Object o)	Deprecated. use writeArray(Object) instead
void	writeShort(int s)	Write a short value.
void	writeUTF(java.lang.String s)

Methods inherited from class java.io.BufferedOutputStream

flush, write, write

Methods inherited from class java.io.FilterOutputStream

close, write

Methods inherited from class java.io.OutputStream

nullOutputStream

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface nom.tam.util.ArrayDataOutput

flush

Methods inherited from interface java.io.DataOutput

write, write, write

Methods inherited from interface nom.tam.util.FitsIO

close

Field Detail

bufferPointer

private final BufferPointer bufferPointer

bufferEncoder

private final BufferEncoder bufferEncoder

Constructor Detail

BufferedDataOutputStream

public BufferedDataOutputStream(java.io.OutputStream o)

Use the BufferedOutputStream constructor

Parameters:

o - An open output stream.

BufferedDataOutputStream

public BufferedDataOutputStream(java.io.OutputStream o,
                                int bufLength)

Use the BufferedOutputStream constructor

Parameters:

o - An open output stream.

bufLength - The buffer size.

Method Detail

checkBuf

protected void checkBuf(int need)
                 throws java.io.IOException

See if there is enough space to add something to the buffer.

Parameters:

need - the number of bytes that should be available in the buffer.

Throws:

java.io.IOException - if the underlying write operation fails

write

public void write(boolean[] b)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write an array of boolean's.

Specified by:

write in interface ArrayDataOutput

Parameters:

b - array of boolean's.

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(boolean[] b,
                  int start,
                  int length)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write a segment of an array of boolean's.

Specified by:

write in interface ArrayDataOutput

Parameters:

b - array of boolean's.

start - start index in the array

length - number of array elements to write

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(char[] c)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write an array of char's.

Specified by:

write in interface ArrayDataOutput

Parameters:

c - array of char's.

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(char[] c,
                  int start,
                  int length)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write a segment of an array of char's.

Specified by:

write in interface ArrayDataOutput

Parameters:

c - array of char's.

start - start index in the array

length - number of array elements to write

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(double[] d)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write an array of double's.

Specified by:

write in interface ArrayDataOutput

Parameters:

d - array of double's.

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(double[] d,
                  int start,
                  int length)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write a segment of an array of double's.

Specified by:

write in interface ArrayDataOutput

Parameters:

d - array of double's.

start - start index in the array

length - number of array elements to write

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(float[] f)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write an array of float's.

Specified by:

write in interface ArrayDataOutput

Parameters:

f - array of float's.

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(float[] f,
                  int start,
                  int length)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write a segment of an array of float's.

Specified by:

write in interface ArrayDataOutput

Parameters:

f - array of float's.

start - start index in the array

length - number of array elements to write

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(int[] i)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write an array of int's.

Specified by:

write in interface ArrayDataOutput

Parameters:

i - array of int's

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(int[] i,
                  int start,
                  int length)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write a segment of an array of int's.

Specified by:

write in interface ArrayDataOutput

Parameters:

i - array of int's

start - start index in the array

length - number of array elements to write

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(long[] l)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write an array of longs.

Specified by:

write in interface ArrayDataOutput

Parameters:

l - array of longs

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(long[] l,
                  int start,
                  int length)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write a segment of an array of longs.

Specified by:

write in interface ArrayDataOutput

Parameters:

l - array of longs

start - start index in the array

length - number of array elements to write

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(short[] s)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write an array of shorts.

Specified by:

write in interface ArrayDataOutput

Parameters:

s - the value to write

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(short[] s,
                  int start,
                  int length)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write a segment of an array of shorts.

Specified by:

write in interface ArrayDataOutput

Parameters:

s - the value to write

start - start index in the array

length - number of array elements to write

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(java.lang.String[] s)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write an array of Strings. Equivalent to calling writeBytes for the selected elements.

Specified by:

write in interface ArrayDataOutput

Parameters:

s - the array to write

Throws:

java.io.IOException - if one of the underlying write operations failed

write

public void write(java.lang.String[] s,
                  int start,
                  int len)
           throws java.io.IOException

Description copied from interface: ArrayDataOutput

Write a segment of an array of Strings. Equivalent to calling writeBytes for the selected elements.

Specified by:

write in interface ArrayDataOutput

Parameters:

s - the array to write

start - start index in the array

len - number of array elements to write

Throws:

java.io.IOException - if one of the underlying write operations failed

writeArray

public void writeArray(java.lang.Object o)
                throws java.io.IOException

Description copied from interface: ArrayDataOutput

This routine provides efficient writing of arrays of any primitive type. The String class is also handled but it is an error to invoke this method with an object that is not an array of these types. If the array is multidimensional, then it calls itself recursively to write the entire array. Strings are written using the standard 1 byte format (i.e., as in writeBytes). If the array is an array of objects, then writePrimitiveArray will be called for each element of the array.

Specified by:

writeArray in interface ArrayDataOutput

Parameters:

o - The object to be written. It must be an array of a primitive type, Object, or String.

Throws:

java.io.IOException - if one of the underlying write operations failed

writeBoolean

public void writeBoolean(boolean b)
                  throws java.io.IOException

Specified by:

writeBoolean in interface java.io.DataOutput

Throws:

java.io.IOException

writeByte

public void writeByte(int b)
               throws java.io.IOException

Specified by:

writeByte in interface java.io.DataOutput

Throws:

java.io.IOException

writeBytes

public void writeBytes(java.lang.String s)
                throws java.io.IOException

Specified by:

writeBytes in interface java.io.DataOutput

Throws:

java.io.IOException

writeChar

public void writeChar(int c)
               throws java.io.IOException

Specified by:

writeChar in interface java.io.DataOutput

Throws:

java.io.IOException

writeChars

public void writeChars(java.lang.String s)
                throws java.io.IOException

Specified by:

writeChars in interface java.io.DataOutput

Throws:

java.io.IOException

writeDouble

public void writeDouble(double d)
                 throws java.io.IOException

Specified by:

writeDouble in interface java.io.DataOutput

Throws:

java.io.IOException

writeFloat

public void writeFloat(float f)
                throws java.io.IOException

Specified by:

writeFloat in interface java.io.DataOutput

Throws:

java.io.IOException

writeInt

public void writeInt(int i)
              throws java.io.IOException

Specified by:

writeInt in interface java.io.DataOutput

Throws:

java.io.IOException

writeLong

public void writeLong(long l)
               throws java.io.IOException

Specified by:

writeLong in interface java.io.DataOutput

Throws:

java.io.IOException

writePrimitiveArray

@Deprecated
public void writePrimitiveArray(java.lang.Object o)
                         throws java.io.IOException

Deprecated.

use writeArray(Object) instead

Deprecated use writeArray(Object).

Parameters:

o - The object to be written.

Throws:

java.io.IOException - if one of the underlying write operations failed

writeShort

public void writeShort(int s)
                throws java.io.IOException

Write a short value.

Specified by:

writeShort in interface java.io.DataOutput

Throws:

java.io.IOException

writeUTF

public void writeUTF(java.lang.String s)
              throws java.io.IOException

Specified by:

writeUTF in interface java.io.DataOutput

Throws:

java.io.IOException