Module org.eclipse.jetty.io

Package org.eclipse.jetty.io.content

Class ContentSourceTransformer

java.lang.Object

org.eclipse.jetty.io.content.ContentSourceTransformer

All Implemented Interfaces:

Content.Source

public abstract class ContentSourceTransformer
extends Object
implements Content.Source

This abstract Content.Source wraps another Content.Source and implementers need only to implement the transform(Content.Chunk) method, which is used to transform Content.Chunk read from the wrapped source.

The demand(Runnable) conversation is passed directly to the wrapped Content.Source, which means that transformations that may fully consume bytes read can result in a null return from Content.Source.read() even after a callback to the demand Runnable (as per spurious invocation in Content.Source.demand(Runnable).

Nested Class Summary

Nested classes/interfaces inherited from interface org.eclipse.jetty.io.Content.Source

Content.Source.Factory

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ContentSourceTransformer(Content.Source rawSource)
protected	ContentSourceTransformer(Content.Source rawSource, org.eclipse.jetty.util.thread.SerializedInvoker invoker)

Method Summary

Modifier and Type	Method	Description
void	demand(Runnable demandCallback)	Demands to invoke the given demand callback parameter when a chunk of content is available.
void	fail(Throwable failure)	Fails this content source with a last failure chunk, failing and discarding accumulated content chunks that were not yet read.
protected Content.Source	getContentSource()
Content.Chunk	read()	Reads a chunk of content.
protected abstract Content.Chunk	transform(Content.Chunk inputChunk)	Transforms the input chunk parameter into an output chunk.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.eclipse.jetty.io.Content.Source

fail, getLength, rewind

Constructor Details

ContentSourceTransformer

protected ContentSourceTransformer(Content.Source rawSource)

ContentSourceTransformer

protected ContentSourceTransformer(Content.Source rawSource,
 org.eclipse.jetty.util.thread.SerializedInvoker invoker)

Method Details

getContentSource

protected Content.Source getContentSource()

read

public Content.Chunk read()

Description copied from interface: Content.Source

Reads a chunk of content.

See how to use this method idiomatically.

The returned chunk could be:

• null, to signal that there isn't a chunk of content available
• an Content.Chunk instance with non null Content.Chunk.getFailure(), to signal that there was a failure trying to produce a chunk of content, or that the content production has been failed externally
• a Content.Chunk instance, containing the chunk of content.

Once a read returns an Content.Chunk instance with non-null Content.Chunk.getFailure() then if the failure is last further reads will continue to return the same failure chunk instance, otherwise further read() operations may return different non-failure chunks.

Once a read returns a last chunk, further reads will continue to return a last chunk (although the instance may be different).

The content reader code must ultimately arrange for a call to Retainable.release() on the returned Content.Chunk.

Additionally, prior to the ultimate call to Retainable.release(), the reader code may make additional calls to Retainable.retain(), that must ultimately be matched by a correspondent number of calls to Retainable.release().

Concurrent reads from different threads are not recommended, as they are inherently in a race condition.

Reads performed outside the invocation context of a demand callback are allowed. However, reads performed with a pending demand are inherently in a race condition (the thread that reads with the thread that invokes the demand callback).

Specified by:

read in interface Content.Source

Returns:

a chunk of content, possibly a failure instance, or null

See Also:

• Content.Source.demand(Runnable)
• Retainable

demand

public void demand(Runnable demandCallback)

Description copied from interface: Content.Source

Demands to invoke the given demand callback parameter when a chunk of content is available.

See how to use this method idiomatically.

Implementations guarantee that calls to this method are safely reentrant so that stack overflows are avoided in the case of mutual recursion between the execution of the Runnable callback and a call to this method. Invocations of the passed Runnable are serialized and a callback for demand call is not invoked until any previous demand callback has returned. Thus the Runnable should not block waiting for a callback of a future demand call.

The demand callback may be invoked spuriously: a subsequent call to Content.Source.read() may return null.

Calling this method establishes a pending demand, which is fulfilled when the demand callback is invoked.

Calling this method when there is already a pending demand results in an IllegalStateException to be thrown.

If the invocation of the demand callback throws an exception, then Content.Source.fail(Throwable) is called.

Specified by:

demand in interface Content.Source

Parameters:

demandCallback - the demand callback to invoke where there is a content chunk available

See Also:

• Content.Source.read()

fail

public void fail(Throwable failure)

Description copied from interface: Content.Source

Fails this content source with a last failure chunk, failing and discarding accumulated content chunks that were not yet read.

The failure may be notified to the content reader at a later time, when the content reader reads a content chunk, via a Content.Chunk instance with a non null Content.Chunk.getFailure().

If Content.Source.read() has returned a last chunk, this is a no operation.

Typical failure: the content being aborted by user code, or idle timeouts.

If this method has already been called, then it is a no operation.

Specified by:

fail in interface Content.Source

Parameters:

failure - the cause of the failure

See Also:

• Content.Chunk.getFailure()

transform

protected abstract Content.Chunk transform(Content.Chunk inputChunk)

Transforms the input chunk parameter into an output chunk.

When this method produces a non-null, non-last chunk, it is subsequently invoked with a null input chunk to try to produce more output chunks from the previous input chunk. For example, a single compressed input chunk may be transformed into multiple uncompressed output chunks.

The input chunk is released as soon as this method returns, so implementations that must hold onto the input chunk must arrange to call Retainable.retain() and its correspondent Retainable.release().

Implementations should return an Content.Chunk with non-null Content.Chunk.getFailure() in case of transformation errors.

Exceptions thrown by this method are equivalent to returning an error chunk.

Implementations of this method may return:

• null, if more input chunks are necessary to produce an output chunk
• the inputChunk itself, typically in case of non-null Content.Chunk.getFailure(), or when no transformation is required
• a new Content.Chunk derived from inputChunk.

Parameters:

inputChunk - a chunk read from the wrapped Content.Source

Returns:

a transformed chunk or null