jakarta.servlet.jsp.JspContext Maven / Gradle / Ivy
/*
* Copyright (c) 1997, 2020 Oracle and/or its affiliates and others.
* All rights reserved.
* Copyright 2004 The Apache Software Foundation
*
* 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 jakarta.servlet.jsp;
import java.util.Enumeration;
import jakarta.el.ELContext;
/**
*
* JspContext serves as the base class for the PageContext class and abstracts all information that is not
* specific to servlets. This allows for Simple Tag Extensions to be used outside of the context of a request/response
* Servlet.
*
* The JspContext provides a number of facilities to the page/component author and page implementor, including:
*
* - a single API to manage the various scoped namespaces
*
- a mechanism to obtain the JspWriter for output
*
- a mechanism to expose page directive attributes to the scripting environment
*
*
*
* Methods Intended for Container Generated Code
*
* The following methods enable the management of nested JspWriter streams to implement Tag Extensions:
* pushBody() and popBody()
*
*
* Methods Intended for JSP authors
*
* Some methods provide uniform access to the diverse objects representing scopes. The implementation must use
* the underlying machinery corresponding to that scope, so information can be passed back and forth between the
* underlying environment (e.g. Servlets) and JSP pages. The methods are: setAttribute(),
* getAttribute(), findAttribute(), removeAttribute(),
* getAttributesScope() and getAttributeNamesInScope().
*
*
* The following methods provide convenient access to implicit objects: getOut()
*
*
* The following methods provide programmatic access to the Expression Language evaluator:
* getExpressionEvaluator(), getVariableResolver()
*
* @since JSP 2.0
*/
public abstract class JspContext {
/**
* Sole constructor. (For invocation by subclass constructors, typically implicit.)
*/
public JspContext() {
}
/**
* Register the name and value specified with page scope semantics. If the value passed in is null,
* this has the same effect as calling removeAttribute( name, PageContext.PAGE_SCOPE ).
*
* @param name the name of the attribute to set
* @param value the value to associate with the name, or null if the attribute is to be removed from the page scope.
* @throws NullPointerException if the name is null
*/
abstract public void setAttribute(String name, Object value);
/**
* Register the name and value specified with appropriate scope semantics. If the value passed in is
* null, this has the same effect as calling removeAttribute( name, scope ).
*
* @param name the name of the attribute to set
* @param value the object to associate with the name, or null if the attribute is to be removed from the specified
* scope.
* @param scope the scope with which to associate the name/object
*
* @throws NullPointerException if the name is null
* @throws IllegalArgumentException if the scope is invalid
* @throws IllegalStateException if the scope is PageContext.SESSION_SCOPE but the page that was requested does
* not participate in a session or the session has been invalidated.
*/
abstract public void setAttribute(String name, Object value, int scope);
/**
* Returns the object associated with the name in the page scope or null if not found.
*
* @param name the name of the attribute to get
* @return the object associated with the name in the page scope or null if not found.
*
* @throws NullPointerException if the name is null
*/
abstract public Object getAttribute(String name);
/**
* Return the object associated with the name in the specified scope or null if not found.
*
* @param name the name of the attribute to set
* @param scope the scope with which to associate the name/object
* @return the object associated with the name in the specified scope or null if not found.
*
* @throws NullPointerException if the name is null
* @throws IllegalArgumentException if the scope is invalid
* @throws IllegalStateException if the scope is PageContext.SESSION_SCOPE but the page that was requested does
* not participate in a session or the session has been invalidated.
*/
abstract public Object getAttribute(String name, int scope);
/**
* Searches for the named attribute in page, request, session (if valid), and application scope(s) in order and
* returns the value associated or null.
*
* @param name the name of the attribute to search for
* @return the value associated or null
* @throws NullPointerException if the name is null
*/
abstract public Object findAttribute(String name);
/**
* Remove the object reference associated with the given name from all scopes. Does nothing if there is no such
* object.
*
* @param name The name of the object to remove.
* @throws NullPointerException if the name is null
*/
abstract public void removeAttribute(String name);
/**
* Remove the object reference associated with the specified name in the given scope. Does nothing if there is no
* such object.
*
* @param name The name of the object to remove.
* @param scope The scope where to look.
* @throws IllegalArgumentException if the scope is invalid
* @throws IllegalStateException if the scope is PageContext.SESSION_SCOPE but the page that was requested does
* not participate in a session or the session has been invalidated.
* @throws NullPointerException if the name is null
*/
abstract public void removeAttribute(String name, int scope);
/**
* Get the scope where a given attribute is defined.
*
* @param name the name of the attribute to return the scope for
* @return the scope of the object associated with the name specified or 0
* @throws NullPointerException if the name is null
*/
abstract public int getAttributesScope(String name);
/**
* Enumerate all the attributes in a given scope.
*
* @param scope the scope to enumerate all the attributes for
* @return an enumeration of names (java.lang.String) of all the attributes the specified scope
* @throws IllegalArgumentException if the scope is invalid
* @throws IllegalStateException if the scope is PageContext.SESSION_SCOPE but the page that was requested does
* not participate in a session or the session has been invalidated.
*/
abstract public Enumeration getAttributeNamesInScope(int scope);
/**
* The current value of the out object (a JspWriter).
*
* @return the current JspWriter stream being used for client response
*/
abstract public JspWriter getOut();
/**
* Provides programmatic access to the ExpressionEvaluator. The JSP Container must return a valid instance of an
* ExpressionEvaluator that can parse EL expressions.
*
* @deprecated As of JSP 2.1, replaced by {@link JspApplicationContext#getExpressionFactory}
* @return A valid instance of an ExpressionEvaluator.
* @since JSP 2.0
*/
@Deprecated
public abstract jakarta.servlet.jsp.el.ExpressionEvaluator getExpressionEvaluator();
/**
* Returns an instance of a VariableResolver that provides access to the implicit objects specified in the JSP
* specification using this JspContext as the context object.
*
* @deprecated As of JSP 2.1, replaced by {@link ELContext#getELResolver}, which can be obtained by
* jspContext.getELContext().getELResolver().
* @return A valid instance of a VariableResolver.
* @since JSP 2.0
*/
@Deprecated
public abstract jakarta.servlet.jsp.el.VariableResolver getVariableResolver();
/**
* Returns the ELContext associated with this JspContext.
*
*
* The ELContext is created lazily and is reused if it already exists. There is a new
* ELContext for each JspContext.
*
*
*
* The ELContext must contain the ELResolver described in the JSP specification (and in
* the javadocs for {@link JspApplicationContext#addELResolver}).
*
*
* @return The ELContext associated with this JspContext.
* @since JSP 2.1
*/
public abstract ELContext getELContext();
/**
* Return a new JspWriter object that sends output to the provided Writer. Saves the current "out" JspWriter, and
* updates the value of the "out" attribute in the page scope attribute namespace of the JspContext.
*
* The returned JspWriter must implement all methods and behave as though it were unbuffered. More specifically:
*
*
* - clear() must throw an IOException
* - clearBuffer() does nothing
* - getBufferSize() always returns 0
* - getRemaining() always returns 0
*
*
* @param writer The Writer for the returned JspWriter to send output to.
* @return a new JspWriter that writes to the given Writer.
* @since JSP 2.0
*/
public JspWriter pushBody(java.io.Writer writer) {
return null; // XXX to implement
}
/**
* Return the previous JspWriter "out" saved by the matching pushBody(), and update the value of the "out" attribute
* in the page scope attribute namespace of the JspContext.
*
* @return the saved JspWriter.
*/
public JspWriter popBody() {
return null; // XXX to implement
}
}