org.sakaiproject.util.java
Class Blob

java.lang.Object
  extended byorg.sakaiproject.util.java.Blob
All Implemented Interfaces:
Cloneable, Serializable

public class Blob
extends Object
implements Cloneable, Serializable

A blob is a Binary Large OBject. The Blob uses a linked list structure internally so it is not susceptible to running out of memory when growing. This can be a problem with very large Vectors -- when they grow, a new, larger internal array is created and elements copied over. Thus, for that short amount of time, there are two copies of the array. That, plus the added overhead of storing bytes in object form, make the Blob the preferrable method for storing raw data.

Since it uses ints as indicies, a single Blob can hold up to Integer.MAX_VALUE (2,147,483,647) bytes. Could be modified to use longs and then could hold up to Long.MAX_VALUE (9.2233e18) bytes if your computer had that much storage. :^)

This is my 'pet' class.

Author:
T. Gee
See Also:
Serialized Form

Field Summary
protected  org.sakaiproject.util.java.BlobNode curr
           
protected  org.sakaiproject.util.java.BlobNode enumerationNode
           
protected  int enumerationPos
           
protected  org.sakaiproject.util.java.BlobNode head
           
static int NODE_SIZE
          The default internal data storage node size.
protected  int nodeSize
           
protected  int size
           
protected  org.sakaiproject.util.java.BlobNode tail
           
 
Constructor Summary
Blob()
          Creates a new, empty Blob.
Blob(Blob b)
          Creates a new blob that is a copy of an existing blob.
Blob(byte[] arr)
          Creates a new blob and initialized it with a byte array.
Blob(byte[] arr, int startPos, int len)
          Creates a new blob and initialized it with a byte array.
Blob(int nodeSize)
          Creates a new, empty Blob and specifies the default internal node size.
 
Method Summary
 void append(Blob b)
          Appends the bytes from a Blob to the end of the Blob.
 void append(boolean addHighByte, char c)
          Appends one or two bytes (in the form of a char) to the end of the Blob.
 void append(boolean addHighByte, String s)
          Appends bytes from a String to the end of the Blob.
 void append(byte b)
          Appends a byte to the end of the Blob.
 void append(byte[] arr)
          Appends an entire byte array to the end of the Blob.
 void append(byte[] arr, int startPos, int len)
          Appends a byte array to the end of the Blob.
 void append(char c)
          Appends one byte (in the form of a char) to the end of the Blob.
 void append(double d)
          Appends eight bytes (in the form of a double) to the end of the Blob.
 void append(float f)
          Appends four bytes (in the form of a float) to the end of the Blob.
 void append(int i)
          Appends four bytes (in the form of an int) to the end of the Blob.
 void append(long l)
          Appends eight bytes (in the form of a long) to the end of the Blob.
 void append(short s)
          Appends two bytes (in the form of a short) to the end of the Blob.
 void append(String s)
          Appends bytes from a String to the end of the Blob.
protected  void appendNode(int newNodeSize)
          Appends a new node to the end of the internal list.
protected  void beginEnumeration(int pos)
          Sets up an enumeration of the bytes of the Blob starting from a particular point.
protected static boolean between(char test, char low, char high)
          An inclusive between function (for chars).
static boolean between(int test, int low, int high)
          An inclusive between function (for ints).
 byte byteAt(int pos)
          Returns the byte at a specific location.
 char charAt(boolean useHighByte, int pos)
          Returns a character reconstructed from one or two bytes at a specific location.
 char charAt(int pos)
          Returns a character reconstructed from one byte at a specific location.
 long checksum()
          Generates and returns an 8-byte checksum.
 Object clone()
          Clones this Blob.
 double doubleAt(int pos)
          Returns a double precision floating point number reconstructed from eight bytes at a specific
 Enumeration enumerateBytes(int pos)
          Returns an enumeration of the bytes in this Blob.
 boolean equals(Object o)
          Returns true if the blob is equal to the given object.
protected  org.sakaiproject.util.java.BlobNode findBefore(org.sakaiproject.util.java.BlobNode target)
          Finds the node before the given node.
