Package org.apache.fluo.api.data

Class Bytes

java.lang.Object

org.apache.fluo.api.data.Bytes

All Implemented Interfaces:

Serializable, Comparable<Bytes>

public final class Bytes
extends Object
implements Comparable<Bytes>, Serializable

Represents bytes in Fluo. Bytes is an immutable wrapper around a byte array. Bytes always copies on creation and never lets its internal byte array escape. Its modeled after Java's String which is an immutable wrapper around a char array. It was created because there is nothing in Java like it at the moment. Its very nice having this immutable type, it avoids having to do defensive copies to ensure correctness. Maybe one day Java will have equivalents of String, StringBuilder, and Charsequence for bytes.

The reason Fluo did not use ByteBuffer is because its not immutable, even a read only ByteBuffer has a mutable position. This makes ByteBuffer unsuitable for place where an immutable data type is desirable, like a key for a map.

Bytes.EMPTY is used to represent a Bytes object with no data.

Since:

1.0.0

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Bytes.BytesBuilder	This class provides an easy, efficient, reusable mechanism for building immutable Bytes objects.

Field Summary

Fields

Modifier and Type	Field	Description
static Bytes	EMPTY

Constructor Summary

Constructors

Constructor	Description
Bytes()

Method Summary

Modifier and Type	Method	Description
static Bytes.BytesBuilder	builder()	Provides an efficient and reusable way to build immutable Bytes objects.
static Bytes.BytesBuilder	builder(int initialCapacity)
byte	byteAt(int i)	Gets a byte within this sequence of bytes
int	compareTo(byte[] bytes)	Compares this to the passed bytes, byte by byte, returning a negative, zero, or positive result if the first sequence is less than, equal to, or greater than the second.
int	compareTo(byte[] bytes, int offset, int len)	Compares this to the passed bytes, byte by byte, returning a negative, zero, or positive result if the first sequence is less than, equal to, or greater than the second.
int	compareTo(Bytes other)	Compares this to the passed bytes, byte by byte, returning a negative, zero, or positive result if the first sequence is less than, equal to, or greater than the second.
boolean	contentEquals(byte[] bytes)	Returns true if this Bytes object equals another.
boolean	contentEquals(byte[] bytes, int offset, int len)	Returns true if this Bytes object equals another.
void	copyTo(byte[] dest, int destPos)	Copy entire Bytes object to specific byte array.
void	copyTo(int start, int end, byte[] dest, int destPos)	Copy a subsequence of Bytes to specific byte array.
boolean	endsWith(Bytes suffix)	Checks if this has the passed suffix
boolean	equals(Object other)	Returns true if this Bytes object equals another.
int	hashCode()
int	length()	Gets the length of bytes
static Bytes	of(byte[] array)	Creates a Bytes object by copying the data of the given byte array
static Bytes	of(byte[] data, int offset, int length)	Creates a Bytes object by copying the data of a subsequence of the given byte array
static Bytes	of(CharSequence cs)	Creates a Bytes object by copying the data of the CharSequence and encoding it using UTF-8.
static Bytes	of(String s)	Creates a Bytes object by copying the value of the given String
static Bytes	of(String s, Charset c)	Creates a Bytes object by copying the value of the given String with a given charset
static Bytes	of(ByteBuffer bb)	Creates a Bytes object by copying the data of the given ByteBuffer.
boolean	startsWith(Bytes prefix)	Checks if this has the passed prefix
Bytes	subSequence(int start, int end)	Returns a portion of the Bytes object
byte[]	toArray()	Returns a byte array containing a copy of the bytes
ByteBuffer	toByteBuffer()
InputStream	toInputStream()
String	toString()	Creates UTF-8 String using Bytes data
void	writeTo(OutputStream out)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY

public static final Bytes EMPTY

Constructor Detail

Bytes

public Bytes()

Method Detail

byteAt

public byte byteAt(int i)

Gets a byte within this sequence of bytes

Parameters:

i - index into sequence

Returns:

byte

Throws:

IndexOutOfBoundsException - if i is out of range

length

public int length()

Gets the length of bytes

subSequence

public Bytes subSequence(int start,
                         int end)

Returns a portion of the Bytes object

Parameters:

start - index of subsequence start (inclusive)

end - index of subsequence end (exclusive)

toArray

public byte[] toArray()

Returns a byte array containing a copy of the bytes

toString

public String toString()

Creates UTF-8 String using Bytes data

Overrides:

toString in class Object

toByteBuffer

public ByteBuffer toByteBuffer()

