Module org.postgresql.pljava.internal

Package org.postgresql.pljava.internal

Class VarlenaWrapper.Verifier

java.lang.Object

org.postgresql.pljava.internal.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	VarlenaWrapper.Verifier.Base	Verifier to be extended to verify byte streams for specific types.
static final class	VarlenaWrapper.Verifier.NoOp	A Verifier that accepts any content, cheaply.

Method Summary

Modifier and Type	Method	Description
final Void	call()
void	cancel()	Cancel this verifier.
void	finish()	Wait for the verify task and rethrow any exception it might have thrown.
VarlenaWrapper.Verifier	schedule()	Set up the verify method to be executed in another thread.
void	update(InputStream is)	Send the next InputStream of content to be verified.
void	update(org.postgresql.pljava.internal.VarlenaWrapper.Output.State state, ByteBuffer bb)	Convenience method that calls flip() on a byte buffer, wraps it in a BufferWrapper, and passes it to update(java.io.InputStream).
protected void	verify(InputStream is)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

verify

protected void verify(InputStream is)
               throws Exception

Throws:

Exception

call

public final Void call()
                throws Exception

Specified by:

call in interface Callable<Void>

Throws:

Exception

schedule

public VarlenaWrapper.Verifier schedule()

Set up the verify method to be executed in another thread.

Returns:

This Verifier object.

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.

cancel

public void cancel()
            throws SQLException

Cancel this verifier.

Throws:

SQLException

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.