Package org.thymeleaf

Interface IThrottledTemplateProcessor

  • All Known Implementing Classes:
    ThrottledTemplateProcessor
    public interface IThrottledTemplateProcessor

    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 processThrottled(...) methods at 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 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 processThrottled(...) call. Output will be written to a Writer in the form of chars, or to an 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.

    Since:
    3.0.0
    Author:
    Daniel Fernández

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      String getProcessorIdentifier()
      Returns an identifier for this processor that should enable the tracing of its executions.
      TemplateSpec getTemplateSpec()
      Return the TemplateSpec this throttled template processor object is acting on.
      boolean isFinished()
      Checks whether the processing of the template has already finished.
      int process​(int maxOutputInBytes, OutputStream outputStream, Charset charset)
      Process the template until at most the specified amount of bytes has been written to output, then return control.
      int process​(int maxOutputInChars, Writer writer)
      Process the template until at most the specified amount of chars has been written to output, then return control.
      int processAll​(OutputStream outputStream, Charset charset)
      Process the whole template (all parts remaining), with no limit in the amount of bytes written to output.
      int processAll​(Writer writer)
      Process the whole template (all parts remaining), with no limit in the amount of chars written to output.

    • Method Detail

      • getProcessorIdentifier

        String getProcessorIdentifier()

        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.

        Returns:
        the identifier for this processor object.
        Since:
        3.0.3

      • getTemplateSpec

        TemplateSpec getTemplateSpec()

        Return the TemplateSpec this throttled template processor object is acting on.

        Returns:
        the template spec.
        Since:
        3.0.3

      • isFinished

        boolean isFinished()

        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 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).

        Returns:
        true if the template has already been fully processed, false if not.

      • processAll

        int processAll​(Writer writer)

        Process the whole template (all parts remaining), with no limit in the amount of chars written to output.

        Parameters:
        writer - the writer output should be written to.
        Returns:
        the amount of bytes written to output.

      • processAll

        int processAll​(OutputStream outputStream,
               Charset charset)

        Process the whole template (all parts remaining), with no limit in the amount of bytes written to output.

        Parameters:
        outputStream - the output stream output should be written to.
        charset - the charset to be used for encoding the written output into bytes.
        Returns:
        the amount of bytes written to output.

      • process

        int process​(int maxOutputInChars,
            Writer writer)

        Process the template until at most the specified amount of chars has been written to output, then return control.

        Parameters:
        maxOutputInChars - the maximum amount of chars that the engine is allowed to output. A number < 0 or Integer.MAX_VALUE will mean "no limit".
        writer - the writer output should be written to.
        Returns:
        the amount of bytes written to output.

      • process

        int process​(int maxOutputInBytes,
            OutputStream outputStream,
            Charset charset)

        Process the template until at most the specified amount of bytes has been written to output, then return control.

        Parameters:
        maxOutputInBytes - the maximum amount of bytes that the engine is allowed to output. A number < 0 or Integer.MAX_VALUE will mean "no limit".
        outputStream - the output stream output should be written to.
        charset - the charset to be used for encoding the written output into bytes.
        Returns:
        the amount of bytes written to output.