javax.mvc.MvcContext Maven / Gradle / Ivy
Show all versions of javax.mvc-api Show documentation
/*
* 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;
import javax.mvc.annotation.UriRef;
import javax.mvc.security.Csrf;
import javax.mvc.security.Encoders;
import javax.ws.rs.core.Configuration;
import java.net.URI;
import java.util.Locale;
import java.util.Map;
/**
* This class provides contextual information such as context and application
* paths as well as access to the JAX-RS application configuration object.
* In addition, it provides access to the security-related beans {@link
* javax.mvc.security.Csrf} and {@link javax.mvc.security.Encoders}.
*
* Implementations of this class are injectable, must be
* {@link javax.enterprise.context.RequestScoped} and accessible from EL using
* the name {@code mvc}. For example, the CSRF token name and value can be
* accessed in EL using the expressions {@code mvc.csrf.name} and {@code
* mvc.csrf.token}, respectively.
*
* @author Santiago Pericas-Geertsen
* @see javax.ws.rs.core.Configuration
* @since 1.0
*/
public interface MvcContext {
/**
* Get the JAX-RS application configuration object. All application-defined properties
* are accessible via this object.
*
* @return the configuration object.
*/
Configuration getConfig();
/**
* Get the application's context path. The value returned must be normalized
* to start with a slash ({@code '/'}) but not end with one. Thus, the path returned by
* this method can be prepended to that returned by {@link #getApplicationPath()}.
*
* For example, given the URI {@code http://host:port/myapp/resources/hello},
* this method returns {@code /myapp}.
*
* @see javax.servlet.ServletContext#getContextPath()
* @return the application's context path.
*/
String getContextPath();
/**
* Get the application's path which was set using the {@link javax.ws.rs.ApplicationPath}
* annotation. The value returned must be normalized to start with a slash ({@code '/'}) but
* not end with one. Thus, the path returned by this method can be appended to that
* returned by {@link #getContextPath()}.
*
* If the application path is empty or was set to {@code /*}, then an empty string is
* returned to ensure concatenation with {@link #getContextPath()} results in a well-formed
* path. If a JAX-RS application subclass is not found, {@code null} may be returned.
*
* For example, given the URI {@code http://host:port/myapp/resources/hello},
* this method returns {@code /resources}.
*
* @return the application's path or {@code null} if not found.
*/
String getApplicationPath();
/**
* Get the application's base path which is defined as the concatenation of context
* and application paths. It follows that the value returned by this method always
* starts with a slash but never ends with one.
*
* If a JAX-RS application subclass is not found, causing {@link #getApplicationPath()}
* to return {@code null}, then the value returned is the same as {@link #getContextPath}.
*
* @return the application's base path.
*/
String getBasePath();
/**
* Get the CSRF object.
*
* @return the CSRF object.
*/
Csrf getCsrf();
/**
* Get the built-in encoders.
*
* @return instance of encoders.
*/
Encoders getEncoders();
/**
* Returns the locale of the current request.
*
* @return The request locale
*/
Locale getLocale();
/**
* Creates an URI to be matched by a controller method. This is aimed primarily
* for use in view rendering technologies to avoid duplicating the values of the
* {@link javax.ws.rs.Path} annotations.
*
* The controller method can either be identified by the simple name of the controller class
* and the method name separated by '#' (MyController#myMethod) or by the value
* of the {@link UriRef} annotation.
*
* The created URI includes context- and application path.
*
* This method assumes that there is no parameter in the URI-template.
*
* For example:
* ${mvc.uri('MyController#myMethod')}
*
* @param identifier for the controller method.
* @return the constructed URI including context- and application path.
*/
URI uri(String identifier);
/**
* Creates an URI to be matched by a controller method. This is aimed primarily
* for use in view rendering technologies to avoid duplicating the values of the
* {@link javax.ws.rs.Path} annotations.
*
* The controller method can either be identified by the simple name of the controller class
* and the method name separated by '#' (MyController#myMethod) or by the value
* of the {@link UriRef} annotation.
*
* The created URI includes context- and application path.
*
* Any {@link javax.ws.rs.PathParam}, {@link javax.ws.rs.QueryParam}
* and {@link javax.ws.rs.MatrixParam} which could apply for given target
* method will be replaced if a matching key is found in the supplied Map.
* Please note that the map must contain values for all path parameters
* as they are required for building the URI. All other parameters are optional.
*
* For example:
* ${mvc.uri('MyController#myMethod' {'foo': 'bar', 'id': 42})}
*
* @param identifier for the controller method.
* @param params a map of path-, query- and matrix parameters.
* @return the constructed URI including context- and application path.
* @throws IllegalArgumentException if there are any URI template parameters without a supplied value, or if a value is {@code null}.
*/
URI uri(String identifier, Map params);
/**
* Returns a {@link MvcUriBuilder} for building URIs to be matched
* by a controller method. This is aimed primarily for use in Java classes.
*
* The controller method can either be identified by the simple name of the controller class
* and the method name separated by '#' (MyController#myMethod) or by the value
* of the {@link UriRef} annotation.
*
* @param identifier for the controller method.
* @return a reference to a {@link MvcUriBuilder}.
*/
MvcUriBuilder uriBuilder(String identifier);
}