FileDocCategorySizeDatePackage
SerialBlob.javaAPI DocJava SE 6 API18843Tue Jun 10 00:26:32 BST 2008javax.sql.rowset.serial

SerialBlob

public class SerialBlob extends Object implements Blob, Serializable, Cloneable
A serialized mapping in the Java programming language of an SQL BLOB value.

The SerialBlob class provides a constructor for creating an instance from a Blob object. Note that the Blob object should have brought the SQL BLOB value's data over to the client before a SerialBlob object is constructed from it. The data of an SQL BLOB value can be materialized on the client as an array of bytes (using the method Blob.getBytes) or as a stream of uninterpreted bytes (using the method Blob.getBinaryStream).

SerialBlob methods make it possible to make a copy of a SerialBlob object as an array of bytes or as a stream. They also make it possible to locate a given pattern of bytes or a Blob object within a SerialBlob object and to update or truncate a Blob object.

author
Jonathan Bruce

Fields Summary
private byte[]
buf
A serialized array of uninterpreted bytes representing the value of this SerialBlob object.
private Blob
blob
The internal representation of the Blob object on which this SerialBlob object is based.
private long
len
The number of bytes in this SerialBlob object's array of bytes.
private long
origLen
The orginal number of bytes in this SerialBlob object's array of bytes when it was first established.
static final long
serialVersionUID
The identifier that assists in the serialization of this SerialBlob object.
Constructors Summary
public SerialBlob(byte[] b)
Constructs a SerialBlob object that is a serialized version of the given byte array.

The new SerialBlob object is initialized with the data from the byte array, thus allowing disconnected RowSet objects to establish serialized Blob objects without touching the data source.

param
b the byte array containing the data for the Blob object to be serialized
throws
SerialException if an error occurs during serialization
throws
SQLException if a SQL errors occurs

    	
        len = b.length;                
        buf = new byte[(int)len];               
        for(int i = 0; i < len; i++) {
           buf[i] = b[i];
        }          
        origLen = len;
    
public SerialBlob(Blob blob)
Constructs a SerialBlob object that is a serialized version of the given Blob object.

The new SerialBlob object is initialized with the data from the Blob object; therefore, the Blob object should have previously brought the SQL BLOB value's data over to the client from the database. Otherwise, the new SerialBlob object will contain no data.

param
blob the Blob object from which this SerialBlob object is to be constructed; cannot be null.
throws
SerialException if an error occurs during serialization
throws
SQLException if the Blob passed to this to this constructor is a null.
see
java.sql.Blob

    
        if (blob == null) {
            throw new SQLException("Cannot instantiate a SerialBlob " +
                 "object with a null Blob object");
        }
        
        len = blob.length();                       
        buf = blob.getBytes(1, (int)len );
        this.blob = blob;
        
         //if ( len < 10240000)
         // len = 10240000;          
        origLen = len;
    
Methods Summary
public voidfree()
This method frees the Blob object and releases the resources that it holds. Blob object. The object is invalid once the free method is called. If free is called multiple times, the subsequent calls to free are treated as a no-op.

throws
SQLException if an error occurs releasing the Blob's resources
since
1.6

        throw new java.lang.UnsupportedOperationException("Not supported");
    
public java.io.InputStreamgetBinaryStream(long pos, long length)
Returns an InputStream object that contains a partial Blob value, starting with the byte specified by pos, which is length bytes in length.

param
pos the offset to the first byte of the partial value to be retrieved. The first byte in the Blob is at position 1
param
length the length in bytes of the partial value to be retrieved
return
InputStream through which the partial Blob value can be read.
throws
SQLException if pos is less than 1 or if pos is greater than the number of bytes in the Blob or if pos + length is greater than the number of bytes in the Blob
since
1.6

        throw new java.lang.UnsupportedOperationException("Not supported");
    
public java.io.InputStreamgetBinaryStream()
Returns this SerialBlob object as an input stream. Unlike the related method, setBinaryStream, a stream is produced regardless of whether the SerialBlob was created with a Blob object or a byte array.

return
a java.io.InputStream object that contains this SerialBlob object's array of bytes
throws
SerialException if an error occurs
see
#setBinaryStream

            
         InputStream stream = new ByteArrayInputStream(buf);
         return (java.io.InputStream)stream;
    
public byte[]getBytes(long pos, int length)
Copies the specified number of bytes, starting at the given position, from this SerialBlob object to another array of bytes.

Note that if the given number of bytes to be copied is larger than the length of this SerialBlob object's array of bytes, the given number will be shortened to the array's length.

param
pos the ordinal position of the first byte in this SerialBlob object to be copied; numbering starts at 1; must not be less than 1 and must be less than or equal to the length of this SerialBlob object
param
length the number of bytes to be copied
return
an array of bytes that is a copy of a region of this SerialBlob object, starting at the given position and containing the given number of consecutive bytes
throws
SerialException if the given starting position is out of bounds

        if (length > len) {
            length = (int)len;                
        }

        if (pos < 1 || length - pos < 0 ) {
            throw new SerialException("Invalid arguments: position cannot be less that 1");
        }      
        
        pos--; // correct pos to array index
      
        byte[] b = new byte[length];
        
        for (int i = 0; i < length; i++) {
            b[i] = this.buf[(int)pos];
            pos++;
        }
        return b;
    
public longlength()
Retrieves the number of bytes in this SerialBlob object's array of bytes.

return
a long indicating the length in bytes of this SerialBlob object's array of bytes
throws
SerialException if an error occurs

        return len;
    
public longposition(byte[] pattern, long start)
Returns the position in this SerialBlob object where the given pattern of bytes begins, starting the search at the specified position.

