de.weltraumschaf.freemarkerdown.PreProcessor Maven / Gradle / Ivy

Go to download
/*
 *  LICENSE
 *
 * "THE BEER-WARE LICENSE" (Revision 43):
 * "Sven Strittmatter"  wrote this file.
 * As long as you retain this notice you can do whatever you want with
 * this stuff. If we meet some day, and you think this stuff is worth it,
 * you can buy me a non alcohol-free beer in return.
 *
 * Copyright (C) 2012 "Sven Strittmatter" 
 */
package de.weltraumschaf.freemarkerdown;

import java.util.Collection;
import net.jcip.annotations.NotThreadSafe;

/**
 * A pre processor is invoked for each instruction it is registered for.
 * 
 * Example: A preprocessor which has the {@link #getTarget() target} {@code "foo"} will be invoked for all
 * instructions introduced by {@code }. So if a template with this content is rendered:
 * 
 *  * Lorem ipsum dolor sit amet
 * <?foo some instructions ?>
 * consetetur sadipscing elitr
 * <?foo something else ?>
 * sed diam nonumy eirmod tempor
 * 
 * 
 * The preprocessor will {@link #process(java.lang.String) receive} two strings:
 * 
 * 
 * {@code " some instructions "}
 * {@code " something else "}
 * 
 * 
 * The whole processing instruction will be replaced by the return value of the processor. So if the pre processor
 * here in the example will return always the string {@code "FOO"} the result will be:
 * 
 *  * Lorem ipsum dolor sit amet
 * FOO
 * consetetur sadipscing elitr
 * FOO
 * sed diam nonumy eirmod tempor
 * 
 * 
 * See this Wikipedia article for more informations
 * about processing instructions.
 * 
 *
 * @since 1.0.0
 * @author Sven Strittmatter 
 */
@NotThreadSafe
public interface PreProcessor {

    /**
     * Processes the given input string.
     * 
     * Each invocation of this method clears previous {@link #getWarnings() warnings}.
     * 
     *
     * @param input must not be {@code null}
     * @return never {@code null}
     */
    String process(String input);

    /**
     * Get the target name of the processor.
     * 
     * If you want to process instructions introduced with {@code 
     *
     * @return never {@code null}, never empty
     */
    String getTarget();

    /**
     * Whether there were some strange things encountered during processing.
     *
     * @return {@code true} if there were errors, else {@code false}
     */
    boolean hasWarnings();

    /**
     * Returns the warning messages collected during strange things occurred while processing the input.
     * 

     * If there were {@link #hasWarnings() no warnings} from the last {@link #process(java.lang.String) processing}
     * this method returns an empty collection.
     * 
     * 
     * This method only returns the warnings from the last call to {@link #process(java.lang.String)}. If you want
     * to collect warnings from various invocations you must save them away.
     * 
     *
     * @return never {@code null}, unmodifiable
     */
    Collection getWarnings();

}