protected  float floatAt(int pos)
          Returns a floating point number reconstructed from four bytes at a specific location.
 Blob getBlob(int pos, int len)
          Returns a new Blob drawn from bytes at a specific location.
 byte[] getBytes()
          Gets the bytes of the blob as a byte array.
 byte[] getBytes(int start, int len)
          Returns a subset of the bytes of the blob as a byte array.
 String getString()
          Returns a String reconstructed from the bytes of the Blob.
 String getString(boolean useHighByte, int pos, int len)
          Returns a String reconstructed from bytes at a specific location.
 String getString(int pos, int len)
          Returns a String reconstructed from bytes at a specific location.
protected  boolean hasMoreBytes()
          Returns 'true' if the Blob has more bytes, 'false' if empty.
static char hexDigit(int i)
          Returns the hex digit cooresponding to a number between 0 and 15.
 int indexOf(byte b)
          Searches for a byte and returns an index to the first one found.
 int indexOf(byte b, int pos)
          Searches for a byte and returns an index to the first one found.
 InputStream inputStream()
          provide an input stream that reads the blob contents
 void insertByte(int pos, byte b)
          Inserts a byte into the blob at the position pos.
 void insertBytes(int pos, byte[] arr)
          Inserts a byte into the blob at the position pos.
 void insertBytes(int pos, byte[] arr, int startPos, int len)
          Inserts a byte into the blob at the position pos.
 int intAt(int pos)
          Returns an int reconstructed from four bytes at a specific location.
 int length()
          Gets the number of bytes in the Blob.
 long longAt(int pos)
          Returns a long int reconstructed from eight bytes at a specific location.
protected  byte nextByte()
          Returns the next byte in the Blob.
 OutputStream outputStream()
          provide an output stream that writes to the END of the blob (appends)
 void printContents()
          Prints the contents of this Blob.
 int read(InputStream in)
          Reads all bytes from an InputStream into the Blob.
 int read(int len, InputStream in)
          Reads bytes from an InputStream into the Blob.
 int readLimiting(InputStream in, long max)
          Reads most bytes from an InputStream into the Blob - not to exceed bytes by much (it may read up to nodeSize more).
protected  void readObject(ObjectInputStream in)
          A specialized object read routine.
 void removeByte(int pos)
          Removes a byte from the Blob at the requested position.
 void removeBytes(int pos, int len)
          Removes a number of bytes from the Blob at the requested position.
protected  int seek(int pos)
          Seeks a position within the internal list.
 void setByteAt(int pos, byte b)
          Sets a byte at a particular position.
 short shortAt(int pos)
          Returns a short int reconstructed from two bytes at a specific location.
static String spaces(int n)
          Returns a string of a specified number of spaces.
static String strstr(int n, char c)
          Returns a string of a specified number of a specified character.
static String toHex(byte b)
          Returns a hex representation of a byte.
static String toHex(int i)
          Returns the hex representation of an int.
static String toHex(long l)
          Returns the hex representation of an long.
static String toHex(short s)
          Returns the hex representation of a short.
static String toHex(String s)
          Returns the hex representation of the characters of a String.
 String toString()
          Returns a string representation of the Blob.
 void truncate(int len)
          Truncates the Blob to the specified position.
 void write(int pos, int len, OutputStream out)
          Writes the contents of a part of the Blob to an OutputStream.
 void write(OutputStream out)
          Writes the entire contents of the Blob to an OutputStream.
protected  void writeObject(ObjectOutputStream out)
          A specialized object write routine.
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

NODE_SIZE

public static final int NODE_SIZE
The default internal data storage node size.

See Also:
Constant Field Values

head

protected transient org.sakaiproject.util.java.BlobNode head

tail

protected transient org.sakaiproject.util.java.BlobNode tail

size

protected transient int size

nodeSize

protected int nodeSize

curr

protected transient org.sakaiproject.util.java.BlobNode curr

enumerationNode

protected transient org.sakaiproject.util.java.BlobNode enumerationNode

enumerationPos

protected transient int enumerationPos
Constructor Detail

Blob

public Blob()
Creates a new, empty Blob. Uses default internal node size.


Blob

public Blob(int nodeSize)
Creates a new, empty Blob and specifies the default internal node size.


Blob

public Blob(Blob b)
Creates a new blob that is a copy of an existing blob.

