Class VarlenaWrapper.Verifier
- Direct Known Subclasses:
VarlenaWrapper.Verifier.Base
,VarlenaWrapper.Verifier.NoOp
- Enclosing interface:
VarlenaWrapper
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
Modifier and TypeClassDescriptionstatic class
Verifier to be extended to verify byte streams for specific types.static final class
A Verifier that accepts any content, cheaply. -
Method Summary
Modifier and TypeMethodDescriptionfinal Void
call()
void
cancel()
Cancel this verifier.void
finish()
Wait for the verify task and rethrow any exception it might have thrown.schedule()
Set up theverify
method to be executed in another thread.void
update
(InputStream is) Send the nextInputStream
of content to be verified.void
update
(org.postgresql.pljava.internal.VarlenaWrapper.Output.State state, ByteBuffer bb) Convenience method that callsflip()
on a byte buffer, wraps it in aBufferWrapper
, and passes it toupdate(java.io.InputStream)
.protected void
verify
(InputStream is)
-
Method Details
-
verify
- Throws:
Exception
-
call
-
schedule
Set up theverify
method to be executed in another thread.- Returns:
- This
Verifier
object.
-
update
Send the nextInputStream
of content to be verified.It is assumed, but not checked here, that any
InputStream
supplied to this method supportsmark
andreset
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 callsflip()
on a byte buffer, wraps it in aBufferWrapper
, and passes it toupdate(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
Cancel this verifier.- Throws:
SQLException
-
finish
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.
-