All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.thymeleaf.templateresource.ITemplateResource Maven / Gradle / Ivy

Go to download

Modern server-side Java template engine for both web and standalone environments

There is a newer version: 3.1.2.RELEASE
Show newest version
/*
 * =============================================================================
 * 
 *   Copyright (c) 2011-2016, 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.templateresource;

import java.io.IOException;
import java.io.Reader;

/**
 * 

* Interface implemented by all Template Resource instances. *

*

* Template resources are created and returned by Template Resolvers * ({@link org.thymeleaf.templateresolver.ITemplateResolver}) and represent the real resource * that contains the template contents, but do not necessarily contain these contents themselves. *

*

* Most usually, template resources are used to obtain a {@link Reader} on the template contents, * abstracting the real location of those contents. *

*

* Note that the existence of a template resource object does not imply the existence of the resource * it represents. In order to check whether a resource really exists or not, the {@link #exists()} method * can be called. Some implementations of {@link org.thymeleaf.templateresolver.ITemplateResolver} might * in fact do so, but note that this can result in a loss of performance in some scenarios due to a double * access to a resource that might be remote (an HTTP URL, for example): one access for checking existence, * and another access for creating the {@link Reader} to be returned by {@link #reader()}. *

*

* Note that implementations of these interface might not be thread-safe. *

* * @author Daniel Fernández * * @see org.thymeleaf.templateresolver.ITemplateResolver * @see org.thymeleaf.templateresolver.TemplateResolution * @see ClassLoaderTemplateResource * @see FileTemplateResource * @see ServletContextTemplateResource * @see StringTemplateResource * @see UrlTemplateResource * * @since 3.0.0 * */ public interface ITemplateResource { /** *

* Returns a String describing the resource. *

*

* Note this should not be taken for a valid resource name, as depending on the implementation * it could be too verbose/descriptive or not unique enough to be used for identification purposes. *

* * @return the resource description. Should never return null. */ public String getDescription(); /** *

* Returns the base name of a resource. *

*

* The base name is aimed at creating derivative names from the name of the resource, usually from * the deepest level of the resource path. *

*

* For example, a file resource located at /home/user/template/main.html should return * main as its base name, so that names like main.properties, * main.th.xml or similar can be derived, and afterwards resolved using {@link #relative(String)}. *

* * @return the base name, or null if it cannot be computed for the specific type of resource. */ public String getBaseName(); /** *

* Determines whether the resource represented by this object really exists or not. *

*

* Note that, depending on the implementation, this might mean actually access the resource, and such * operation could have a cost in performance in some scenarios (e.g. a resource representing a * remote URL). *

*

* This mechanism will be used by Template Resolvers extending from * {@link org.thymeleaf.templateresolver.AbstractTemplateResolver} for checking real resource existence * if the {@link org.thymeleaf.templateresolver.AbstractTemplateResolver#setCheckExistence(boolean)} flag * is set to true. *

* * @return true if the resource exists, false if not. */ public boolean exists(); /** *

* Returns a {@link Reader} that can be used for consuming the template contents. *

*

* Most implementations of this interface will require specifying a character encoding * during construction, so that this readers are correctly able to decode their underlying input streams. *

*

* Note this readers should be closed after being fully consumed, just like any other resources. *

* * @return a {@link Reader} on the template contents. Should never return null. * @throws IOException if an input/output exception happens or if the resource does not exist (e.g. * {@link java.io.FileNotFoundException}). */ public Reader reader() throws IOException; /** *

* Creates another {@link ITemplateResource}, usually of the same implementation class, for a resource * living in a location relative to the current object's. *

*

* Note some {@link ITemplateResource} implementations might not support this feature. *

* * @param relativeLocation the location of the resource we want to obtain, relative to the current one. Required. * @return the relative resource. Should never return null. */ public ITemplateResource relative(final String relativeLocation); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy