io.earcam.utilitarian.io

Class SplittableOutputStream

java.lang.Object

java.io.OutputStream

io.earcam.utilitarian.io.SplittableOutputStream

All Implemented Interfaces:

SplittableOutputStreamBuilder, SplittableOutputStreamBuilder.SplitOutputStreamBuilder, Closeable, Flushable, AutoCloseable

@NotThreadSafe
public class SplittableOutputStream
extends OutputStream
implements SplittableOutputStreamBuilder, SplittableOutputStreamBuilder.SplitOutputStreamBuilder

Deals with structured (e.g. XML) or unstructured data.

User code must invoke beginRecord() before writing bytes, and subsequently delimit safe splitting points by invoking endRecord(). The number of bytes written between the call to beginRecord() and call to endRecord() must not exceed maxSize(long) - (header.length + footer.length)

A record is defined as any bytes written between calls to beginRecord() and endRecord(). Should the maximum file size be specified and the length of a single record (plus header and footer) exceed the maximum then a BufferOverflowException is throw.

Common usage would be splitting files, in this case the Supplier is expected to keep track of output file names.

Please note limitation; due to the use of Long internally, the maximum size per-file is limited to 9223372036854775807L bytes (which is 9,223PB or 9,223,000,000GB) per split OutputStream .

Nested Class Summary

Nested classes/interfaces inherited from interface io.earcam.utilitarian.io.SplittableOutputStreamBuilder

SplittableOutputStreamBuilder.SplitOutputStreamBuilder

Method Summary

Modifier and Type	Method and Description
void	beginRecord() Called to mark the beginning of a record (where a "record" is any block of bytes that can only be treated atomically; in that it's valid to split content at the record's boundaries.
void	close()
void	endRecord() Called to mark the end of a record
SplittableOutputStreamBuilder.SplitOutputStreamBuilder	maxCount(long numberOfRecords) Split criteria for maximum number of records.
SplittableOutputStreamBuilder.SplitOutputStreamBuilder	maxSize(long bytes) Split criteria for maximum file size.
SplittableOutputStream	outputStream() The builder's build method.
static SplittableOutputStreamBuilder	splittable(Supplier<OutputStream> next, byte[] head, byte[] footer) Begin building a SplittableOutputStream
void	write(byte[] bytes)
void	write(int b)

Methods inherited from class java.io.OutputStream

flush, write

Methods inherited from class java.lang.Object

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

Method Detail

splittable

public static SplittableOutputStreamBuilder splittable(Supplier<OutputStream> next,
                                                       byte[] head,
                                                       byte[] footer)
                                                throws IOException

Begin building a SplittableOutputStream

Parameters:

next - a Supplier of the underlying OutputStreams

header - written at the start of each OutputStream (e.g. file header)

footer - written at the end of each OutputStream (e.g. file footer)

Returns:

the builder for further construction

Throws:

IOException - rethrows in the unlikely event the underlying ByteArrayOutputStream buffer does

maxSize

public SplittableOutputStreamBuilder.SplitOutputStreamBuilder maxSize(long bytes)

Description copied from interface: SplittableOutputStreamBuilder

Split criteria for maximum file size.

May also be composed with maximum record count criteria.

Specified by:

maxSize in interface SplittableOutputStreamBuilder

Parameters:

bytes - the maximum file size permitted.

Returns:

the builder for further construction

See Also:

SplittableOutputStreamBuilder.maxCount(long)

maxCount

public SplittableOutputStreamBuilder.SplitOutputStreamBuilder maxCount(long numberOfRecords)

Description copied from interface: SplittableOutputStreamBuilder

Split criteria for maximum number of records. Where the definition of a record is any bytes written between calls to SplittableOutputStream#start() and SplittableOutputStream#finish()

May also be composed with maximum file size criteria.

Specified by:

maxCount in interface SplittableOutputStreamBuilder

Parameters:

numberOfRecords - the maximum permitted number of records per file.

Returns:

the builder for further construction

See Also:

SplittableOutputStreamBuilder.maxSize(long)

outputStream

public SplittableOutputStream outputStream()
                                    throws IOException

Description copied from interface: SplittableOutputStreamBuilder.SplitOutputStreamBuilder

The builder's build method.

Note: side effect; also writes the head byte array.

Specified by:

outputStream in interface SplittableOutputStreamBuilder.SplitOutputStreamBuilder

Returns:

An OutputStream for regular use

Throws:

IOException - if the attempt to write the head fails

write

public void write(int b)
           throws IOException

Specified by:

write in class OutputStream

Throws:

IOException

write

public void write(byte[] bytes)
           throws IOException

Overrides:

write in class OutputStream

Throws:

IOException

beginRecord

public void beginRecord()

Called to mark the beginning of a record (where a "record" is any block of bytes that can only be treated atomically; in that it's valid to split content at the record's boundaries.

See Also:

endRecord()

endRecord

public void endRecord()
               throws IOException

Called to mark the end of a record

Throws:

IOException - rethrows anything from the underlying OutputStream

See Also:

beginRecord()

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class OutputStream

Throws:

IOException