Parameters:
b - The Blob to copy.

Blob

public Blob(byte[] arr)
Creates a new blob and initialized it with a byte array.

Parameters:
arr - A byte array to copy entirely into the new Blob.

Blob

public Blob(byte[] arr,
            int startPos,
            int len)
Creates a new blob and initialized it with a byte array.

Parameters:
arr - A byte array to copy into the new Blob.
startPos - The location to start extracting bytes from.
len - The length of the array to copy in.
Method Detail

between

protected static final boolean between(char test,
                                       char low,
                                       char high)
An inclusive between function (for chars).

Parameters:
test - The char to test.
low - The lower bound.
high - The upper bound.
Returns:
true if test is between low and high (inclusive), false otherwise.

between

public static final boolean between(int test,
                                    int low,
                                    int high)
An inclusive between function (for ints).

Parameters:
test - The number to test.
low - The lower bound.
high - The upper bound.
Returns:
true if test is between low and high (inclusive), false otherwise.

toHex

public static final String toHex(byte b)
Returns a hex representation of a byte.

Parameters:
b - The byte to convert to hex.
Returns:
The 2-digit hex value of the supplied byte.

toHex

public static final String toHex(short s)
Returns the hex representation of a short.

Parameters:
s - The short to convert to hex.
Returns:
The 4-digit hex value of the supplied short.

toHex

public static final String toHex(int i)
Returns the hex representation of an int.

Parameters:
i - The int to convert to hex.
Returns:
The 8-digit hex value of the supplied int.

toHex

public static final String toHex(long l)
Returns the hex representation of an long.

Parameters:
l - The long to convert to hex.
Returns:
The 16-digit hex value of the supplied long.

toHex

public static final String toHex(String s)
Returns the hex representation of the characters of a String.

Parameters:
s - The String to convert to hex.
Returns:
A String where each character of the original string is given as a space seperated sequence of hex values.

hexDigit

public static final char hexDigit(int i)
Returns the hex digit cooresponding to a number between 0 and 15.

Parameters:
i - The number to get the hex digit for.
Returns:
The hex digit cooresponding to that number.
Throws:
IllegalArgumentException - If supplied digit is not between 0 and 15 inclusive.

strstr

public static final String strstr(int n,
                                  char c)
Returns a string of a specified number of a specified character.

Parameters:
n - The number of characters to create in the return String.
c - The character to create.
Returns:
A String of the requested number of the requested character.

spaces

public static final String spaces(int n)
Returns a string of a specified number of spaces.

Parameters:
n - The number of spaces to create.
Returns:
A String of the requested number of spaces.
See Also:
strstr(int, char)

append

public void append(byte b)
Appends a byte to the end of the Blob.

Parameters:
b - The byte to add.

append

public void append(char c)
Appends one byte (in the form of a char) to the end of the Blob. Strips the high byte off.

Parameters:
c - The character to add.

append

public void append(boolean addHighByte,
                   char c)
Appends one or two bytes (in the form of a char) to the end of the Blob. Can optionally add the high byte or not.

Parameters:
addHighByte - 'true' to add the character's high byte to the Blob; 'false' to strip it.
c - The character to add.

append

public void append(short s)
Appends two bytes (in the form of a short) to the end of the Blob.

Parameters:
s - The short integer to add.

append

public void append(int i)
Appends four bytes (in the form of an int) to the end of the Blob.

Parameters:
i - The integer to add.

append

public void append(long l)
Appends eight bytes (in the form of a long) to the end of the Blob.

Parameters:
l - The long integer to add.

append

public void append(float f)
Appends four bytes (in the form of a float) to the end of the Blob.

Parameters:
f - The float to add.

append

public void append(double d)
Appends eight bytes (in the form of a double) to the end of the Blob.

Parameters:
d - The double to add.

append

public void append(String s)
Appends bytes from a String to the end of the Blob. Strips the high bytes from the characters.

Parameters:
s - The String to add.

append

public void append(boolean addHighByte,
                   String s)
Appends bytes from a String to the end of the Blob. Can optionally add the high bytes from the characters or not.

Parameters:
addHighByte - 'true' to add the characters' high byte to the Blob; 'false' to strip it.
s - The String to add.

append

