001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 package javax.servlet.jsp; 018 019 import java.util.Enumeration; 020 021 import javax.el.ELContext; 022 import javax.servlet.jsp.el.ExpressionEvaluator; 023 import javax.servlet.jsp.el.VariableResolver; 024 025 /** 026 * <p> 027 * <code>JspContext</code> serves as the base class for the 028 * PageContext class and abstracts all information that is not specific 029 * to servlets. This allows for Simple Tag Extensions to be used 030 * outside of the context of a request/response Servlet. 031 * <p> 032 * The JspContext provides a number of facilities to the 033 * page/component author and page implementor, including: 034 * <ul> 035 * <li>a single API to manage the various scoped namespaces 036 * <li>a mechanism to obtain the JspWriter for output 037 * <li>a mechanism to expose page directive attributes to the 038 * scripting environment 039 * </ul> 040 * 041 * <p><B>Methods Intended for Container Generated Code</B> 042 * <p> 043 * The following methods enable the <B>management of nested</B> JspWriter 044 * streams to implement Tag Extensions: <code>pushBody()</code> and 045 * <code>popBody()</code> 046 * 047 * <p><B>Methods Intended for JSP authors</B> 048 * <p> 049 * Some methods provide <B>uniform access</B> to the diverse objects 050 * representing scopes. 051 * The implementation must use the underlying machinery 052 * corresponding to that scope, so information can be passed back and 053 * forth between the underlying environment (e.g. Servlets) and JSP pages. 054 * The methods are: 055 * <code>setAttribute()</code>, <code>getAttribute()</code>, 056 * <code>findAttribute()</code>, <code>removeAttribute()</code>, 057 * <code>getAttributesScope()</code> and 058 * <code>getAttributeNamesInScope()</code>. 059 * 060 * <p> 061 * The following methods provide <B>convenient access</B> to implicit objects: 062 * <code>getOut()</code> 063 * 064 * <p> 065 * The following methods provide <B>programmatic access</b> to the 066 * Expression Language evaluator: 067 * <code>getExpressionEvaluator()</code>, <code>getVariableResolver()</code> 068 * 069 * @since 2.0 070 */ 071 072 public abstract class JspContext { 073 074 /** 075 * Sole constructor. (For invocation by subclass constructors, 076 * typically implicit.) 077 */ 078 public JspContext() { 079 } 080 081 /** 082 * Register the name and value specified with page scope semantics. 083 * If the value passed in is <code>null</code>, this has the same 084 * effect as calling 085 * <code>removeAttribute( name, PageContext.PAGE_SCOPE )</code>. 086 * 087 * @param name the name of the attribute to set 088 * @param value the value to associate with the name, or null if the 089 * attribute is to be removed from the page scope. 090 * @throws NullPointerException if the name is null 091 */ 092 093 abstract public void setAttribute(String name, Object value); 094 095 /** 096 * Register the name and value specified with appropriate 097 * scope semantics. If the value passed in is <code>null</code>, 098 * this has the same effect as calling 099 * <code>removeAttribute( name, scope )</code>. 100 * 101 * @param name the name of the attribute to set 102 * @param value the object to associate with the name, or null if 103 * the attribute is to be removed from the specified scope. 104 * @param scope the scope with which to associate the name/object 105 * 106 * @throws NullPointerException if the name is null 107 * @throws IllegalArgumentException if the scope is invalid 108 * @throws IllegalStateException if the scope is 109 * PageContext.SESSION_SCOPE but the page that was requested 110 * does not participate in a session or the session has been 111 * invalidated. 112 */ 113 114 abstract public void setAttribute(String name, Object value, int scope); 115 116 /** 117 * Returns the object associated with the name in the page scope or null 118 * if not found. 119 * 120 * @param name the name of the attribute to get 121 * @return the object associated with the name in the page scope 122 * or null if not found. 123 * 124 * @throws NullPointerException if the name is null 125 */ 126 127 abstract public Object getAttribute(String name); 128 129 /** 130 * Return the object associated with the name in the specified 131 * scope or null if not found. 132 * 133 * @param name the name of the attribute to set 134 * @param scope the scope with which to associate the name/object 135 * @return the object associated with the name in the specified 136 * scope or null if not found. 137 * 138 * @throws NullPointerException if the name is null 139 * @throws IllegalArgumentException if the scope is invalid 140 * @throws IllegalStateException if the scope is 141 * PageContext.SESSION_SCOPE but the page that was requested 142 * does not participate in a session or the session has been 143 * invalidated. 144 */ 145 146 abstract public Object getAttribute(String name, int scope); 147 148 /** 149 * Searches for the named attribute in page, request, session (if valid), 150 * and application scope(s) in order and returns the value associated or 151 * null. 152 * 153 * @param name the name of the attribute to search for 154 * @return the value associated or null 155 * @throws NullPointerException if the name is null 156 */ 157 158 abstract public Object findAttribute(String name); 159 160 /** 161 * Remove the object reference associated with the given name 162 * from all scopes. Does nothing if there is no such object. 163 * 164 * @param name The name of the object to remove. 165 * @throws NullPointerException if the name is null 166 */ 167 168 abstract public void removeAttribute(String name); 169 170 /** 171 * Remove the object reference associated with the specified name 172 * in the given scope. Does nothing if there is no such object. 173 * 174 * @param name The name of the object to remove. 175 * @param scope The scope where to look. 176 * @throws IllegalArgumentException if the scope is invalid 177 * @throws IllegalStateException if the scope is 178 * PageContext.SESSION_SCOPE but the page that was requested 179 * does not participate in a session or the session has been 180 * invalidated. 181 * @throws NullPointerException if the name is null 182 */ 183 184 abstract public void removeAttribute(String name, int scope); 185 186 /** 187 * Get the scope where a given attribute is defined. 188 * 189 * @param name the name of the attribute to return the scope for 190 * @return the scope of the object associated with the name specified or 0 191 * @throws NullPointerException if the name is null 192 */ 193 194 abstract public int getAttributesScope(String name); 195 196 /** 197 * Enumerate all the attributes in a given scope. 198 * 199 * @param scope the scope to enumerate all the attributes for 200 * @return an enumeration of names (java.lang.String) of all the 201 * attributes the specified scope 202 * @throws IllegalArgumentException if the scope is invalid 203 * @throws IllegalStateException if the scope is 204 * PageContext.SESSION_SCOPE but the page that was requested 205 * does not participate in a session or the session has been 206 * invalidated. 207 */ 208 209 abstract public Enumeration<String> getAttributeNamesInScope(int scope); 210 211 /** 212 * The current value of the out object (a JspWriter). 213 * 214 * @return the current JspWriter stream being used for client response 215 */ 216 abstract public JspWriter getOut(); 217 218 /** 219 * Provides programmatic access to the ExpressionEvaluator. 220 * The JSP Container must return a valid instance of an 221 * ExpressionEvaluator that can parse EL expressions. 222 * 223 * @return A valid instance of an ExpressionEvaluator. 224 * @since 2.0 225 */ 226 public abstract ExpressionEvaluator getExpressionEvaluator(); 227 228 229 public abstract ELContext getELContext(); 230 231 /** 232 * Returns an instance of a VariableResolver that provides access to the 233 * implicit objects specified in the JSP specification using this JspContext 234 * as the context object. 235 * 236 * @return A valid instance of a VariableResolver. 237 * @since 2.0 238 */ 239 public abstract VariableResolver getVariableResolver(); 240 241 /** 242 * Return a new JspWriter object that sends output to the 243 * provided Writer. Saves the current "out" JspWriter, 244 * and updates the value of the "out" attribute in the 245 * page scope attribute namespace of the JspContext. 246 * <p>The returned JspWriter must implement all methods and 247 * behave as though it were unbuffered. More specifically: 248 * <ul> 249 * <li>clear() must throw an IOException</li> 250 * <li>clearBuffer() does nothing</li> 251 * <li>getBufferSize() always returns 0</li> 252 * <li>getRemaining() always returns 0</li> 253 * </ul> 254 * </p> 255 * 256 * @param writer The Writer for the returned JspWriter to send 257 * output to. 258 * @return a new JspWriter that writes to the given Writer. 259 * @since 2.0 260 */ 261 public JspWriter pushBody( java.io.Writer writer ) { 262 return null; // XXX to implement 263 } 264 265 /** 266 * Return the previous JspWriter "out" saved by the matching 267 * pushBody(), and update the value of the "out" attribute in 268 * the page scope attribute namespace of the JspContext. 269 * 270 * @return the saved JspWriter. 271 */ 272 public JspWriter popBody() { 273 return null; // XXX to implement 274 } 275 }