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

Go to download
/*
 * Copyright (c) 2015 Oracle and/or its affiliates. All rights reserved.
 * Copyright (c) 2016-2018 JSR 371 expert group and contributors
 *
 * 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;

import javax.mvc.Models;
import javax.ws.rs.container.ResourceInfo;
import javax.ws.rs.core.Configuration;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.core.UriInfo;
import java.io.OutputStream;
import java.util.Locale;

/**
 * Contextual data used by a {@link javax.mvc.engine.ViewEngine} to process a view.
 * This includes the view name, the models instance and the request and response
 * objects from the container, among other data.
 *
 * @author Santiago Pericas-Geertsen
 * @author Christian Kaltepoth
 * @see javax.mvc.engine.ViewEngine
 * @since 1.0
 */
public interface ViewEngineContext {

    /**
     * Returns the view.
     *
     * @return the view.
     */
    String getView();

    /**
     * Returns the models instance needed to process the view.
     *
     * @return the models instance.
     */
    Models getModels();

    /**
     * Returns the request locale resolved for the current request.
     *
     * @return the request locale
     */
    Locale getLocale();

    /**
     * Returns the HTTP request object from the container. The type of the request object
     * depends on the environment. In a servlet environment you can use this method to get
     * the HttpServletRequest object.
     *
     * @param type The expected type of the HTTP request object.
     * @param   The expected type of the HTTP request object
     * @return HTTP request object.
     */
     T getRequest(Class type);

    /**
     * Returns the HTTP response object from the container. The type of the response object
     * depends on the environment. In a servlet environment you can use this method to get
     * the HttpServletResponse object.
     *
     * Please note that you should generally prefer using {@link #getOutputStream()}
     * and {@link #getResponseHeaders()} to write the result of processing the view, because
     * these methods are guaranteed to work in all supported environments.
     *
     * @param type The expected type of the HTTP response object.
     * @param   The expected type of the HTTP request object
     * @return HTTP response object.
     */
     T getResponse(Class type);

    /**
     * Get the mutable response headers multivalued map. This map can be modified
     * to change the HTTP response headers. Please note that changing the map will only have
     * an effect on the headers if modifications are performed before data is written
     * to the output stream obtained from {@link #getOutputStream()}.
     *
     * @return mutable multivalued map of response headers.
     */
    MultivaluedMap getResponseHeaders();

    /**
     * The output stream which should be used to write the result of processing a view.
     *
     * @return The output stream
     */
    OutputStream getOutputStream();

    /**
     * The media type to use for the response. Please note that {@link ViewEngine}
     * implementations should respect the charset parameter of the media type when
     * writing data to the output stream obtained from {@link #getOutputStream()}.
     *
     * @return The media type
     */
    MediaType getMediaType();

    /**
     * Returns the {@link javax.ws.rs.core.UriInfo} instance containing information
     * about the current request URI.
     *
     * @return the URI info for the current request.
     * @see javax.ws.rs.core.UriInfo
     */
    UriInfo getUriInfo();

    /**
     * Returns the {@link javax.ws.rs.container.ResourceInfo} instance containing
     * information about the controller method matched in the current request.
     *
     * @return the resource info for the current request.
     * @see javax.ws.rs.container.ResourceInfo
     */
    ResourceInfo getResourceInfo();

    /**
     * Returns the application's configuration. The configuration provides access
     * to properties such as {@link javax.mvc.engine.ViewEngine#VIEW_FOLDER}, which
     * view engines must use to locate views.
     *
     * @return application's configuration.
     * @see javax.ws.rs.core.Configuration
     */
    Configuration getConfiguration();
}