public void append(byte[] arr)
Appends an entire byte array to the end of the Blob.

Parameters:
arr - The array to add bytes from.

append

public void append(byte[] arr,
                   int startPos,
                   int len)
Appends a byte array to the end of the Blob.

Parameters:
arr - The array to add bytes from.
startPos - The position to start the byte extraction from the array at.
len - The number of bytes to read from the array.

append

public void append(Blob b)
Appends the bytes from a Blob to the end of the Blob.

Parameters:
b - The Blob to draw bytes from.

insertByte

public void insertByte(int pos,
                       byte b)
Inserts a byte into the blob at the position pos. Everything else is moved back.

Parameters:
pos - The postition to add the byte at (0 -> beginning).
b - The byte to add.
Throws:
IndexOutOfBoundsException - If pos is outside range of Blob.
See Also:
insertBytes(int, byte[])

insertBytes

public void insertBytes(int pos,
                        byte[] arr)
Inserts a byte into the blob at the position pos. Everything else is moved back.

Parameters:
pos - The postition to begin adding the bytes at (0 -> beginning).
arr - The array of bytes to add from.
Throws:
IndexOutOfBoundsException - If pos is outside range of Blob.

insertBytes

public void insertBytes(int pos,
                        byte[] arr,
                        int startPos,
                        int len)
Inserts a byte into the blob at the position pos. Everything else is moved back.

Parameters:
pos - The postition to begin adding the bytes at (0 -> beginning).
arr - The array of bytes to add from.
startPos - The position to begin byte copy from.
len - The number of bytes to add from the array.
Throws:
IndexOutOfBoundsException - If pos is outside range of Blob.

truncate

public void truncate(int len)
Truncates the Blob to the specified position. The Blob will have the given number of bytes left.

Parameters:
len - The size to truncate the Blob to.
Throws:
IndexOutOfBoundsException - If len is outside range of Blob.

removeByte

public void removeByte(int pos)
Removes a byte from the Blob at the requested position. Everything else is moved up.

Parameters:
pos - The position to remove a byte from (0 -> beginning).
Throws:
IndexOutOfBoundsException - If pos is outside range of Blob.
See Also:
removeBytes(int, int)

removeBytes

public void removeBytes(int pos,
                        int len)
Removes a number of bytes from the Blob at the requested position. Everything else is moved up.

Parameters:
pos - The position to remove the bytes from (0 -> beginning).
len - The number of bytes to remove.
Throws:
IndexOutOfBoundsException - If pos and len are outside range of Blob.

getBytes

public byte[] getBytes()
Gets the bytes of the blob as a byte array.

Returns:
An array of the bytes that compose the Blob.

getBytes

public byte[] getBytes(int start,
                       int len)
Returns a subset of the bytes of the blob as a byte array.

Parameters:
start - start index to begin draw (included in get).
len - number of bytes to extract.
Returns:
An array of the bytes that compose the Blob.
Throws:
IndexOutOfBoundsException - If start and len are outside range of Blob.

byteAt

public byte byteAt(int pos)
Returns the byte at a specific location.

Parameters:
pos - The position to from which to return the byte (0 -> beginning).
Returns:
The byte at requested position.
Throws:
IndexOutOfBoundsException - If pos is outside range of Blob.

charAt

public char charAt(int pos)
Returns a character reconstructed from one byte at a specific location. Sets the high byte in the character to 0x0.

Parameters:
pos - The position to get the byte to reconstuct the character (0 -> beginning).
Returns:
The reconstructed character.
Throws:
IndexOutOfBoundsException - If the requested char is outside the Blob.

charAt

public char charAt(boolean useHighByte,
                   int pos)
Returns a character reconstructed from one or two bytes at a specific location.

Parameters:
useHighByte - 'true' to use two bytes (one for the high byte) to reconstruct a character; 'false' to use one byte and set the high byte to 0x0.
pos - The position to get the byte(s) to reconstuct the character (0 -> beginning).
Returns:
The reconstructed character.
Throws:
IndexOutOfBoundsException - If the requested bytes are outside the Blob.

shortAt

public short shortAt(int pos)
Returns a short int reconstructed from two bytes at a specific location.

