jdk-sandbox: comparison jdk/src/share/classes/javax/sql/rowset/serial/SerialBlob.java

equal deleted inserted replaced

-:a65826af2aa4
+:701d0765f75f
 * <code>SerialBlob</code> object as an array of bytes or as a stream.
 * They also make it possible to locate a given pattern of bytes or a
 * <code>Blob</code> object within a <code>SerialBlob</code> object
 * and to update or truncate a <code>Blob</code> object.
 *
+* <h4> Thread safety </h4>
+*
+* <p> A SerialBlob is not safe for use by multiple concurrent threads.  If a
+* SerialBlob is to be used by more than one thread then access to the SerialBlob
+* should be controlled by appropriate synchronization.
+*
 * @author Jonathan Bruce
 */
 public class SerialBlob implements Blob, Serializable, Cloneable {
 /**
 * @serial
 */
 private long len;
 /**
-* The orginal number of bytes in this <code>SerialBlob</code> object's
+* The original number of bytes in this <code>SerialBlob</code> object's
 * array of bytes when it was first established.
 * @serial
 */
 private long origLen;
 *            to the length of this <code>SerialBlob</code> object
 * @param length the number of bytes to be copied
 * @return an array of bytes that is a copy of a region of this
 *         <code>SerialBlob</code> 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
+* @throws SerialException if the given starting position is out of bounds;
+* if {@code free} had previously been called on this object
 */
 public byte[] getBytes(long pos, int length) throws SerialException {
+isValid();
 if (length > len) {
 length = (int)len;
 }
 if (pos < 1 || len - pos < 0 ) {
 * Retrieves the number of bytes in this <code>SerialBlob</code>
 * object's array of bytes.
 *
 * @return a <code>long</code> indicating the length in bytes of this
 *         <code>SerialBlob</code> object's array of bytes
-* @throws SerialException if an error occurs
+* @throws SerialException if an error occurs;
+* if {@code free} had previously been called on this object
 */
 public long length() throws SerialException {
+isValid();
 return len;
 }
 /**
 * Returns this <code>SerialBlob</code> object as an input stream.
 * a stream is produced regardless of whether the <code>SerialBlob</code>
 * was created with a <code>Blob</code> object or a <code>byte</code> array.
 *
 * @return a <code>java.io.InputStream</code> object that contains
 *         this <code>SerialBlob</code> object's array of bytes
-* @throws SerialException if an error occurs
+* @throws SerialException if an error occurs;
+* if {@code free} had previously been called on this object
 * @see #setBinaryStream
 */
 public java.io.InputStream getBinaryStream() throws SerialException {
-InputStream stream = new ByteArrayInputStream(buf);
+isValid();
-return stream;
+InputStream stream = new ByteArrayInputStream(buf);
+return stream;
 }
 /**
 * Returns the position in this <code>SerialBlob</code> object where
 * the given pattern of bytes begins, starting the search at the
 * @return the position in this <code>SerialBlob</code> object
 *         where the given pattern begins, starting at the specified
 *         position; <code>-1</code> if the pattern is not found
 *         or the given starting position is out of bounds; position
 *         numbering for the return value starts at <code>1</code>
-* @throws SerialException if an error occurs when serializing the blob
+* @throws SerialException if an error occurs when serializing the blob;
+* if {@code free} had previously been called on this object
 * @throws SQLException if there is an error accessing the <code>BLOB</code>
 *         value from the database
 */
 public long position(byte[] pattern, long start)
 throws SerialException, SQLException {
+isValid();
 if (start < 1 || start > len) {
 return -1;
 }
 int pos = (int)start-1; // internally Blobs are stored as arrays.
 * @return the position in this <code>SerialBlob</code> object
 *         where the given <code>Blob</code> object begins, starting
 *         at the specified position; <code>-1</code> if the pattern is
 *         not found or the given starting position is out of bounds;
 *         position numbering for the return value starts at <code>1</code>
-* @throws SerialException if an error occurs when serializing the blob
+* @throws SerialException if an error occurs when serializing the blob;
+* if {@code free} had previously been called on this object
 * @throws SQLException if there is an error accessing the <code>BLOB</code>
 *         value from the database
 */
 public long position(Blob pattern, long start)
 throws SerialException, SQLException {
+isValid();
 return position(pattern.getBytes(1, (int)(pattern.length())), start);
 }
 /**
 * Writes the given array of bytes to the <code>BLOB</code> value that
 * @param bytes the array of bytes to be written to the <code>BLOB</code>
 *        value that this <code>Blob</code> object represents
 * @return the number of bytes written
 * @throws SerialException if there is an error accessing the
 *     <code>BLOB</code> value; or if an invalid position is set; if an
-*     invalid offset value is set
+*     invalid offset value is set;
+* if {@code free} had previously been called on this object
 * @throws SQLException if there is an error accessing the <code>BLOB</code>
 *         value from the database
 * @see #getBytes
 */
 public int setBytes(long pos, byte[] bytes)
 * @return the number of bytes written
 * @throws SerialException if there is an error accessing the
 *     <code>BLOB</code> 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 <code>SerialBlob</code> length; or the combined
-*     values of the length and offset is greater than the Blob buffer
+*     values of the length and offset is greater than the Blob buffer;
+* if {@code free} had previously been called on this object
 * @throws SQLException if there is an error accessing the <code>BLOB</code>
 *         value from the database.
 * @see #getBytes
 */
 public int setBytes(long pos, byte[] bytes, int offset, int length)
 throws SerialException, SQLException {
+isValid();
 if (offset < 0 || offset > bytes.length) {
 throw new SerialException("Invalid offset in byte array set");
 }
 if (pos < 1 || pos > this.length()) {
 * @return a <code>java.io.OutputStream</code> object to which data can
 *         be written
 * @throws SQLException if there is an error accessing the
 *            <code>BLOB</code> value
 * @throws SerialException if the SerialBlob in not instantiated with a
-*     <code>Blob</code> object that supports <code>setBinaryStream()</code>
+*     <code>Blob</code> object that supports <code>setBinaryStream()</code>;
+* if {@code free} had previously been called on this object
 * @see #getBinaryStream
 */
 public java.io.OutputStream setBinaryStream(long pos)
 throws SerialException, SQLException {
+isValid();
 if (this.blob != 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 " +
 *
 * @param length the length, in bytes, to which the <code>BLOB</code>
 *        value that this <code>Blob</code> 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
+*     or the length to truncate is greater that the SerialBlob length;
+* if {@code free} had previously been called on this object
 */
 public void truncate(long length) throws SerialException {
-if (length > len) {
+isValid();
-throw new SerialException
+if (length > len) {
-("Length more than what can be truncated");
+throw new SerialException
-} else if((int)length == 0) {
+("Length more than what can be truncated");
-buf = new byte[0];
+} else if((int)length == 0) {
-len = length;
+buf = new byte[0];
-} else {
+len = length;
-len = length;
+} else {
-buf = this.getBytes(1, (int)len);
+len = length;
-}
+buf = this.getBytes(1, (int)len);
 }
+}
-/**
-* Returns an <code>InputStream</code> object that contains a partial <code>Blob</code> value,
+/**
-* starting  with the byte specified by pos, which is length bytes in length.
+* Returns an
-*
+* <code>InputStream</code> object that contains a partial
-* @param pos the offset to the first byte of the partial value to be retrieved.
+* {@code Blob} value, starting with the byte specified by pos, which is
-*  The first byte in the <code>Blob</code> is at position 1
+* length bytes in length.
+*
+* @param pos the offset to the first byte of the partial value to be
+* retrieved. The first byte in the {@code Blob} is at position 1
 * @param length the length in bytes of the partial value to be retrieved
-* @return <code>InputStream</code> through which the partial <code>Blob</code> value can be read.
+* @return
-* @throws SQLException if pos is less than 1 or if pos is greater than the number of bytes
+* <code>InputStream</code> through which the partial {@code Blob} value can
-* in the <code>Blob</code> or if pos + length is greater than the number of bytes
+* be read.
-* in the <code>Blob</code>
+* @throws SQLException if pos is less than 1 or if pos is greater than the
+* number of bytes in the {@code Blob} or if pos + length is greater than
+* the number of bytes in the {@code Blob}
+* @throws SerialException if the {@code free} method had been previously
+* called on this object
 *
 * @since 1.6
 */
-public InputStream getBinaryStream(long pos,long length) throws SQLException {
+public InputStream getBinaryStream(long pos, long length) throws SQLException {
-throw new java.lang.UnsupportedOperationException("Not supported");
+isValid();
-}
+if (pos < 1 || pos > this.length()) {
+throw new SerialException("Invalid position in BLOB object set");
+}
-/**
+if (length < 1 || length > len - pos + 1) {
-* This method frees the <code>Blob</code> object and releases the resources that it holds.
+throw new SerialException("length is < 1 or pos + length >"
-* <code>Blob</code> object. The object is invalid once the <code>free</code>
++ "total number of bytes");
-* method is called. If <code>free</code> is called multiple times, the subsequent
+}
-* calls to <code>free</code> are treated as a no-op.
+return new ByteArrayInputStream(buf, (int) pos - 1, (int) length);
-*
+}
-* @throws SQLException if an error occurs releasing
-* the Blob's resources
+/**
+* This method frees the {@code SeriableBlob} object and releases the
+* resources that it holds. The object is invalid once the {@code free}
+* method is called. <p> If {@code free} is called multiple times, the
+* subsequent calls to {@code free} are treated as a no-op. </P>
+*
+* @throws SQLException if an error occurs releasing the Blob's resources
 * @since 1.6
 */
 public void free() throws SQLException {
-throw new java.lang.UnsupportedOperationException("Not supported");
+if (buf != null) {
+buf = null;
+if (blob != null) {
+blob.free();
+}
+blob = null;
+}
 }
 /**
 * Compares this SerialBlob to the specified object.  The result is {@code
 * true} if and only if the argument is not {@code null} and is a {@code
 * @return  a clone of this SerialBlob
 */
 public Object clone() {
 try {
 SerialBlob sb = (SerialBlob) super.clone();
-sb.buf = Arrays.copyOf(buf, (int)len);
+sb.buf =  (buf != null) ? Arrays.copyOf(buf, (int)len) : null;
 sb.blob = null;
 return sb;
 } catch (CloneNotSupportedException ex) {
 // this shouldn't happen, since we are Cloneable
 throw new InternalError();
 fields.put("blob", blob instanceof Serializable ? blob : null);
 s.writeFields();
 }
 /**
-* The identifier that assists in the serialization of this <code>SerialBlob</code>
+* Check to see if this object had previously had its {@code free} method
-* object.
+* called
-*/
+*
+* @throws SerialException
+*/
+private void isValid() throws SerialException {
+if (buf == null) {
+throw new SerialException("Error: You cannot call a method on a "
++ "SerialBlob instance once free() has been called.");
+}
+}
+/**
+* The identifier that assists in the serialization of this
+* {@code SerialBlob} object.
+*/
 static final long serialVersionUID = -8144641928112860441L;
 }

changeset 14781	701d0765f75f
parent 14337	a003c6a54cb6
child 18564	f9db68ff2cbb