Package org.apache.tika.digest

Class DigestSink

java.lang.Object

java.io.OutputStream

org.apache.tika.digest.DigestSink

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public abstract class DigestSink
extends OutputStream

A sink returned by Digester.digestSink(org.apache.tika.metadata.Metadata, org.apache.tika.parser.ParseContext): bytes written to it are digested, and the value(s) reach the metadata only if the producer calls commit().

Commit is explicit because the alternative -- publish on close unless something remembered to cancel -- makes every unanticipated exit (a checked exception, an Error, a producer that closes the sink itself) publish a digest of whatever bytes happened to arrive. A digest of a partial write is worse than no digest: it is wrong, and it is stably wrong, so every failure of the same shape produces the same plausible value.

Contract:

• Write the content, then commit(), then close() -- close in a finally or via try-with-resources.
• close() releases resources either way, and publishes only if commit() was called first. It is idempotent.
• commit() after close() throws IllegalStateException: the chance to publish is gone, and failing loudly beats a silently missing digest.
• Writing after close() throws IOException.
• All methods must be called from the producing thread.

Constructor Summary

Constructors

Constructor	Description
DigestSink()

Method Summary

Modifier and Type	Method	Description
final void	close()
final void	commit()	Marks the content complete, so close() publishes it.
protected final void	ensureOpen()	For subclasses' write methods.
protected abstract void	finish(boolean publish)	Called once, from the first close().

Methods inherited from class java.io.OutputStream

flush, nullOutputStream, write, write, write

Methods inherited from class java.lang.Object

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

Constructor Details

DigestSink

public DigestSink()

Method Details

commit

public final void commit()

Marks the content complete, so close() publishes it. Idempotent.

Throws:

IllegalStateException - if this sink is already closed

close

public final void close()
                 throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Overrides:

close in class OutputStream

Throws:

IOException

finish

protected abstract void finish(boolean publish)
                        throws IOException

Called once, from the first close(). Release resources either way; set the metadata only when publish is true.

Throws:

IOException

ensureOpen

protected final void ensureOpen()
                         throws IOException

For subclasses' write methods.

Throws:

IOException