javax.mvc.engine.ViewEngine Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of javax.mvc-api Show documentation
MVC ${project.version} API
The newest version!
/*
 * Copyright © 2017 Ivar Grimstad ([email protected])
 *
 * 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 javax.mvc.engine;

/**
 * View engines are responsible for processing views and are discovered
 * using CDI. Implementations must inject all instances of this interface,
 * and process a view as follows:
 * 

 *     Gather the set of candidate view engines by calling {@link #supports(String)}
 *     and discarding engines that return false.
 *     Sort the resulting set of candidates using priorities. View engines
 *     can be decorated with {@link javax.annotation.Priority} to indicate
 *     their priority; otherwise the priority is assumed to be {@link Priorities#DEFAULT}.
 *     If more than one candidate is available, choose one in an
 *     implementation-defined manner.
 *     Fire a {@link javax.mvc.event.BeforeProcessViewEvent} event.
 *     Call method {@link #processView(ViewEngineContext)} to process view.
 *     Fire a {@link javax.mvc.event.AfterProcessViewEvent} event.
 * 
 * The default view engines for JSPs and Facelets use file extensions to determine
 * support. Namely, the default JSP view engine supports views with extensions jsp
 * and jspx, and the one for Facelets supports views with extension
 * xhtml.
 *
 * @author Santiago Pericas-Geertsen
 * @see javax.annotation.Priority
 * @see javax.mvc.event.BeforeProcessViewEvent
 * @since 1.0
 */
@SuppressWarnings("unused")
public interface ViewEngine {

    /**
     * Name of property that can be set in an application's {@link javax.ws.rs.core.Configuration}
     * to override the root location for views in an archive.
     *
     * @see javax.ws.rs.core.Application#getProperties()
     */
    String VIEW_FOLDER = "javax.mvc.engine.ViewEngine.viewFolder";

    /**
     * Default value for property {@link #VIEW_FOLDER}.
     */
    String DEFAULT_VIEW_FOLDER = "/WEB-INF/views/";

    /**
     * Returns true if this engine can process the view or false
     * otherwise.
     *
     * @param view the view.
     * @return outcome of supports test.
     */
    boolean supports(String view);

    /**
     * Process a view given a {@link javax.mvc.engine.ViewEngineContext}. Processing
     * a view involves merging the model and template data and writing
     * the result to an output stream.
     *
     * Following the Java EE threading model, the underlying view engine implementation
     * must support this method being called by different threads. Any resources allocated
     * during view processing must be released before the method returns.
     *
     * @param context the context needed for processing.
     * @throws ViewEngineException if an error occurs during processing.
     */
    void processView(ViewEngineContext context) throws ViewEngineException;
}