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