jakarta.faces.context.ExternalContext Maven / Gradle / Ivy
/*
* Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.faces.context;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.UnsupportedEncodingException;
import java.io.Writer;
import java.net.MalformedURLException;
import java.net.URL;
import java.security.Principal;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import jakarta.faces.lifecycle.ClientWindow;
/**
*
* This class
* allows the Faces API to be unaware of the nature of its containing application environment. In particular, this class
* allows Jakarta Faces based applications to run in either a Jakarta Servlet or a Portlet environment.
*
*
*
* The documentation for this class only specifies the behavior for the Jakarta Servlet implementation of
* ExternalContext. The Portlet implementation of ExternalContext is specified under
* the revision of the Portlet Bridge Specification for JavaServer
* Faces JSR that corresponds to this version of the Jakarta Faces Specification.
* See the Preface of the Jakarta Faces Specification Document, for a reference.
*
*
*
* If a reference to an ExternalContext is obtained during application startup or shutdown time, any method
* documented as "valid to call this method during application startup or shutdown" must be supported during application
* startup or shutdown time. The result of calling a method during application startup or shutdown time that does not
* have this designation is undefined.
*
*
*
* An ExternalContext can be injected into a CDI managed bean using
* @Inject ExternalContext externalContext;
*
*/
public abstract class ExternalContext {
@SuppressWarnings({ "UnusedDeclaration" })
private ExternalContext defaultExternalContext;
// ------------------------------------------------------ Manifest Constants
/**
*
* String identifier for BASIC authentication.
*
*/
public static final String BASIC_AUTH = "BASIC";
/**
*
* String identifier for CLIENT_CERT authentication.
*
*/
public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
/**
*
* String identifier for DIGEST authentication.
*
*/
public static final String DIGEST_AUTH = "DIGEST";
/**
*
* String identifier for FORM authentication.
*
*/
public static final String FORM_AUTH = "FORM";
// ---------------------------------------------------------- Public Methods
/**
*
* Adds the cookie represented by the arguments to the response.
*
*
*
*
*
* Jakarta Servlet: This must be accomplished by calling the
* jakarta.servlet.http.HttpServletResponse method addCookie(). The Cookie
* argument must be constructed by passing the name and value parameters. If the
* properties arugument is non-null and not empty, the Cookie instance must be
* initialized as described below.
*
*
*
* Cookie handling table
*
*
*
* Key in "values" Map (case sensitive)
*
* Expected type of value.
*
* Name of setter method on Cookie instance to be set with the value from the Map.
*
*
*
*
*
* comment
*
* String
*
* setComment
*
*
*
*
*
* domain
*
* String
*
* setDomain
*
*
*
*
*
* maxAge
*
* Integer
*
* setMaxAge
*
*
*
*
*
* secure
*
* Boolean
*
* setSecure
*
*
*
*
*
* path
*
* String
*
* setPath
*
*
*
*
*
* httpOnly
*
* Boolean
*
* setHttpOnly
*
*
*
*
*
* any other attribute (e.g. SameSite)
*
* String
*
* setAttribute
*
*
*
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
*
*
* @param name To be passed as the first argument to the Cookie constructor.
*
* @param value To be passed as the second argument to the Cookie constructor.
*
* @param properties A Map containg key/value pairs to be passed as arguments to the setter methods as
* described above.
*
* @since 2.0
*/
public void addResponseCookie(String name, String value, Map properties) {
if (defaultExternalContext != null) {
defaultExternalContext.addResponseCookie(name, value, properties);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Dispatch a request to the specified resource to create output for this
* response.
*
*
*
* Jakarta Servlet: This must be accomplished by calling the jakarta.servlet.ServletContext method
* getRequestDispatcher(path), and calling the forward() method on the resulting object.
*
*
* If the call to getRequestDisatcher(path) returns null, send
* aServletResponse SC_NOT_FOUND error code.
*
*
* @param path Context relative path to the specified resource, which must start with a slash ("/") character
*
* @throws jakarta.faces.FacesException thrown if a ServletException occurs
* @throws IOException if an input/output error occurs
*/
public abstract void dispatch(String path) throws IOException;
/**
*
* Return the input URL, after performing any rewriting needed to ensure that
* it will correctly identify an addressable action in the current application.
*
*
*
* Encoding the {@link jakarta.faces.lifecycle.ClientWindow}
*
*
*
*
*
* Call
* {@link jakarta.faces.lifecycle.ClientWindow#isClientWindowRenderModeEnabled(jakarta.faces.context.FacesContext) }. If
* the result is false take no further action and return the rewritten URL. If the result is
* true, call {@link #getClientWindow()}. If the result is non-null, call
* {@link jakarta.faces.lifecycle.ClientWindow#getId()} and append the id to the query string of the URL, making the
* necessary allowances for a pre-existing query string or no query-string.
*
*
*
* Call {@link jakarta.faces.lifecycle.ClientWindow#getQueryURLParameters}. If the result is non-{@code null}, for each
* parameter in the map, unconditionally add that parameter to the URL.
*
*
*
* The name of the query string parameter is given by the value of the constant
* {@link jakarta.faces.render.ResponseStateManager#CLIENT_WINDOW_URL_PARAM}.
*
*
*
*
*
* Jakarta Servlet: This must be the value returned by the
* jakarta.servlet.http.HttpServletResponse method encodeURL(url).
*
*
* @param url The input URL to be encoded
*
* @return the encoded URL.
*
* @throws NullPointerException if url is null
*/
public abstract String encodeActionURL(String url);
/**
*
* Return the specified name, after prefixing it with a namespace that ensures
* that it will be unique within the context of a particular page.
*
*
*
* Jakarta Servlet: The input value must be returned unchanged.
*
*
* @param name Name to be encoded
*
* @return the unique name prefixed with namespace.
*
*
*
*/
public abstract String encodeNamespace(String name);
/**
*
* Return the input URL, after performing any rewriting needed to ensure that it will correctly identify an addressable
* resource in the current application.
*
*
*
* Jakarta Servlet: This must be the value returned by the
* jakarta.servlet.http.HttpServletResponse method encodeURL(url).
*
*
* @param url The input URL to be encoded
*
* @return the encoded resource URL.
*
* @throws NullPointerException if url is null
*/
// PENDING(craigmcc) - Currently identical to encodeActionURL()
public abstract String encodeResourceURL(String url);
/**
*
* Return the websocket URL, after performing any rewriting needed to ensure that it will correctly identify an
* addressable websocket in the current application.
*
*
*
* Jakarta Servlet: This must ensure that the input URL is prefixed with the correct websocket scheme, domain
* and port and then encoded by {@link #encodeResourceURL(String)}.
*
*
* @param url The input URL to be encoded.
*
* @return the encoded websocket URL.
*
* @throws NullPointerException if url is null.
*
* @since 2.3
*/
public abstract String encodeWebsocketURL(String url);
/**
*
* Return a mutable Map representing the application scope
* attributes for the current application. The returned Map must implement the entire contract for a
* modifiable map as described in the JavaDocs for java.util.Map. Modifications made in the
* Map must cause the corresponding changes in the set of application scope attributes. Particularly the
* clear(), remove(), put(), putAll(), and get()
* operations must take the appropriate action on the underlying data structure.
*
*
*
* It is valid to call this method during application startup or shutdown. If called at startup or shutdown time, this
* method returns a Map that is backed by the same container context instance (ServletContext
* or PortletContext) as the one returned by calling getApplicationMap() on the
* ExternalContext returned by the FacesContext during an actual request.
*
*
*
* Jakarta Servlet: This must be the set of attributes available via the
* jakarta.servlet.ServletContext methods getAttribute(), getAttributeNames(),
* removeAttribute(), and setAttribute().
*
*
* @return the map associated with the backed ServletContext.
*
*/
public abstract Map getApplicationMap();
/**
*
* Return the name of the authentication scheme used to authenticate the current user, if any; otherwise, return
* null. For standard authentication schemes, the returned value will match one of the following constants:
* BASIC_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH, or FORM_AUTH.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest
* method getAuthType().
*
*
* @return the authentication type.
*/
public abstract String getAuthType();
/**
*
* Return the threadsafe {@link Flash} for this application. The default implementation will throw
* UnsupportedOperationException. Compliant Jakarta Faces runtimes must provide an implementation of
* this method.
*
*
* @return the Flash for this application.
*
* @since 2.0
*/
public Flash getFlash() {
if (defaultExternalContext != null) {
return defaultExternalContext.getFlash();
}
throw new UnsupportedOperationException();
}
/**
*
* Returns the MIME type of the specified file or null if the MIME type is not known. The MIME type is
* determined by the container.
*
*
*
* It is valid to call this method during application startup or shutdown. If called during application startup or
* shutdown, this method calls through to the getMimeType() method on the same container context instance
* (ServletContext or PortletContext) as the one used when calling getMimeType()
* on the ExternalContext returned by the FacesContext during an actual request.
*
*
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletContext method
* getMimeType().
*
*
*
*
* @param file The file for which the mime type should be obtained.
*
* @return the MIME type of the file.
*
* @since 2.0
*/
public String getMimeType(String file) {
if (defaultExternalContext != null) {
return defaultExternalContext.getMimeType(file);
}
throw new UnsupportedOperationException();
}
/**
*
* Return the application environment object instance for the current
* appication.
*
*
*
* It is valid to call this method during application startup or shutdown. If called during application startup or
* shutdown, this returns the same container context instance (ServletContext or
* PortletContext) as the one returned when calling getContext() on the
* ExternalContext returned by the FacesContext during an actual request.
*
*
*
*
* Jakarta Servlet: This must be the current application's jakarta.servlet.ServletContext
* instance.
*
*
* @return the object of the ServletContext.
*
*/
public abstract Object getContext();
/**
*
*
* Return the name of the container context for this application.
*
*
*
* Return the result of calling getServletContextName() on the ServletContext instance for
* this application. It is valid to call this method during application startup or shutdown.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @return the name the ServletContext.
*
*/
public String getContextName() {
if (defaultExternalContext != null) {
return defaultExternalContext.getContextName();
}
throw new UnsupportedOperationException();
}
/**
*
*
* Return the name of the container context for this application.
*
*
*
* Jakarta Servlet: Return the result of calling getContextPath() on the
* ServletContext instance for this application.
*
*
*
* It is valid to call this method during application startup or shutdown.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @return the context path of this application.
*
* @since 2.2
*/
public String getApplicationContextPath() {
if (defaultExternalContext != null) {
return defaultExternalContext.getApplicationContextPath();
}
throw new UnsupportedOperationException();
}
/**
*
* Return the value of the specified application initialization parameter (if
* any).
*
*
*
* Jakarta Servlet: This must be the result of the jakarta.servlet.ServletContext method
* getInitParameter(name).
*
*
*
* It is valid to call this method during application startup or shutdown. If called during application startup or
* shutdown, this method calls through to the actual container context to return the init parameter value.
*
*
* @param name Name of the requested initialization parameter
*
* @throws NullPointerException if name is null
*
* @return the value of the specified parameter.
*
*/
public abstract String getInitParameter(String name);
/**
*
* Return an immutable Map whose keys are the set of application
* initialization parameter names configured for this application, and whose values are the corresponding parameter
* values. The returned Map must implement the entire contract for an unmodifiable map as described in the
* JavaDocs for java.util.Map.
*
*
*
* It is valid to call this method during application startup or shutdown. If called during application startup or
* shutdown, this method returns a Map that is backed by the same container context instance
* (ServletContext or PortletContext) as the one returned by calling
* getInitParameterMap() on the ExternalContext returned by the FacesContext
* during an actual request.
*
*
*
* Jakarta Servlet: This result must be as if it were synthesized by calling the
* jakarta.servlet.ServletContext method getInitParameterNames, and putting each configured
* parameter name/value pair into the result.
*
*
* @return the init parameter map for this application.
*
*/
public abstract Map getInitParameterMap();
/**
*
* Return the login name of the user making the current request if any; otherwise, return null.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest
* method getRemoteUser().
*
*
* @return the user name of the current request.
*
*/
public abstract String getRemoteUser();
/**
*
* Return the environment-specific object instance for the current request.
*
*
*
* Jakarta Servlet: This must be the current request's jakarta.servlet.http.HttpServletRequest
* instance.
*
*
* @return the instance of the current request.
*
*/
public abstract Object getRequest();
/**
*
* Set the environment-specific request to be returned by subsequent calls to {@link #getRequest}. This may be used to
* install a wrapper for the request.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param request the request object to be set.
*
* @since 1.2
*/
public void setRequest(Object request) {
if (defaultExternalContext != null) {
defaultExternalContext.setRequest(request);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Returns the name of the scheme used to make this request, for example, http, https, or ftp.
*
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletRequest method
* getScheme().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
*
*
* @return the name of the scheme.
*
* @since 2.0
*/
public String getRequestScheme() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestScheme();
}
throw new UnsupportedOperationException();
}
/**
*
* Returns the host name of the server to which the request was sent.
*
*
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletRequest method
* getServerName().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
*
*
* @return the host name of the server.
*
* @since 2.0
*/
public String getRequestServerName() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestServerName();
}
throw new UnsupportedOperationException();
}
/**
*
* Returns the port number to which the request was sent.
*
*
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletRequest method
* getServerPort().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
*
*
* @return the port number to which the request was sent.
*
* @since 2.0
*/
public int getRequestServerPort() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestServerPort();
}
throw new UnsupportedOperationException();
}
/**
*
*
* Overrides the name of the character encoding used in the body of this request.
*
*
*
* Calling this method after the request has been accessed will have no no effect, unless a Reader or
* Stream has been obtained from the request, in which case an IllegalStateException is
* thrown.
*
*
*
* Jakarta Servlet: This must call through to the jakarta.servlet.ServletRequest method
* setCharacterEncoding().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param encoding the encoding name to be set.
*
* @throws java.io.UnsupportedEncodingException if this is not a valid encoding
*
* @since 1.2
*
*/
public void setRequestCharacterEncoding(String encoding) throws UnsupportedEncodingException {
if (defaultExternalContext != null) {
defaultExternalContext.setRequestCharacterEncoding(encoding);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Returns a String containing the real path for a given virtual path.
*
*
*
* It is valid to call this method during application startup or shutdown. If called during application startup or
* shutdown, this method calls through to the getRealPath() method on the same container context instance
* (ServletContext or PortletContext) as the one used when calling getRealPath()
* on the ExternalContext returned by the FacesContext during an actual request.
*
*
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletContext method
* getRealPath().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
*
*
* @param path The context of the requested initialization parameter
*
* @return the real path for the specified virtual path.
*
* @since 2.0
*/
public String getRealPath(String path) {
if (defaultExternalContext != null) {
return defaultExternalContext.getRealPath(path);
}
throw new UnsupportedOperationException();
}
/**
*
* Return the portion of the request URI that identifies the web application context for this request.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest
* method getContextPath().
*
*
* @return the context path for this request.
*/
public abstract String getRequestContextPath();
/**
*
* Return an immutable Map whose keys are the set of cookie names included in the current request, and
* whose values (of type jakarta.servlet.http.Cookie) are the first (or only) cookie for each cookie name
* returned by the underlying request. The returned Map must implement the entire contract for an
* unmodifiable map as described in the JavaDocs for java.util.Map.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest
* method getCookies(), unless null was returned, in which case this must be a zero-length
* array.
*
*
* @return the cookie map in the current request.
*
*/
public abstract Map getRequestCookieMap();
/**
*
* Return an immutable Map whose keys are the set of request header names included in the current request,
* and whose values (of type String) are the first (or only) value for each header name returned by the underlying
* request. The returned Map must implement the entire contract for an unmodifiable map as described in the
* JavaDocs for java.util.Map. In addition, key comparisons must be performed in a case insensitive manner.
*
*
*
* Jakarta Servlet: This must be the set of headers available via the
* jakarta.servlet.http.HttpServletRequest methods getHeader() and
* getHeaderNames().
*
*
* @return the header map in the current request.
*
*/
public abstract Map getRequestHeaderMap();
/**
*
* Return an immutable Map whose keys are the set of request header names included in the current request,
* and whose values (of type String[]) are all of the value for each header name returned by the underlying request. The
* returned Map must implement the entire contract for an unmodifiable map as described in the JavaDocs for
* java.util.Map. In addition, key comparisons must be performed in a case insensitive manner.
*
*
*
* Jakarta Servlet: This must be the set of headers available via the
* jakarta.servlet.http.HttpServletRequest methods getHeaders() and
* getHeaderNames().
*
*
* @return the header values map in the current request.
*/
public abstract Map getRequestHeaderValuesMap();
/**
*
* Return the preferred Locale in which the client will accept content.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletRequest method
* getLocale().
*
*
* @return the Locale of the current request.
*/
public abstract Locale getRequestLocale();
/**
*
* Return an Iterator over the preferred Locales specified in the request, in decreasing order
* of preference.
*
*
*
* Jakarta Servlet: This must be an Iterator over the values returned by the
* jakarta.servlet.ServletRequest method getLocales().
*
*
* @return the Iterator of Locales of the current request.
*
*/
public abstract Iterator getRequestLocales();
/**
*
* Return a mutable Map representing the request scope attributes for the current application. The returned
* Map must implement the entire contract for a modifiable map as described in the JavaDocs for
* java.util.Map. Modifications made in the Map must cause the corresponding changes in the
* set of request scope attributes. Particularly the clear(), remove(), put(),
* putAll(), and get() operations must take the appropriate action on the underlying data
* structure.
*
*
*
* Jakarta Servlet: This must be the set of attributes available via the
* jakarta.servlet.ServletRequest methods getAttribute(), getAttributeNames(),
* removeAttribute(), and setAttribute().
*
*
* @return the map including the attributes of the current request.
*
*/
public abstract Map getRequestMap();
/**
*
* Return an immutable Map whose keys are the set of request parameters names included in the current
* request, and whose values (of type String) are the first (or only) value for each parameter name returned by the
* underlying request. The returned Map must implement the entire contract for an unmodifiable map as
* described in the JavaDocs for java.util.Map.
*
*
*
* Jakarta Servlet: This must be the set of parameters available via the
* jakarta.servlet.ServletRequest methods getParameter() and getParameterNames().
*
*
* @return the map for the current request parameters.
*
*/
public abstract Map getRequestParameterMap();
/**
*
* Return an Iterator over the names of all request parameters included in the current request.
*
*
*
* Jakarta Servlet: This must be an Iterator over the values returned by the
* jakarta.servlet.ServletRequest method getParameterNames().
*
*
* @return the Iterator for the names of the current request parameters.
*
*/
public abstract Iterator getRequestParameterNames();
/**
*
* Return an immutable Map whose keys are the set of request parameters names included in the current
* request, and whose values (of type String[]) are all of the values for each parameter name returned by the underlying
* request. The returned Map must implement the entire contract for an unmodifiable map as described in the
* JavaDocs for java.util.Map.
*
*
*
* Jakarta Servlet: This must be the set of parameters available via the
* jakarta.servlet.ServletRequest methods getParameterValues() and
* getParameterNames().
*
*
* @return the map for the parameter values of the current request.
*
*/
public abstract Map getRequestParameterValuesMap();
/**
*
* Return the extra path information (if any) included in the request URI; otherwise, return null.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest
* method getPathInfo().
*
*
* @return the path information of the current request.
*
*/
public abstract String getRequestPathInfo();
/**
*
* Return the Jakarta Servlet path information (if any) included in the request URI; otherwise, return
* null.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest
* method getServletPath().
*
*
* @return the Jakarta Servlet path information of the current request.
*/
public abstract String getRequestServletPath();
/**
*
*
* Return the character encoding currently being used to interpret this request.
*
*
*
* Jakarta Servlet: This must return the value returned by the jakarta.servlet.ServletRequest
* method getCharacterEncoding().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @return the character encoding currently being used.
*
* @since 1.2
*
*/
public String getRequestCharacterEncoding() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestCharacterEncoding();
}
throw new UnsupportedOperationException();
}
/**
*
*
* Return the MIME Content-Type for this request. If not available, return null.
*
*
*
* Jakarta Servlet: This must return the value returned by the jakarta.servlet.ServletRequest
* method getContentType().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @return the Content-Type for this request.
*
* @since 1.2
*/
public String getRequestContentType() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestContentType();
}
throw new UnsupportedOperationException();
}
/**
*
* Return the result of calling getContentLenth() on the ServletRequest instance for this
* request.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @return the content length of the current request.
*
* @since 2.0
*/
public int getRequestContentLength() {
if (defaultExternalContext != null) {
return defaultExternalContext.getRequestContentLength();
}
throw new UnsupportedOperationException();
}
/**
*
*
* Returns the name of the character encoding (MIME charset) used for the body
* sent in this response.
*
*
*
* Jakarta Servlet: This must return the value returned by the jakarta.servlet.ServletResponse
* method getCharacterEncoding().
*
*
*
* Portlet: if this method is called during a lifecycle phase other than RENDER_RESPONSE, this must return
* null. If called during RENDER_RESPONSE, return the response encoding of the portlet response.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @return the name of the character encoding.
*
* @since 1.2
*/
public String getResponseCharacterEncoding() {
if (defaultExternalContext != null) {
return defaultExternalContext.getResponseCharacterEncoding();
}
throw new UnsupportedOperationException();
}
/**
*
*
* Return the MIME Content-Type for this response. If not available, return null.
*
*
*
* Jakarta Servlet: This must return the value returned by the jakarta.servlet.ServletResponse
* method getContentType().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @return the MIME Content-Type for this response.
*
* @since 1.2
*/
public String getResponseContentType() {
if (defaultExternalContext != null) {
return defaultExternalContext.getResponseContentType();
}
throw new UnsupportedOperationException();
}
/**
*
* Return a URL for the application resource mapped to the
* specified path, if it exists; otherwise, return null.
*
*
*
* It is valid to call this method during application startup or shutdown. If called during application startup or
* shutdown, this method calls through to the getResource() method on the same container context instance
* (ServletContext or PortletContext) as the one used when calling getResource()
* on the ExternalContext returned by the FacesContext during an actual request.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletContext method
* getResource(path).
*
*
* @param path The path to the requested resource, which must start with a slash ("/" character
*
* @return the URL of the resource.
*
* @throws MalformedURLException if the specified path is not in the correct form
* @throws NullPointerException if path is null
*/
public abstract URL getResource(String path) throws MalformedURLException;
/**
*
* Return an InputStream for an application resource mapped to
* the specified path, if it exists; otherwise, return null.
*
*
*
* It is valid to call this method during application startup or shutdown. If called during application startup or
* shutdown, this method calls through to the getResourceAsStream() method on the same container context
* instance (ServletContext or PortletContext) as the one used when calling
* getResourceAsStream() on the ExternalContext returned by the FacesContext
* during an actual request.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletContext method
* getResourceAsStream(path).
*
*
* @param path The path to the requested resource, which must start with a slash ("/" character
*
* @return the InputStream for the application resource.
*
* @throws NullPointerException if path is null
*/
public abstract InputStream getResourceAsStream(String path);
/**
*
* Return the Set of resource paths for all application resources
* whose resource path starts with the specified argument.
*
*
*
* It is valid to call this method during application startup or shutdown. If called during application startup or
* shutdown, this method calls through to the getResourcePaths() method on the same container context
* instance (ServletContext or PortletContext) as the one used when calling
* getResourcePaths() on the ExternalContext returned by the FacesContext during
* an actual request.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.ServletContext method
* getResourcePaths(path).
*
*
* @param path Partial path used to match resources, which must start with a slash ("/") character
*
* @return the Set of resource paths for the application resources.
*
* @throws NullPointerException if path is null
*/
public abstract Set getResourcePaths(String path);
/**
*
* Return the environment-specific object instance for the current response.
*
*
*
* Jakarta Servlet: This is the current request's jakarta.servlet.http.HttpServletResponse
* instance.
*
*
* @return the instance of the current jakarta.servlet.http.HttpServletResponse.
*/
public abstract Object getResponse();
/**
*
* Set the environment-specific response to be returned by subsequent calls to {@link #getResponse}. This may be used to
* install a wrapper for the response.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param response the response instance to be set.
*
* @since 1.2
*/
public void setResponse(Object response) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponse(response);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Returns an OutputStream suitable for writing binary data to the user-agent.
*
*
*
*
*
* Jakarta Servlet: This must return the value returned by the jakarta.servlet.ServletResponse
* method getOutputStream().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
*
*
* @return the OutputStream for the current response.
*
* @throws IOException any IO related exception.
*
* @since 2.0
*/
public OutputStream getResponseOutputStream() throws IOException {
if (defaultExternalContext != null) {
return defaultExternalContext.getResponseOutputStream();
}
throw new UnsupportedOperationException();
}
/**
*
* Returns a Writer suitable for writing character data to the user-agent.
*
*
*
*
*
* Jakarta Servlet: This must return the value returned by the
* {@link jakarta.servlet.ServletResponse#getWriter}.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
*
*
* @return the Writer for the current response.
*
* @throws IOException any IO related exception.
*
* @since 2.0
*/
public Writer getResponseOutputWriter() throws IOException {
if (defaultExternalContext != null) {
return defaultExternalContext.getResponseOutputWriter();
}
throw new UnsupportedOperationException();
}
/**
*
*
* Sets the character encoding (MIME charset) of the response being sent to the client, for example, to UTF-8.
*
*
*
* Jakarta Servlet: This must call through to the jakarta.servlet.ServletResponse method
* setCharacterEncoding().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param encoding the character encoding to be sent by the current response.
*
* @since 1.2
*
*/
public void setResponseCharacterEncoding(String encoding) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseCharacterEncoding(encoding);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Sets the content type of the response being sent to the client, if the response has not been committed yet.
*
*
*
*
*
* Jakarta Servlet: This must call setContentType() on the underlying
* jakarta.servlet.ServletResponse instance.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
*
*
* @param contentType The content type to be set as the contentType of the response.
*
* @since 2.0
*/
public void setResponseContentType(String contentType) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseContentType(contentType);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* If the create parameter is true, create (if necessary) and return a session instance
* associated with the current request. If the create parameter is false return any existing
* session instance associated with the current request, or return null if there is no such session.
*
*
*
* Jakarta Servlet: This must return the result of calling getSession(create) on the underlying
* jakarta.servlet.http.HttpServletRequest instance.
*
*
* @param create Flag indicating whether or not a new session should be created if there is no session associated with
* the current request
*
* @return the session object of the current request.
*/
public abstract Object getSession(boolean create);
/**
*
* Return the id of the current session or the empty string if no session has been created and the create
* parameter is false.
*
*
*
*
*
* Jakarta Servlet: If create is true, obtain a reference to the HttpSession for the
* current request (creating the session if necessary) and return its id. If create is false,
* obtain a reference to the current session, if one exists, and return its id. If no session exists, return the empty
* string.
*
*
*
*
* @since 2.2
*
* @param create Flag indicating whether or not a new session should be created if there is no session associated with
* the current request
*
* @return the session id for the current request.
*/
public String getSessionId(boolean create) {
String result = "";
if (defaultExternalContext != null) {
result = defaultExternalContext.getSessionId(create);
} else {
throw new UnsupportedOperationException();
}
return result;
}
/**
*
* Returns the maximum time interval, in seconds, that the Jakarta Servlet container will keep this session open between
* client accesses. After this interval, the Jakarta Servlet container will invalidate the session. The maximum time
* interval can be set with the {@link #setSessionMaxInactiveInterval} method.
*
*
*
* A return value of zero or less indicates that the session will never timeout.
*
*
*
* Jakarta Servlet: This must return the result of calling getMaxInactiveInterval on the
* underlying jakarta.servlet.http.HttpSession instance.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @return the session maximum inactive interval.
* @since 2.1
*/
public int getSessionMaxInactiveInterval() {
int result = 0;
if (defaultExternalContext != null) {
result = defaultExternalContext.getSessionMaxInactiveInterval();
} else {
throw new UnsupportedOperationException();
}
return result;
}
/**
*
* Return a mutable Map representing the session scope attributes for the current application. The returned
* Map must implement the entire contract for a modifiable map as described in the JavaDocs for
* java.util.Map. Modifications made in the Map must cause the corresponding changes in the
* set of session scope attributes. Particularly the clear(), remove(), put(),
* and get() operations must take the appropriate action on the underlying data structure. Accessing
* attributes via this Map must cause the creation of a session associated with the current request, if
* such a session does not already exist.
*
*
*
* Jakarta Servlet: This must be the set of attributes available via the
* jakarta.servlet.http.HttpSession methods getAttribute(), getAttributeNames(),
* removeAttribute(), and setAttribute().
*
*
* @return the session map for the current application.
*
*/
public abstract Map getSessionMap();
/**
*
* Return the Principal object containing the name of the current authenticated user, if any; otherwise,
* return null.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest
* method getUserPrincipal().
*
*
* @return the Principal object.
*/
public abstract Principal getUserPrincipal();
/**
*
* Return the {@link ClientWindow} set in a preceding call to {@link #setClientWindow}, or null if no such
* call has been made.
*
*
* @since 2.2
*
* @return the instance of the ClientWindow.
*/
public ClientWindow getClientWindow() {
if (defaultExternalContext != null) {
return defaultExternalContext.getClientWindow();
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Invalidates this session then unbinds any objects bound to it.
*
*
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpSession method
* invalidate().
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
*
*
* @since 2.0
*/
public void invalidateSession() {
if (defaultExternalContext != null) {
defaultExternalContext.invalidateSession();
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Return true if the currently authenticated user is included in the specified role. Otherwise, return
* false.
*
*
*
* Jakarta Servlet: This must be the value returned by the jakarta.servlet.http.HttpServletRequest
* method isUserInRole(role).
*
*
* @param role Logical role name to be checked
*
* @return the flag indicating whether the current user is in the specified role.
*
* @throws NullPointerException if role is null
*/
public abstract boolean isUserInRole(String role);
/**
*
* Log the specified message to the application object.
*
*
*
* It is valid to call this method during application startup or shutdown. If called during application startup or
* shutdown, this calls the log() method on the same container context instance
* (ServletContext or PortletContext) as the one used during a call to log() on
* the ExternalContext returned by the FacesContext during an actual request.
*
*
*
*
* Jakarta Servlet: This must be performed by calling the jakarta.servlet.ServletContext method
* log(String).
*
*
* @param message Message to be logged
*
* @throws NullPointerException if message is null
*/
public abstract void log(String message);
/**
*
* Log the specified message and exception to the application object.
*
*
*
* It is valid to call this method during application startup or shutdown. If called during application startup or
* shutdown, this calls the log() method on the same container context instance
* (ServletContext or PortletContext) as the one used when calling log() on the
* ExternalContext returned by the FacesContext during an actual request.
*
*
*
* Jakarta Servlet: This must be performed by calling the jakarta.servlet.ServletContext method
* log(String,Throwable).
*
*
* @param message Message to be logged
* @param exception Exception to be logged
*
* @throws NullPointerException if message or exception is null
*/
public abstract void log(String message, Throwable exception);
/**
*
* Redirect a request to the specified URL, and cause the
* responseComplete() method to be called on the {@link FacesContext} instance for the current request.
*
*
*
* The implementation must determine if the request is an Ajax request by obtaining a
* {@link PartialViewContext} instance from the {@link FacesContext} and calling
* {@link PartialViewContext#isAjaxRequest()}.
*
*
*
* Jakarta Servlet: For non Ajax requests, this must be
* accomplished by calling the jakarta.servlet.http.HttpServletResponse method
* sendRedirect().
For Ajax requests, the implementation must:
*
*
* - Get a {@link PartialResponseWriter} instance from the {@link FacesContext}.
* - Call {@link #setResponseContentType} with
text/xml
* - Call {@link #setResponseCharacterEncoding} with
UTF-8
* - Call {@link #addResponseHeader} with
Cache-Control, no-cache
* - Call {@link PartialResponseWriter#startDocument}
* - Call {@link PartialResponseWriter#redirect} with the
url argument.
* - Call {@link PartialResponseWriter#endDocument}
*
*
* @param url Absolute URL to which the client should be redirected
*
* @throws IllegalArgumentException if the specified url is relative
* @throws IllegalStateException if, in a portlet environment, the current response object is a
* RenderResponse instead of an ActionResponse
* @throws IllegalStateException if, in a Jakarta Servlet environment, the current response has already been committed
* @throws IOException if an input/output error occurs
*/
public abstract void redirect(String url) throws IOException;
/**
*
* Set the response header with the given name and value.
*
*
*
* Jakarta Servlet:This must be performed by calling the jakarta.servlet.http.HttpServletResponse
* setHeader method.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param name The name of the response header.
* @param value The value of the response header.
*
* @since 2.0
*/
public void setResponseHeader(String name, String value) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseHeader(name, value);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Add the given name and value to the response header.
*
*
*
* Jakarta Servlet:This must be performed by calling the jakarta.servlet.http.HttpServletResponse
* addHeader method.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param name The name of the response header.
* @param value The value of the response header.
*
* @since 2.0
*/
public void addResponseHeader(String name, String value) {
if (defaultExternalContext != null) {
defaultExternalContext.addResponseHeader(name, value);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Set the buffer size for the current response.
*
*
*
* Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse
* setBufferSize method.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param size the new buffer size
*
* @since 2.0
*/
public void setResponseBufferSize(int size) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseBufferSize(size);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Return the buffer size for the current response.
*
*
*
* Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse
* getBufferSize method.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @since 2.0
*
* @return the buffer size of the response.
*/
public int getResponseBufferSize() {
if (defaultExternalContext != null) {
return defaultExternalContext.getResponseBufferSize();
}
throw new UnsupportedOperationException();
}
/**
*
* Check if the current response has been committed.
*
*
*
* Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse
* isCommitted method.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @since 2.0
*
* @return the flag indicating whether the current response has been committed.
*/
public boolean isResponseCommitted() {
if (defaultExternalContext != null) {
return defaultExternalContext.isResponseCommitted();
}
throw new UnsupportedOperationException();
}
/**
*
* Resets the current response.
*
*
*
* Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse
* reset method.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @since 2.0
*/
public void responseReset() {
if (defaultExternalContext != null) {
defaultExternalContext.responseReset();
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Sends an HTTP status code with message.
*
*
*
* Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse
* sendError method.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param statusCode an HTTP status code
* @param message an option message to detail the cause of the code
*
* @since 2.0
*
* @throws IOException any IO related exceptions.
*/
public void responseSendError(int statusCode, String message) throws IOException {
if (defaultExternalContext != null) {
defaultExternalContext.responseSendError(statusCode, message);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Sets the HTTP status code for the response.
*
*
*
* Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse
* setStatus method.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param statusCode an HTTP status code
*
* @since 2.0
*/
public void setResponseStatus(int statusCode) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseStatus(statusCode);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Specifies the time, in seconds, between client requests before the Jakarta Servlet container will invalidate this
* session.
*
*
*
* An interval value of zero or less indicates that the session should never timeout.
*
*
*
* Jakarta Servlet: This must call setMaxInactiveInterval on the underlying
* jakarta.servlet.http.HttpServletRequest instance.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param interval the value to be set.
*
* @since 2.1
*/
public void setSessionMaxInactiveInterval(int interval) {
if (defaultExternalContext != null) {
defaultExternalContext.setSessionMaxInactiveInterval(interval);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Associate this instance with a {@link ClientWindow}.
*
*
* @param window the window with which this instance is associated.
*
* @since 2.2
*/
public void setClientWindow(ClientWindow window) {
if (defaultExternalContext != null) {
defaultExternalContext.setClientWindow(window);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Flushes the buffered response content to the client.
*
*
*
* Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse
* flushBuffer method.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @since 2.0
*
* @throws IOException any IO related exception.
*/
public void responseFlushBuffer() throws IOException {
if (defaultExternalContext != null) {
defaultExternalContext.responseFlushBuffer();
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Set the content length of the response.
*
*
*
* Jakarta Servlet: This must be performed by calling the jakarta.servlet.http.HttpServletResponse
* setContentLength method.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param length the value to be set.
*
* @since 2.0
*/
public void setResponseContentLength(int length) {
if (defaultExternalContext != null) {
defaultExternalContext.setResponseContentLength(length);
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* The purpose of this method is to generate a query string from the
* collection of Parameter objects provided by the parameters argument and append that query string to the baseUrl. This
* method must be able to encode the parameters to a baseUrl that may or may not have existing query parameters. The
* parameter values should be encoded appropriately for the environment so that the resulting URL can be used as the
* target of a link (e.g., in an href attribute) in a Jakarta Faces response. It's possible for an
* ExternalContext implementation to override this method in any way that would make the URL bookmarkable in that
* environment.
*
*
*
* See {@link #encodeActionURL(java.lang.String)} for the required specification of how to encode the
* {@link jakarta.faces.lifecycle.ClientWindow}.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @param baseUrl The base URL onto which the query string generated by this method will be appended. The URL may
* contain query parameters.
* @param parameters The collection of Parameter objects, representing name=value pairs that are used to produce a query
* string
*
* @return the result of encoding.
*
* @since 2.0
*/
public String encodeBookmarkableURL(String baseUrl, Map> parameters) {
if (defaultExternalContext != null) {
return defaultExternalContext.encodeBookmarkableURL(baseUrl, parameters);
}
throw new UnsupportedOperationException();
}
/**
* The purpose of this method is to generate a query string from the
* collection of Parameter objects provided by the parameters argument and append that query string to the baseUrl. This
* method must be able to encode the parameters to a baseUrl that may or may not have existing query parameters. The
* parameter values should be encoded appropriately for the environment so that the resulting URL can be used as the
* target of a redirect. It's possible for an ExternalContext implementation to override this method to accomodate the
* definition of redirect for that environment.
*
*
* See {@link #encodeActionURL(java.lang.String)} for the required specification of how to encode the
* {@link jakarta.faces.lifecycle.ClientWindow}.
*
*
* @param baseUrl The base URL onto which the query string generated by this method will be appended. The URL may
* contain query parameters.
* @param parameters The collection of Parameter objects, representing name=value pairs that are used to produce a query
* string
*
* @return the result of encoding.
* @since 2.0
*/
public String encodeRedirectURL(String baseUrl, Map> parameters) {
if (defaultExternalContext != null) {
return defaultExternalContext.encodeRedirectURL(baseUrl, parameters);
}
throw new UnsupportedOperationException();
}
/**
*
* Return the input URL, after performing any rewriting needed to ensure that
* it can be used in a partial page submission (ajax request) to correctly identify an addressable action in the current
* application.
*
*
*
* See {@link #encodeActionURL(java.lang.String)} for the required specification of how to encode the
* {@link jakarta.faces.lifecycle.ClientWindow}.
*
*
*
*
*
* Jakarta Servlet:Returns the same encoded URL as the {@link #encodeActionURL(String url)} method.
*
*
*
* Portlet:Returns an encoded URL that, upon HTTP POST, will invoke the RESOURCE_PHASE of the portlet
* lifecycle.
*
*
*
*
* @param url The input URL to be encoded
*
* @return the encoded URL.
*
* @throws NullPointerException if url is null
*
* @since 2.0
*/
public String encodePartialActionURL(String url) {
if (defaultExternalContext != null) {
return defaultExternalContext.encodePartialActionURL(url);
}
throw new UnsupportedOperationException();
}
/**
*
* Returns a boolean indicating whether this request was made using a secure channel, such as HTTPS.
*
*
*
* Jakarta Servlet: This must return the result of calling isSecure on the underlying
* jakarta.servlet.http.HttpServletRequest instance.
*
*
*
* The default implementation throws UnsupportedOperationException and is provided for the sole purpose of
* not breaking existing applications that extend this class.
*
*
* @return the boolean indicating whether this request is secured.
*
* @since 2.1
*/
public boolean isSecure() {
if (defaultExternalContext != null) {
return defaultExternalContext.isSecure();
} else {
throw new UnsupportedOperationException();
}
}
/**
*
* Release any resources associated with this ExternalContext
* instance. This method is called during during destruction of the associated FacesContext.
*
*
* @since 4.0
*/
public abstract void release();
}