Blob object in java

Interface Blob

The representation (mapping) in the Java programming language of an SQL BLOB value. An SQL BLOB is a built-in type that stores a Binary Large Object as a column value in a row of a database table. By default drivers implement Blob using an SQL locator(BLOB) , which means that a Blob object contains a logical pointer to the SQL BLOB data rather than the data itself. A Blob object is valid for the duration of the transaction in which is was created.

Methods in the interfaces ResultSet , CallableStatement , and PreparedStatement , such as getBlob and setBlob allow a programmer to access an SQL BLOB value. The Blob interface provides methods for getting the length of an SQL BLOB (Binary Large Object) value, for materializing a BLOB value on the client, and for determining the position of a pattern of bytes within a BLOB value. In addition, this interface has methods for updating a BLOB value.

All methods on the Blob interface must be fully implemented if the JDBC driver supports the data type.

Method Summary

Returns an InputStream object that contains a partial Blob value, starting with the byte specified by pos, which is length bytes in length.

Retrieves the byte position at which the specified byte array pattern begins within the BLOB value that this Blob object represents.

Retrieves the byte position in the BLOB value designated by this Blob object at which pattern begins.

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.

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.

Method Details

length

getBytes

Retrieves all or part of the BLOB value that this Blob object represents, as an array of bytes. This byte array contains up to length consecutive bytes starting at position pos .

getBinaryStream

position

Retrieves the byte position at which the specified byte array pattern begins within the BLOB value that this Blob object represents. The search for pattern begins at position start .

position

Retrieves the byte position in the BLOB value designated by this Blob object at which pattern begins. The search begins at position start .

setBytes

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. The array of bytes will overwrite the existing bytes in the Blob object starting at the position pos . If the end of the Blob value is reached while writing the array of bytes, then the length of the Blob value will be increased to accommodate the extra bytes. Note: If the value specified for pos is greater than the length+1 of the BLOB value then the behavior is undefined. Some JDBC drivers may throw an SQLException while other drivers may support this operation.

setBytes

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. The array of bytes will overwrite the existing bytes in the Blob object starting at the position pos . If the end of the Blob value is reached while writing the array of bytes, then the length of the Blob value will be increased to accommodate the extra bytes. Note: If the value specified for pos is greater than the length+1 of the BLOB value then the behavior is undefined. Some JDBC drivers may throw an SQLException while other drivers may support this operation.

setBinaryStream

Retrieves a stream that can be used to write to the BLOB value that this Blob object represents. The stream begins at position pos . The bytes written to the stream will overwrite the existing bytes in the Blob object starting at the position pos . If the end of the Blob value is reached while writing to the stream, then the length of the Blob value will be increased to accommodate the extra bytes. Note: If the value specified for pos is greater than the length+1 of the BLOB value then the behavior is undefined. Some JDBC drivers may throw an SQLException while other drivers may support this operation.

truncate

Truncates the BLOB value that this Blob object represents to be len bytes in length. Note: If the value specified for pos is greater than the length+1 of the BLOB value then the behavior is undefined. Some JDBC drivers may throw an SQLException while other drivers may support this operation.

free

This method frees the Blob object and releases the resources that it holds. The object is invalid once the free method is called. After free has been called, any attempt to invoke a method other than free will result in an SQLException being thrown. If free is called multiple times, the subsequent calls to free are treated as a no-op.

getBinaryStream

Returns an InputStream object that contains a partial Blob value, starting with the byte specified by pos, which is length bytes in length.

Report a bug or suggest an enhancement
For further API reference and developer documentation see the Java SE Documentation, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples. Other versions.
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 1993, 2023, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
All rights reserved. Use is subject to license terms and the documentation redistribution policy.

Источник

Using Large Objects

An important feature of Blob , Clob , and NClob Java objects is that you can manipulate them without having to bring all of their data from the database server to your client computer. Some implementations represent an instance of these types with a locator (logical pointer) to the object in the database that the instance represents. Because a BLOB , CLOB , or NCLOB SQL object may be very large, the use of locators can make performance significantly faster. However, other implementations fully materialize large objects on the client computer.

If you want to bring the data of a BLOB , CLOB , or NCLOB SQL value to the client computer, use methods in the Blob , Clob , and NClob Java interfaces that are provided for this purpose. These large object type objects materialize the data of the objects they represent as a stream.

The following topics are covered:

Adding Large Object Type Object to Database

The following excerpt from ClobSample.addRowToCoffeeDescriptions adds a CLOB SQL value to the table COFFEE_DESCRIPTIONS . The Clob Java object myClob contains the contents of the file specified by fileName .

