org.thymeleaf.context.IEngineContext 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.context;
import java.util.List;
import java.util.Map;
import org.thymeleaf.engine.TemplateData;
import org.thymeleaf.inline.IInliner;
import org.thymeleaf.model.IProcessableElementTag;
/**
*
* Mostly-internal interface implemented by all classes containing the context required for
* template processing inside the engine itself.
*
*
* This interface extends {@link ITemplateContext} by adding a series of methods required internally
* by the template engine for processing, which should not be used from users' code.
* Calling these methods directly from custom processors or other extensions could have undesirable
* effects on template processing.
*
*
* Contexts used during template processing by the engine are always implementations of this interface.
* If the Template Engine is called with an implementation of this {@link IEngineContext} as
* {@code context}, the same object will be used (so that users can actually provide their own implementations).
* On the other side, if the {@code context} specified to the Template Engine is not an implementation of this
* interface, an implementation of {@link IEngineContext} will be internally created by the engine, the original
* context's variables and other info will be cloned, and used instead.
*
*
* Again note that, besides providing custom-made implementations of this interface (which is a very complex
* operation, not recommended in most scenarios) there should be no reason why this interface should ever be
* used in users' code.
*
*
* @author Daniel Fernández
*
* @since 3.0.0
*
*/
public interface IEngineContext extends ITemplateContext {
/**
*
* Sets a new variable into the context.
*
*
* Depending on the context level, determined by {@link #increaseLevel()} and
* {@link #decreaseLevel()}, the variable being set might be considered a local variable
* and thus disappear from context once the context level is decreased below the
* level the variable was created at.
*
*
* @param name the name of the variable.
* @param value the value of the variable.
*/
public void setVariable(final String name, final Object value);
/**
*
* Sets several variables at a time into the context.
*
*
* Depending on the context level, determined by {@link #increaseLevel()} and
* {@link #decreaseLevel()}, the variables being set might be considered a local variables
* and thus disappear from context once the context level is decreased below the
* level the variable was created at.
*
*
* @param variables the variables to be set.
*/
public void setVariables(final Map variables);
/**
*
* Removes a variable from the context.
*
*
* Depending on the context level, determined by {@link #increaseLevel()} and
* {@link #decreaseLevel()}, this removal might be considered local variable-related
* and thus cease to happen (i.e. the variable would be recovered) once the context level
* is decreased below the level the variable was created at.
*
*
* @param name the name of the variable to be removed.
*/
public void removeVariable(final String name);
/**
*
* Set a selection target. Usually the consequence of executing a {@code th:object} processor.
*
*
* Once set, all selection expressions ({@code *{...}}) will be executed on this target.
*
*
* This selection target will have the consideration of a local variable and thus depend on
* the context level (see {@link #setVariable(String, Object)}).
*
*
* @param selectionTarget the selection target to be set.
*/
public void setSelectionTarget(final Object selectionTarget);
/**
*
* Set an inliner. Usually the consequence of executing a {@code th:inline} processor.
*
*
* This inliner will have the consideration of a local variable and thus depend on
* the context level (see {@link #setVariable(String, Object)}).
*
*
* @param inliner the inliner to be set.
*/
public void setInliner(final IInliner inliner);
/**
*
* Sets a new template metadata object ({@link TemplateData}) for the current execution point, specifying
* that the elements and nodes that are to be processed from now on (until the context level is
* decreased below the current level) originally belonged to a different template.
*
*
* A call on this method is usually the consequence of {@code th:insert} or {@code th:replace}.
*
*
* @param template the template data.
*/
public void setTemplateData(final TemplateData template);
/**
*
* Sets a new element tag ({@link IProcessableElementTag}) into the hierarchy (stack) of element tags.
*
*
* This hierarchy of element tags (added this way) can be obtained with {@link #getElementStack()}.
*
*
* @param elementTag the element tag.
*/
public void setElementTag(final IProcessableElementTag elementTag);
/**
*
* Retrieves the element stack just like {@link #getElementStack()}, but only for those elements added
* to the hierarchy above a specific context level.
*
*
* @param contextLevel the level above which we want to obtain the element stack.
* @return the element stack above a specified level.
*/
public List getElementStackAbove(final int contextLevel);
/**
*
* Checks whether a specific variable is local or not.
*
*
* This means checking if the context level at which the variable was defined was 0 or not.
*
*
* @param name the name of the variable to be checked.
* @return {@code true} if the variable is local (level > 0), {@code false} if not (level == 0).
*/
public boolean isVariableLocal(final String name);
/**
*
* Increase the context level. This is usually a consequence of the
* {@link org.thymeleaf.engine.ProcessorTemplateHandler} detecting the start of a new element
* (i.e. handling an {@link org.thymeleaf.model.IOpenElementTag} event).
*
*
* This method should only be called internally.
*
*/
public void increaseLevel();
/**
*
* Decrease the context level. This is usually a consequence of the
* {@link org.thymeleaf.engine.ProcessorTemplateHandler} detecting the closing of an element
* (i.e. handling an {@link org.thymeleaf.model.ICloseElementTag} event).
*
*
* This method should only be called internally.
*
*/
public void decreaseLevel();
/**
*
* Return the current context level.
*
*
* This method should only be called internally.
*
*
* @return the current level
*/
public int level();
}