param
pattern the pattern of bytes for which to search
param
start the position of the byte in this SerialBlob object from which to begin the search; the first position is 1; must not be less than 1 nor greater than the length of this SerialBlob object
return
the position in this SerialBlob object where the given pattern begins, starting at the specified position; -1 if the pattern is not found or the given starting position is out of bounds; position numbering for the return value starts at 1
throws
SerialException if an error occurs when serializing the blob
throws
SQLException if there is an error accessing the BLOB value from the database

                
        if (start < 1 || start > len) {
            return -1;
        } 

        int pos = (int)start-1; // internally Blobs are stored as arrays. 
        int i = 0;        
        long patlen = pattern.length;                
        
        while (pos < len) {     
            if (pattern[i] == buf[pos]) {                
                if (i + 1 == patlen) {
                    return (pos + 1) - (patlen - 1);
                }
                i++; pos++; // increment pos, and i
            } else if (pattern[i] != buf[pos]) {
                pos++; // increment pos only
            }                                    
        }        
        return -1; // not found
    
public longposition(java.sql.Blob pattern, long start)
Returns the position in this SerialBlob object where the given Blob object begins, starting the search at the specified position.

param
pattern the Blob object for which to search;
param
start the position of the byte in this SerialBlob object from which to begin the search; the first position is 1; must not be less than 1 nor greater than the length of this SerialBlob object
return
the position in this SerialBlob object where the given Blob object begins, starting at the specified position; -1 if the pattern is not found or the given starting position is out of bounds; position numbering for the return value starts at 1
throws
SerialException if an error occurs when serializing the blob
throws
SQLException if there is an error accessing the BLOB value from the database

        return position(pattern.getBytes(1, (int)(pattern.length())), start);
    
public java.io.OutputStreamsetBinaryStream(long pos)
Retrieves a stream that can be used to write to the BLOB value that this Blob object represents. The stream begins at position pos. This method forwards the setBinaryStream() call to the underlying Blob in the event that this SerialBlob object is instantiated with a Blob. If this SerialBlob is instantiated with a byte array, a SerialException is thrown.

param
pos the position in the BLOB value at which to start writing
return
a java.io.OutputStream object to which data can be written
throws
SQLException if there is an error accessing the BLOB value
throws
SerialException if the SerialBlob in not instantiated with a Blob object that supports setBinaryStream()
see
#getBinaryStream

       
        if (this.blob.setBinaryStream(pos) != null) {
            return this.blob.setBinaryStream(pos);
        } else {
            throw new SerialException("Unsupported operation. SerialBlob cannot " +
                "return a writable binary stream, unless instantiated with a Blob object " +
                "that provides a setBinaryStream() implementation");
        }        
    
public intsetBytes(long pos, byte[] bytes)
Writes the given array of bytes to the BLOB value that this Blob object represents, starting at position pos, and returns the number of bytes written.

param
pos the position in the SQL BLOB value at which to start writing. The first position is 1; must not be less than 1 nor greater than the length of this SerialBlob object.
param
bytes the array of bytes to be written to the BLOB value that this Blob object represents
return
the number of bytes written
throws
SerialException if there is an error accessing the BLOB value; or if an invalid position is set; if an invalid offset value is set
throws
SQLException if there is an error accessing the BLOB value from the database
see
#getBytes

        return (setBytes(pos, bytes, 0, bytes.length));
    
public intsetBytes(long pos, byte[] bytes, int offset, int length)
Writes all or part of the given byte array to the BLOB value that this Blob object represents and returns the number of bytes written. Writing starts at position pos in the BLOB value; len bytes from the given byte array are written.

param
pos the position in the BLOB object at which to start writing. The first position is 1; must not be less than 1 nor greater than the length of this SerialBlob object.
param
bytes the array of bytes to be written to the BLOB value
param
offset the offset in the byte array at which to start reading the bytes. The first offset position is 0; must not be less than 0 nor greater than the length of the byte array
param
length the number of bytes to be written to the BLOB value from the array of bytes bytes.
return
the number of bytes written
throws
SerialException if there is an error accessing the BLOB value; if an invalid position is set; if an invalid offset value is set; if number of bytes to be written is greater than the SerialBlob length; or the combined values of the length and offset is greater than the Blob buffer
throws
SQLException if there is an error accessing the BLOB value from the database.
see
#getBytes

        
        if (offset < 0 || offset > bytes.length) {
            throw new SerialException("Invalid offset in byte array set");
        }            
        
        if (pos < 1 || pos > this.length()) {
            throw new SerialException("Invalid position in BLOB object set");
        }
                    
        if ((long)(length) > origLen) {
	    throw new SerialException("Buffer is not sufficient to hold the value");
	}    
        
        if ((length + offset) > bytes.length) {  
            throw new SerialException("Invalid OffSet. Cannot have combined offset " +
                "and length that is greater that the Blob buffer");            
        }                                       
        
        int i = 0;
        pos--; // correct to array indexing
        while ( i < length || (offset + i +1) < (bytes.length-offset) ) {
            this.buf[(int)pos + i] = bytes[offset + i ]; 
            i++;
        }
        return i;        
    
public voidtruncate(long length)
Truncates the BLOB value that this Blob object represents to be len bytes in length.

param
length the length, in bytes, to which the BLOB value that this Blob object represents should be truncated
throws
SerialException if there is an error accessing the Blob value; or the length to truncate is greater that the SerialBlob length

         
         if (length > len) {
            throw new SerialException
               ("Length more than what can be truncated");
         } else if((int)length == 0) { 
              buf = new byte[0];
              len = length;
         } else {      
              len = length;              
              buf = this.getBytes(1, (int)len);
         }