-
- All Superinterfaces:
java.lang.AutoCloseable
public interface SqlBlob extends java.lang.AutoCloseable
A reference to a BINARY LARGE OBJECT in the attached database.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default void
close()
Operation<java.lang.Void>
closeOperation()
Return anOperation
that will release the temporary resources associated with thisSqlBlob
.default java.util.concurrent.CompletionStage<java.lang.Long>
getPosition()
Get the position of thisSqlBlob
.Operation<java.lang.Long>
getPositionOperation()
Return aOperation
that fetches the position of thisSqlBlob
.java.nio.channels.AsynchronousByteChannel
getReadChannel()
Return aChannel
that can be used to read bytes from theSqlBlob
beginning at the position.java.nio.channels.AsynchronousByteChannel
getWriteChannel()
Return aChannel
that can be used to write bytes to thisSqlBlob
beginning at the position.default java.util.concurrent.CompletionStage<java.lang.Long>
length()
Get the length of thisSqlBlob
.Operation<java.lang.Long>
lengthOperation()
Return aOperation
that fetches the length of thisSqlBlob
.default SqlBlob
locate(byte[] target)
Set the position to the beginning of the next occurrence of the target after the position.default SqlBlob
locate(SqlBlob target)
Set the position to the beginning of the next occurrence of the target after the position.Operation<java.lang.Long>
locateOperation(byte[] target)
Return anOperation
to set the position to the beginning of the next occurrence of the target after the position.Operation<java.lang.Long>
locateOperation(SqlBlob target)
Return aOperation
to set the position to the beginning of the next occurrence of the target after the position.default SqlBlob
setPosition(long offset)
Set the position of thisSqlBlob
.Operation<java.lang.Long>
setPositionOperation(long offset)
Return aOperation
that sets the position of thisSqlBlob
.default SqlBlob
trim()
Truncate thisSqlBlob
so that the current position is the end of theSqlBlob
.Operation<java.lang.Long>
trimOperation()
Return aOperation
that truncates thisSqlBlob
so that the current position is the end of theSqlBlob
.
-
-
-
Method Detail
-
closeOperation
Operation<java.lang.Void> closeOperation()
Return anOperation
that will release the temporary resources associated with thisSqlBlob
.- Returns:
- an
Operation
that will release the temporary resources associated with thisSqlBlob
.
-
close
default void close()
- Specified by:
close
in interfacejava.lang.AutoCloseable
-
getPositionOperation
Operation<java.lang.Long> getPositionOperation()
-
getPosition
default java.util.concurrent.CompletionStage<java.lang.Long> getPosition()
Get the position of thisSqlBlob
. The position is 1-based. Position 0 is immediately before the first byte in theSqlBlob
. Position 1 is the first byte in theSqlBlob
, etc. Positionlength()
is the last byte in theSqlBlob
. Position is between 0 and length + 1. ISSUE: Should position be 1-based as SQL seems to do or 0-based as Java does?- Returns:
- a future which value is the 1-based position of this
SqlBlob
- Throws:
java.lang.IllegalStateException
- if theSession
that created thisSqlBlob
is closed.
-
lengthOperation
Operation<java.lang.Long> lengthOperation()
Return aOperation
that fetches the length of thisSqlBlob
.
-
length
default java.util.concurrent.CompletionStage<java.lang.Long> length()
Get the length of thisSqlBlob
.- Returns:
- a future which value is the number of bytes in this
SqlBlob
- Throws:
java.lang.IllegalStateException
- if theSession
that created thisSqlBlob
is closed.
-
setPositionOperation
Operation<java.lang.Long> setPositionOperation(long offset)
Return aOperation
that sets the position of thisSqlBlob
. If offset exceeds the length of thisSqlBlob
set position to the length + 1 of thisSqlBlob
, ie one past the last byte.
-
setPosition
default SqlBlob setPosition(long offset)
Set the position of thisSqlBlob
. If offset exceeds the length of thisSqlBlob
set position to the length + 1 of thisSqlBlob
, ie one past the last byte.- Parameters:
offset
- the 1-based position to set- Returns:
- this
SqlBlob
- Throws:
java.lang.IllegalArgumentException
- if offset is less than 0java.lang.IllegalStateException
- if theSession
that created thisSqlBlob
is closed.
-
locateOperation
Operation<java.lang.Long> locateOperation(SqlBlob target)
Return aOperation
to set the position to the beginning of the next occurrence of the target after the position. If there is no such occurrence set the position to 0.- Parameters:
target
- aSqlBlob
created by the sameSession
containing the byte sequence to search for- Returns:
- a
Operation
that locatestarget
in thisSqlBlob
- Throws:
java.lang.IllegalArgumentException
- iftarget
was created by some otherSession
java.lang.IllegalStateException
- if theSession
that created thisSqlBlob
is closed.
-
locate
default SqlBlob locate(SqlBlob target)
Set the position to the beginning of the next occurrence of the target after the position. If there is no such occurrence set the position to 0.
-
locateOperation
Operation<java.lang.Long> locateOperation(byte[] target)
Return anOperation
to set the position to the beginning of the next occurrence of the target after the position. If there is no such occurrence set the position to 0.
-
locate
default SqlBlob locate(byte[] target)
Set the position to the beginning of the next occurrence of the target after the position. If there is no such occurrence set the position to 0.- Parameters:
target
- the byte sequence to search for- Returns:
- this
SqlBlob
- Throws:
java.lang.IllegalStateException
- if theSession
that created thisSqlBlob
is closed.
-
trimOperation
Operation<java.lang.Long> trimOperation()
-
trim
default SqlBlob trim()
Truncate thisSqlBlob
so that the current position is the end of theSqlBlob
. If the position is N, then aftertrim()
the length is N - 1. The position is still N. This will fail if position is 0.- Returns:
- this SqlBlob
- Throws:
java.lang.IllegalStateException
- if theSession
that created thisSqlBlob
is closed or position is 0.
-
getReadChannel
java.nio.channels.AsynchronousByteChannel getReadChannel()
Return aChannel
that can be used to read bytes from theSqlBlob
beginning at the position. Reading bytes from the returnedChannel
advances the position. Each call to a read method that fetches bytes from the server creates and submits a virtualOperation
to fetch those bytes. This virtualOperation
is executed in sequence with otherOperation
s and may be skipped if an error occurs.- Returns:
- a read-only byte
Channel
beginning at the position. - Throws:
java.lang.IllegalStateException
- if theSession
that created this SqlBlob is closed.
-
getWriteChannel
java.nio.channels.AsynchronousByteChannel getWriteChannel()
Return aChannel
that can be used to write bytes to thisSqlBlob
beginning at the position. Bytes written overwrite bytes already in theSqlBlob
. Writing bytes to the returnedChannel
advances the position. Each call to a write method that flushes bytes to the server creates and submits a virtualOperation
to flush those bytes. This virtualOperation
is executed in sequence with otherOperation
s and may be skipped if an error occurs. ISSUE: Can the app read bytes from a writeChannel
? If so then maybe removegetReadChannel()
and add a read-only flag to this method, renamedgetChannel
.- Returns:
- a writable byte
Channel
beginning at the position. - Throws:
java.lang.IllegalStateException
- if theSession
that created thisSqlBlob
is closed.
-
-