Returns:

A read only byte buffer that's backed by the internal byte array.

toInputStream

public InputStream toInputStream()

Returns:

An input stream that's backed by the internal byte array

writeTo

public void writeTo(OutputStream out)
             throws IOException

Throws:

IOException

compareTo

public final int compareTo(Bytes other)

Compares this to the passed bytes, byte by byte, returning a negative, zero, or positive result if the first sequence is less than, equal to, or greater than the second. The comparison is performed starting with the first byte of each sequence, and proceeds until a pair of bytes differs, or one sequence runs out of byte (is shorter). A shorter sequence is considered less than a longer one.

Specified by:

compareTo in interface Comparable<Bytes>

Returns:

comparison result

compareTo

public int compareTo(byte[] bytes)

Compares this to the passed bytes, byte by byte, returning a negative, zero, or positive result if the first sequence is less than, equal to, or greater than the second. The comparison is performed starting with the first byte of each sequence, and proceeds until a pair of bytes differs, or one sequence runs out of byte (is shorter). A shorter sequence is considered less than a longer one.

Returns:

comparison result

Since:

1.2.0

compareTo

public int compareTo(byte[] bytes,
                     int offset,
                     int len)

Compares this to the passed bytes, byte by byte, returning a negative, zero, or positive result if the first sequence is less than, equal to, or greater than the second. The comparison is performed starting with the first byte of each sequence, and proceeds until a pair of bytes differs, or one sequence runs out of byte (is shorter). A shorter sequence is considered less than a longer one. This method checks the arguments passed to it.

Returns:

comparison result

Since:

1.2.0

equals

public final boolean equals(Object other)

Returns true if this Bytes object equals another.

Overrides:

equals in class Object

contentEquals

public boolean contentEquals(byte[] bytes)

Returns true if this Bytes object equals another.

Since:

1.2.0

contentEquals

public boolean contentEquals(byte[] bytes,
                             int offset,
                             int len)

Returns true if this Bytes object equals another. This method checks it's arguments.

Since:

1.2.0

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

of

public static final Bytes of(byte[] array)

Creates a Bytes object by copying the data of the given byte array

of

public static final Bytes of(byte[] data,
                             int offset,
                             int length)

Creates a Bytes object by copying the data of a subsequence of the given byte array

Parameters:

data - Byte data

offset - Starting offset in byte array (inclusive)

length - Number of bytes to include

of

public static final Bytes of(ByteBuffer bb)

Creates a Bytes object by copying the data of the given ByteBuffer.

Parameters:

bb - Data will be read from this ByteBuffer in such a way that its position is not changed.

of

public static final Bytes of(CharSequence cs)

Creates a Bytes object by copying the data of the CharSequence and encoding it using UTF-8.

of

public static final Bytes of(String s)

Creates a Bytes object by copying the value of the given String

of

public static final Bytes of(String s,
                             Charset c)

Creates a Bytes object by copying the value of the given String with a given charset

startsWith

public boolean startsWith(Bytes prefix)

Checks if this has the passed prefix

Parameters:

prefix - is a Bytes object to compare to this

Returns:

true or false

Since:

1.1.0

endsWith

public boolean endsWith(Bytes suffix)

Checks if this has the passed suffix

Parameters:

suffix - is a Bytes object to compare to this

Returns:

true or false

Since:

1.1.0

builder

public static Bytes.BytesBuilder builder()

Provides an efficient and reusable way to build immutable Bytes objects.

builder

public static Bytes.BytesBuilder builder(int initialCapacity)

Parameters:

initialCapacity - The initial size of the byte builders internal array.

copyTo

public void copyTo(byte[] dest,
                   int destPos)

Copy entire Bytes object to specific byte array. Uses the specified offset in the dest byte array to start the copy.

Parameters:

dest - destination array

destPos - starting position in the destination data.

Throws:

IndexOutOfBoundsException - if copying would cause access of data outside array bounds.

NullPointerException - if either src or dest is null.

Since:

1.1.0

copyTo

public void copyTo(int start,
                   int end,
                   byte[] dest,
                   int destPos)

Copy a subsequence of Bytes to specific byte array. Uses the specified offset in the dest byte array to start the copy.

Parameters:

start - index of subsequence start (inclusive)

end - index of subsequence end (exclusive)

dest - destination array

destPos - starting position in the destination data.

Throws:

IndexOutOfBoundsException - if copying would cause access of data outside array bounds.

NullPointerException - if either src or dest is null.

Since:

1.1.0