Parameters:
pos - The position to get the bytes to reconstuct the short (0 -> beginning).
Returns:
The reconstructed short.
Throws:
IndexOutOfBoundsException - If the requested bytes are outside the Blob.

intAt

public int intAt(int pos)
Returns an int reconstructed from four bytes at a specific location.

Parameters:
pos - The position to get the bytes to reconstuct the int (0 -> beginning).
Returns:
The reconstructed int.
Throws:
IndexOutOfBoundsException - If the requested bytes are outside the Blob.

longAt

public long longAt(int pos)
Returns a long int reconstructed from eight bytes at a specific location.

Parameters:
pos - The position to get the bytes to reconstuct the long (0 -> beginning).
Returns:
The reconstructed long.
Throws:
IndexOutOfBoundsException - If the requested bytes are outside the Blob.

floatAt

protected float floatAt(int pos)
Returns a floating point number reconstructed from four bytes at a specific location.

Parameters:
pos - The position to get the bytes to reconstuct the float (0 -> beginning).
Returns:
The reconstructed float.
Throws:
IndexOutOfBoundsException - If the requested bytes are outside the Blob.

doubleAt

public double doubleAt(int pos)
Returns a double precision floating point number reconstructed from eight bytes at a specific

Parameters:
pos - The position to get the bytes to reconstuct the double (0 -> beginning).
Returns:
The reconstructed double.
Throws:
IndexOutOfBoundsException - If the requested bytes are outside the Blob.

getString

public String getString()
Returns a String reconstructed from the bytes of the Blob. Sets the high byte in each character to 0x0.

Returns:
The reconstructed String.

getString

public String getString(int pos,
                        int len)
Returns a String reconstructed from bytes at a specific location. Sets the high byte in each character to 0x0.

Parameters:
pos - The position to start retrieving the bytes to reconstuct the String (0 -> beginning).
len - The length of the to-be-returned String.
Returns:
The reconstructed String.
Throws:
IndexOutOfBoundsException - If the requested bytes are outside the Blob.

getString

public String getString(boolean useHighByte,
                        int pos,
                        int len)
Returns a String reconstructed from bytes at a specific location.

Parameters:
useHighByte - 'true' to use two bytes (one for the high byte) to reconstruct each character; 'false' to use one byte and set the high byte to 0x0.
pos - The position to start retrieving the bytes to reconstuct the String (0 -> beginning).
len - The length of the to-be-returned String.
Returns:
The reconstructed String.
Throws:
IndexOutOfBoundsException - If the requested bytes are outside the Blob.

clone

public Object clone()
Clones this Blob. The resulting Blob will have the same data as the first. (altho possibly not the same internal configuration).


getBlob

public Blob getBlob(int pos,
                    int len)
Returns a new Blob drawn from bytes at a specific location.

Parameters:
pos - The position to start retrieving the bytes to build the new Blob (0 -> beginning).
len - The number of bytes to put into the new Blob.
Returns:
The newly constructed Blob.
Throws:
IndexOutOfBoundsException - If the requested bytes are outside the Blob.

enumerateBytes

public Enumeration enumerateBytes(int pos)
Returns an enumeration of the bytes in this Blob. The objects returned from the calls to nextElement are of type Byte.

Parameters:
pos - The location from which to begin enumerating bytes.
Throws:
IndexOutOfBoundsException - If pos is outside range of Blob.

setByteAt

public void setByteAt(int pos,
                      byte b)
Sets a byte at a particular position.

Parameters:
pos - The position to set the byte at.
b - The value to set that postion to.
Throws:
IndexOutOfBoundsException - If pos is outside range of Blob.

length

public int length()
Gets the number of bytes in the Blob.

Returns:
The number of bytes in the Blob.

equals

public boolean equals(Object o)
Returns true if the blob is equal to the given object. True only if supplied object is a Blob and the two contain exactly the same data.


indexOf

public int indexOf(byte b)
Searches for a byte and returns an index to the first one found.

Parameters:
b - The byte to search for.
Returns:
The index of the first match or -1 if not found.

indexOf

public int indexOf(byte b,
                   int pos)
Searches for a byte and returns an index to the first one found. Search starts at given index and includes that index.