public void addRowToCoffeeDescriptions(String coffeeName, String fileName) throws SQLException < String sql = "INSERT INTO COFFEE_DESCRIPTIONS VALUES(. )"; Clob myClob = this.con.createClob(); try (PreparedStatement pstmt = this.con.prepareStatement(sql); Writer clobWriter = myClob.setCharacterStream(1);)< String str = this.readFile(fileName, clobWriter); System.out.println("Wrote the following: " + clobWriter.toString()); if (this.settings.dbms.equals("mysql")) < System.out.println("MySQL, setting String in Clob object with setString method"); myClob.setString(1, str); >System.out.println("Length of Clob: " + myClob.length()); pstmt.setString(1, coffeeName); pstmt.setClob(2, myClob); pstmt.executeUpdate(); > catch (SQLException sqlex) < JDBCTutorialUtilities.printSQLException(sqlex); >catch (Exception ex) < System.out.println("Unexpected exception: " + ex.toString()); >>

The following line creates a Clob Java object:

Clob myClob = this.con.createClob();

The following line retrieves a stream (in this case a Writer object named clobWriter ) that is used to write a stream of characters to the Clob Java object myClob . The method ClobSample.readFile writes this stream of characters; the stream is from the file specified by the String fileName . The method argument 1 indicates that the Writer object will start writing the stream of characters at the beginning of the Clob value:

Writer clobWriter = myClob.setCharacterStream(1);

The ClobSample.readFile method reads the file line-by-line specified by the file fileName and writes it to the Writer object specified by writerArg :

private String readFile(String fileName, Writer writerArg) throws IOException < try (BufferedReader br = new BufferedReader(new FileReader(fileName))) < String nextLine = ""; StringBuffer sb = new StringBuffer(); while ((nextLine = br.readLine()) != null) < System.out.println("Writing: " + nextLine); writerArg.write(nextLine); sb.append(nextLine); >// Convert the content into to a string String clobData = sb.toString(); // Return the data. return clobData; > >

The following excerpt creates a PreparedStatement object pstmt that inserts the Clob Java object myClob into COFFEE_DESCRIPTIONS :

String sql = "INSERT INTO COFFEE_DESCRIPTIONS VALUES(. )"; Clob myClob = this.con.createClob(); try (PreparedStatement pstmt = this.con.prepareStatement(sql); // . ) < // . pstmt.setString(1, coffeeName); pstmt.setClob(2, myClob); pstmt.executeUpdate(); // .

Retrieving CLOB Values

The method ClobSample.retrieveExcerpt retrieves the CLOB SQL value stored in the COF_DESC column of COFFEE_DESCRIPTIONS from the row whose column value COF_NAME is equal to the String value specified by the coffeeName parameter:

public String retrieveExcerpt(String coffeeName, int numChar) throws SQLException < String description = null; Clob myClob = null; String sql = "select COF_DESC from COFFEE_DESCRIPTIONS where COF_NAME = ?"; try (PreparedStatement pstmt = this.con.prepareStatement(sql)) < pstmt.setString(1, coffeeName); ResultSet rs = pstmt.executeQuery(); if (rs.next()) < myClob = rs.getClob(1); System.out.println("Length of retrieved Clob: " + myClob.length()); >description = myClob.getSubString(1, numChar); > catch (SQLException sqlex) < JDBCTutorialUtilities.printSQLException(sqlex); >catch (Exception ex) < System.out.println("Unexpected exception: " + ex.toString()); >return description; >

The following line retrieves the Clob Java value from the ResultSet object rs :

The following line retrieves a substring from the myClob object. The substring begins at the first character of the value of myClob and has up to the number of consecutive characters specified in numChar , where numChar is an integer.

description = myClob.getSubString(1, numChar);

Adding and Retrieving BLOB Objects

Adding and retrieving BLOB SQL objects is similar to adding and retrieving CLOB SQL objects. Use the Blob.setBinaryStream method to retrieve an OutputStream object to write the BLOB SQL value that the Blob Java object (which called the method) represents.

Releasing Resources Held by Large Objects

Blob , Clob , and NClob Java objects remain valid for at least the duration of the transaction in which they are created. This could potentially result in an application running out of resources during a long running transaction. Applications may release Blob , Clob , and NClob resources by invoking their free method.

In the following excerpt, the method Clob.free is called to release the resources held for a previously created Clob object:

Clob aClob = con.createClob(); int numWritten = aClob.setString(1, val); aClob.free();

Источник