Class VarlenaWrapper.Verifier

  • All Implemented Interfaces:
    Callable<Void>
    Direct Known Subclasses:
    VarlenaWrapper.Verifier.Base, VarlenaWrapper.Verifier.NoOp
    Enclosing interface:
    VarlenaWrapper

    public abstract static class VarlenaWrapper.Verifier
    extends Object
    implements Callable<Void>
    A Verifier verifies the proper form of content written to a VarlenaWrapper.Output.

    This is necessary only when the correctness of the written stream may be doubtful, as when an API spec requires exposing a method for client code to write arbitrary bytes. If a type implementation exposes only type-appropriate operations to client code, and always controls the byte stream written to the varlena, the NoOp verifier can be used.

    Verifier itself cannot be instantiated or extended, except by its two immediate subclasses, NoOp and Base. Type-specific verifiers must extend Base. Exactly one instance of NoOp, NoOp.INSTANCE, exists.

    A type-specific verifier must supply a verify(java.io.InputStream) method that reads its input stream argument (which may be assumed to support mark and reset efficiently), and complete normally if the full stream is a complete and well-formed representation of the type. Otherwise, it must throw an exception.

    In use, a verifier is instantiated and schedule()d, which sets the verify method running in a separate thread. The verify method must not interact with PostgreSQL. The varlena wrapper code then passes buffers to it via update() as they are filled. A final call to finish(), in the thread interacting with PostgreSQL, waits for the verify task to complete and then rethrows the exception, if it threw one. It is possible to cancel() a Verifier.

    As an optimization, all those methods are no-ops in the NoOp class; no other thread is used, and no work is done. The Base class, unextended, also serves as a verifier that accepts anything, but goes through all the motions to do it.

    • Method Detail

      • update

        public void update​(InputStream is)
                    throws SQLException
        Send the next InputStream of content to be verified.

        It is assumed, but not checked here, that any InputStream supplied to this method supports mark and reset efficiently.

        If the verifier has already thrown an exception, it will be rethrown here in the current thread.

        Parameters:
        is - InputStream representing the next range of bytes to be verified.
        Throws:
        SQLException - if a verification error has already been detected, the verifier has been cancelled, etc.
      • update

        public void update​(org.postgresql.pljava.internal.VarlenaWrapper.Output.State state,
                           ByteBuffer bb)
                    throws SQLException
        Convenience method that calls flip() on a byte buffer, wraps it in a BufferWrapper, and passes it to update(java.io.InputStream).

        Note that the NoOp version of this method does none of that; in particular, the byte buffer will not have been flipped. This should not be a problem, as the thread passing the buffer to this method had better make no further use of it anyway.

        Parameters:
        state - The state object protecting the native memory.
        bb - Byte buffer containing next range of content to verify.
        Throws:
        SQLException - if a verification error has already been detected, the verifier has been cancelled, etc.
      • finish

        public void finish()
                    throws SQLException
        Wait for the verify task and rethrow any exception it might have thrown.
        Throws:
        SQLException - any exception thrown by the verify method, or for unexpected conditions such as interruption while waiting.