Parameters:
b - The byte to search for.
pos - The position to begin searching at (0 -> beginning).
Returns:
The index of the first match or -1 if not found.
Throws:
IndexOutOfBoundsException - If pos is outside range of Blob.

read

public int read(int len,
                InputStream in)
         throws IOException
Reads bytes from an InputStream into the Blob.

Parameters:
len - The number of bytes to attempt to read.
in - The InputStream to read from.
Returns:
The number of bytes read and appended to the blob or -1 if the end of the stream was reached.
Throws:
IOException - If there is a problem reading.

read

public int read(InputStream in)
         throws IOException
Reads all bytes from an InputStream into the Blob. This will read an InputStream byte-by-byte until EOF and append the data to the end of the Blob.

Parameters:
in - The InputStream to read from.
Returns:
The number of bytes read and appended to the blob or -1 if the end of the stream was reached immediately.
Throws:
IOException - If there is a problem reading.

readLimiting

public int readLimiting(InputStream in,
                        long max)
                 throws IOException
Reads most bytes from an InputStream into the Blob - not to exceed bytes by much (it may read up to nodeSize more). This will read an InputStream byte-by-byte until EOF and append the data to the end of the Blob.

Parameters:
in - The InputStream to read from.
max - the max (sort of) bytes to read
Returns:
The number of bytes read and appended to the blob or -1 if the end of the stream was reached immediately. or -2 if we cut off due to max before end
Throws:
IOException - If there is a problem reading.

outputStream

public OutputStream outputStream()
provide an output stream that writes to the END of the blob (appends)


inputStream

public InputStream inputStream()
provide an input stream that reads the blob contents


write

public void write(OutputStream out)
           throws IOException
Writes the entire contents of the Blob to an OutputStream.

Parameters:
out - The OutputStream to write to.
Throws:
IOException - If there is a problem writing.

write

public void write(int pos,
                  int len,
                  OutputStream out)
           throws IOException
Writes the contents of a part of the Blob to an OutputStream.

Parameters:
pos - The position to begin writing from.
len - The number of bytes to write.
out - The OutputStream to write to.
Throws:
IndexOutOfBoundsException - If pos and len are outside range of Blob.
IOException - If there is a problem writing.

checksum

public long checksum()
Generates and returns an 8-byte checksum.


toString

public String toString()
Returns a string representation of the Blob. Includes length and checksum.

See Also:
printContents()

printContents

public void printContents()
Prints the contents of this Blob. Formats the data neatly and prints it to System.out.

See Also:
toString()

appendNode

protected void appendNode(int newNodeSize)
Appends a new node to the end of the internal list.

Parameters:
newNodeSize - Size of the new node to create.

seek

protected int seek(int pos)
Seeks a position within the internal list. Takes an offset from the beginning and sets the 'curr' pointer to the reqested node and returns the offset within that node to the correct position.

Parameters:
pos - The position within the Blob to seek.
Returns:
The offest into the current node where the requested byte can be found.
Throws:
IndexOutOfBoundsException - If pos is outside range of Blob.

findBefore

protected org.sakaiproject.util.java.BlobNode findBefore(org.sakaiproject.util.java.BlobNode target)
Finds the node before the given node. This is the one whose next pointer is the given node.

Returns:
the node before the supplied node or null if the given node is the head node.
Throws:
NoSuchElementException - if the node is not found in the list.

beginEnumeration

protected void beginEnumeration(int pos)
Sets up an enumeration of the bytes of the Blob starting from a particular point.

Parameters:
pos - The location from which to begin enumerating bytes.
Throws:
IndexOutOfBoundsException - If pos and len are outside range of Blob.

hasMoreBytes

protected boolean hasMoreBytes()
Returns 'true' if the Blob has more bytes, 'false' if empty.


nextByte

protected byte nextByte()
Returns the next byte in the Blob.

Throws:
NoSuchElementException - If there are no more bytes in the current enumeration

writeObject

protected void writeObject(ObjectOutputStream out)
                    throws IOException
A specialized object write routine. This is because java gets a stack overflow error when trying to write the linked list. Damn!

Throws:
IOException

readObject

protected void readObject(ObjectInputStream in)
                   throws IOException,
                          ClassNotFoundException
A specialized object read routine.

Throws:
IOException
ClassNotFoundException