org.thymeleaf.IThrottledTemplateProcessor Maven / Gradle / Ivy
Show all versions of thymeleaf Show documentation
/*
* =============================================================================
*
* Copyright (c) 2011-2018, The THYMELEAF team (http://www.thymeleaf.org)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* =============================================================================
*/
package org.thymeleaf;
import java.io.OutputStream;
import java.io.Writer;
import java.nio.charset.Charset;
/**
*
* Interface defining operations that can regulate the pace at which the template engine will process a
* template (a.k.a. engine throttling). Objects implementing this interface are returned by
* the {@code processThrottled(...)} methods at {@link ITemplateEngine}.
*
*
* When the processing of a template is throttled the client classes can tell the engine how much output
* they are prepared to handle by calling any of the {@code process(int,...)} methods. As a response to this,
* the engine will process only the part of the template enough to write at most so many chars
* or bytes as specified at the {@code processThrottled(...)} call. Output will be written to a {@link Writer}
* in the form of chars, or to an {@link OutputStream} in the form of bytes.
*
*
* Once the desired amount of output has been written, the engine stops where it is with minimum
* or no pending output caching, and returns control to the caller, so that the client can
* process output and prepare for a subsequent call. Note that this whole process is
* single-threaded.
*
*
* Among other scenarios, this should allow Thymeleaf to be efficiently integrated as a
* back-pressure-driven cold observable in a reactive architecture.
*
*
* @author Daniel Fernández
*
* @since 3.0.0
*
*/
public interface IThrottledTemplateProcessor {
/**
*
* Returns an identifier for this processor that should enable the tracing of its executions.
*
*
* Given throttled processors are often used in reactive environments, in which different executions
* of a throttled processor might be performed by different threads (in a non-interleaved manner), this
* identifier should help identifying at the log trace the specific processor being executed independently
* of the thread ID.
*
*
* Though it is not completely required that the identifier returned by this method is unique by
* construction, it should be unique enough to be of practical use as an identifier.
*
*
* @return the identifier for this processor object.
*
* @since 3.0.3
*/
public String getProcessorIdentifier();
/**
*
* Return the {@link TemplateSpec} this throttled template processor object is acting on.
*
*
* @return the template spec.
*
* @since 3.0.3
*/
public TemplateSpec getTemplateSpec();
/**
*
* Checks whether the processing of the template has already finished.
*
*
* NOTE Implementations of this method must be thread-safe as, even if executions
* of the throttled processor (calls to {@code process(...)} methods) should never happen concurrently,
* determining whether a throttled processor has finished or not can happen concurrently from different
* threads as a way of short-cutting the execution of the processor (and avoid excessive consumption of
* upstream data, for example).
*
*
* @return true if the template has already been fully processed, false if not.
*/
public boolean isFinished();
/**
*
* Process the whole template (all parts remaining), with no limit in the amount of chars written to output.
*
* @param writer the writer output should be written to.
* @return the amount of bytes written to output.
*/
public int processAll(final Writer writer);
/**
*
* Process the whole template (all parts remaining), with no limit in the amount of bytes written to output.
*
* @param outputStream the output stream output should be written to.
* @param charset the charset to be used for encoding the written output into bytes.
* @return the amount of bytes written to output.
*/
public int processAll(final OutputStream outputStream, final Charset charset);
/**
*
* Process the template until at most the specified amount of chars has been written to output, then return control.
*
*
* @param maxOutputInChars the maximum amount of chars that the engine is allowed to output. A number < 0 or
* {@link Integer#MAX_VALUE} will mean "no limit".
* @param writer the writer output should be written to.
* @return the amount of bytes written to output.
*/
public int process(final int maxOutputInChars, final Writer writer);
/**
*
* Process the template until at most the specified amount of bytes has been written to output, then return control.
*
*
* @param maxOutputInBytes the maximum amount of bytes that the engine is allowed to output. A number < 0 or
* {@link Integer#MAX_VALUE} will mean "no limit".
* @param outputStream the output stream output should be written to.
* @param charset the charset to be used for encoding the written output into bytes.
* @return the amount of bytes written to output.
*/
public int process(final int maxOutputInBytes, final OutputStream outputStream, final Charset charset);
}