Interface SqlBlob

  • 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 an Operation that will release the temporary resources associated with this SqlBlob.
      default java.util.concurrent.CompletionStage<java.lang.Long> getPosition()
      Get the position of this SqlBlob.
      Operation<java.lang.Long> getPositionOperation()
      Return a Operation that fetches the position of this SqlBlob.
      java.nio.channels.AsynchronousByteChannel getReadChannel()
      Return a Channel that can be used to read bytes from the SqlBlob beginning at the position.
      java.nio.channels.AsynchronousByteChannel getWriteChannel()
      Return a Channel that can be used to write bytes to this SqlBlob beginning at the position.
      default java.util.concurrent.CompletionStage<java.lang.Long> length()
      Get the length of this SqlBlob.
      Operation<java.lang.Long> lengthOperation()
      Return a Operation that fetches the length of this SqlBlob.
      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 an Operation 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 a Operation 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 this SqlBlob.
      Operation<java.lang.Long> setPositionOperation​(long offset)
      Return a Operation that sets the position of this SqlBlob.
      default SqlBlob trim()
      Truncate this SqlBlob so that the current position is the end of the SqlBlob.
      Operation<java.lang.Long> trimOperation()
      Return a Operation that truncates this SqlBlob so that the current position is the end of the SqlBlob.
    • Method Detail

      • closeOperation

        Operation<java.lang.Void> closeOperation()
        Return an Operation that will release the temporary resources associated with this SqlBlob.
        Returns:
        an Operation that will release the temporary resources associated with this SqlBlob.
      • close

        default void close()
        Specified by:
        close in interface java.lang.AutoCloseable
      • getPositionOperation

        Operation<java.lang.Long> getPositionOperation()
        Return a Operation that fetches the position of this SqlBlob. The position is 1-based. Position 0 is immediately before the first byte in the SqlBlob. Position 1 is the first byte in the SqlBlob, etc. Position length() is the last byte in the SqlBlob. Position is between 0 and length + 1.
        Returns:
        a Operation that returns the position of this SqlBlob
        Throws:
        java.lang.IllegalStateException - if the Session that created this SqlBlob is closed.
      • getPosition

        default java.util.concurrent.CompletionStage<java.lang.Long> getPosition()
        Get the position of this SqlBlob. The position is 1-based. Position 0 is immediately before the first byte in the SqlBlob. Position 1 is the first byte in the SqlBlob, etc. Position length() is the last byte in the SqlBlob. 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 the Session that created this SqlBlob is closed.
      • lengthOperation

        Operation<java.lang.Long> lengthOperation()
        Return a Operation that fetches the length of this SqlBlob.
        Returns:
        a Operation that returns the length of this SqlBlob
        Throws:
        java.lang.IllegalStateException - if the Session that created this SqlBlob is closed.
      • length

        default java.util.concurrent.CompletionStage<java.lang.Long> length()
        Get the length of this SqlBlob.
        Returns:
        a future which value is the number of bytes in this SqlBlob
        Throws:
        java.lang.IllegalStateException - if the Session that created this SqlBlob is closed.
      • setPositionOperation

        Operation<java.lang.Long> setPositionOperation​(long offset)
        Return a Operation that sets the position of this SqlBlob. If offset exceeds the length of this SqlBlob set position to the length + 1 of this SqlBlob, ie one past the last byte.
        Parameters:
        offset - a non-negative number
        Returns:
        a Operation that sets the position of this SqlBlob
        Throws:
        java.lang.IllegalArgumentException - if offset is less than 0
        java.lang.IllegalStateException - if the Session that created this SqlBlob is closed.
      • setPosition

        default SqlBlob setPosition​(long offset)
        Set the position of this SqlBlob. If offset exceeds the length of this SqlBlob set position to the length + 1 of this SqlBlob, 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 0
        java.lang.IllegalStateException - if the Session that created this SqlBlob is closed.
      • locateOperation

        Operation<java.lang.Long> locateOperation​(SqlBlob target)
        Return a Operation 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 - a SqlBlob created by the same Session containing the byte sequence to search for
        Returns:
        a Operation that locates target in this SqlBlob
        Throws:
        java.lang.IllegalArgumentException - if target was created by some other Session
        java.lang.IllegalStateException - if the Session that created this SqlBlob 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.
        Parameters:
        target - the byte sequence to search for
        Returns:
        this SqlBlob
        Throws:
        java.lang.IllegalArgumentException - if target was created by some other Session
        java.lang.IllegalStateException - if the Session that created this SqlBlob is closed
      • locateOperation

        Operation<java.lang.Long> locateOperation​(byte[] target)
        Return an Operation 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 - the byte sequence to search for. Not null. Captured.
        Returns:
        a Operation that locates target in this SqlBlob
        Throws:
        java.lang.IllegalStateException - if the Session that created this SqlBlob is closed.
      • 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 the Session that created this SqlBlob is closed.
      • trimOperation

        Operation<java.lang.Long> trimOperation()
        Return a Operation that truncates this SqlBlob so that the current position is the end of the SqlBlob. If the position is N, then after trim() the length is N - 1. The position is still N. This will fail if position is 0.
        Returns:
        a Operation that trims the length of this SqlBlob
        Throws:
        java.lang.IllegalStateException - if the Session that created this SqlBlob is closed or position is 0.
      • trim

        default SqlBlob trim()
        Truncate this SqlBlob so that the current position is the end of the SqlBlob. If the position is N, then after trim() 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 the Session that created this SqlBlob is closed or position is 0.
      • getReadChannel

        java.nio.channels.AsynchronousByteChannel getReadChannel()
        Return a Channel that can be used to read bytes from the SqlBlob beginning at the position. Reading bytes from the returned Channel advances the position. Each call to a read method that fetches bytes from the server creates and submits a virtual Operation to fetch those bytes. This virtual Operation is executed in sequence with other Operations and may be skipped if an error occurs.
        Returns:
        a read-only byte Channel beginning at the position.
        Throws:
        java.lang.IllegalStateException - if the Session that created this SqlBlob is closed.
      • getWriteChannel

        java.nio.channels.AsynchronousByteChannel getWriteChannel()
        Return a Channel that can be used to write bytes to this SqlBlob beginning at the position. Bytes written overwrite bytes already in the SqlBlob. Writing bytes to the returned Channel advances the position. Each call to a write method that flushes bytes to the server creates and submits a virtual Operation to flush those bytes. This virtual Operation is executed in sequence with other Operations and may be skipped if an error occurs. ISSUE: Can the app read bytes from a write Channel? If so then maybe remove getReadChannel() and add a read-only flag to this method, renamed getChannel.
        Returns:
        a writable byte Channel beginning at the position.
        Throws:
        java.lang.IllegalStateException - if the Session that created this SqlBlob is closed.