View Javadoc

    1   /**
    2    *
    3    * Copyright 2003-2004 The Apache Software Foundation
    4    *
    5    *  Licensed under the Apache License, Version 2.0 (the "License");
    6    *  you may not use this file except in compliance with the License.
    7    *  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   *  Unless required by applicable law or agreed to in writing, software
    12   *  distributed under the License is distributed on an "AS IS" BASIS,
    13   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   *  See the License for the specific language governing permissions and
    15   *  limitations under the License.
    16   */
    17
    18  //
    19  // This source code implements specifications defined by the Java
    20  // Community Process. In order to remain compliant with the specification
    21  // DO NOT add / change / or delete method signatures!
    22  //
    23
    24  package javax.servlet.jsp;
    25
    26  import java.util.Enumeration;
    27
    28  import javax.servlet.jsp.el.ExpressionEvaluator;
    29  import javax.servlet.jsp.el.VariableResolver;
    30
    31  /**
    32   * <p>
    33   * <code>JspContext</code> serves as the base class for the
    34   * PageContext class and abstracts all information that is not specific
    35   * to servlets.  This allows for Simple Tag Extensions to be used
    36   * outside of the context of a request/response Servlet.
    37   * <p>
    38   * The JspContext provides a number of facilities to the
    39   * page/component author and page implementor, including:
    40   * <ul>
    41   * <li>a single API to manage the various scoped namespaces
    42   * <li>a mechanism to obtain the JspWriter for output
    43   * <li>a mechanism to expose page directive attributes to the
    44   *     scripting environment
    45   * </ul>
    46   *
    47   * <p><B>Methods Intended for Container Generated Code</B>
    48   * <p>
    49   * The following methods enable the <B>management of nested</B> JspWriter
    50   * streams to implement Tag Extensions: <code>pushBody()</code> and
    51   * <code>popBody()</code>
    52   *
    53   * <p><B>Methods Intended for JSP authors</B>
    54   * <p>
    55   * Some methods provide <B>uniform access</B> to the diverse objects
    56   * representing scopes.
    57   * The implementation must use the underlying machinery
    58   * corresponding to that scope, so information can be passed back and
    59   * forth between the underlying environment (e.g. Servlets) and JSP pages.
    60   * The methods are:
    61   * <code>setAttribute()</code>,  <code>getAttribute()</code>,
    62   * <code>findAttribute()</code>,  <code>removeAttribute()</code>,
    63   * <code>getAttributesScope()</code> and
    64   * <code>getAttributeNamesInScope()</code>.
    65   *
    66   * <p>
    67   * The following methods provide <B>convenient access</B> to implicit objects:
    68   * <code>getOut()</code>
    69   *
    70   * <p>
    71   * The following methods provide <B>programmatic access</b> to the
    72   * Expression Language evaluator:
    73   * <code>getExpressionEvaluator()</code>, <code>getVariableResolver()</code>
    74   *
    75   * @since 2.0
    76   */
    77
    78  public abstract class JspContext {
    79
    80      /**
    81       * Sole constructor. (For invocation by subclass constructors,
    82       * typically implicit.)
    83       */
    84      public JspContext() {
    85      }
    86
    87      /**
    88       * Register the name and value specified with page scope semantics.
    89       * If the value passed in is <code>null</code>, this has the same
    90       * effect as calling
    91       * <code>removeAttribute( name, PageContext.PAGE_SCOPE )</code>.
    92       *
    93       * @param name the name of the attribute to set
    94       * @param value the value to associate with the name, or null if the
    95       *     attribute is to be removed from the page scope.
    96       * @throws NullPointerException if the name is null
    97       */
    98
    99      abstract public void setAttribute(String name, Object value);
    100
    101     /**
    102      * Register the name and value specified with appropriate
    103      * scope semantics.  If the value passed in is <code>null</code>,
    104      * this has the same effect as calling
    105      * <code>removeAttribute( name, scope )</code>.
    106      *
    107      * @param name the name of the attribute to set
    108      * @param value the object to associate with the name, or null if
    109      *     the attribute is to be removed from the specified scope.
    110      * @param scope the scope with which to associate the name/object
    111      *
    112      * @throws NullPointerException if the name is null
    113      * @throws IllegalArgumentException if the scope is invalid
    114      * @throws IllegalStateException if the scope is
    115      *     PageContext.SESSION_SCOPE but the page that was requested
    116      *     does not participate in a session or the session has been
    117      *     invalidated.
    118      */
    119
    120     abstract public void setAttribute(String name, Object value, int scope);
    121
    122     /**
    123      * Returns the object associated with the name in the page scope or null
    124      * if not found.
    125      *
    126      * @param name the name of the attribute to get
    127      * @return the object associated with the name in the page scope
    128      *     or null if not found.
    129      *
    130      * @throws NullPointerException if the name is null
    131      */
    132
    133     abstract public Object getAttribute(String name);
    134
    135     /**
    136      * Return the object associated with the name in the specified
    137      * scope or null if not found.
    138      *
    139      * @param name the name of the attribute to set
    140      * @param scope the scope with which to associate the name/object
    141      * @return the object associated with the name in the specified
    142      *     scope or null if not found.
    143      *
    144      * @throws NullPointerException if the name is null
    145      * @throws IllegalArgumentException if the scope is invalid
    146      * @throws IllegalStateException if the scope is
    147      *     PageContext.SESSION_SCOPE but the page that was requested
    148      *     does not participate in a session or the session has been
    149      *     invalidated.
    150      */
    151
    152     abstract public Object getAttribute(String name, int scope);
    153
    154     /**
    155      * Searches for the named attribute in page, request, session (if valid),
    156      * and application scope(s) in order and returns the value associated or
    157      * null.
    158      *
    159      * @param name the name of the attribute to search for
    160      * @return the value associated or null
    161      * @throws NullPointerException if the name is null
    162      */
    163
    164     abstract public Object findAttribute(String name);
    165
    166     /**
    167      * Remove the object reference associated with the given name
    168      * from all scopes.  Does nothing if there is no such object.
    169      *
    170      * @param name The name of the object to remove.
    171      * @throws NullPointerException if the name is null
    172      */
    173
    174     abstract public void removeAttribute(String name);
    175
    176     /**
    177      * Remove the object reference associated with the specified name
    178      * in the given scope.  Does nothing if there is no such object.
    179      *
    180      * @param name The name of the object to remove.
    181      * @param scope The scope where to look.
    182      * @throws IllegalArgumentException if the scope is invalid
    183      * @throws IllegalStateException if the scope is
    184      *     PageContext.SESSION_SCOPE but the page that was requested
    185      *     does not participate in a session or the session has been
    186      *     invalidated.
    187      * @throws NullPointerException if the name is null
    188      */
    189
    190     abstract public void removeAttribute(String name, int scope);
    191
    192     /**
    193      * Get the scope where a given attribute is defined.
    194      *
    195      * @param name the name of the attribute to return the scope for
    196      * @return the scope of the object associated with the name specified or 0
    197      * @throws NullPointerException if the name is null
    198      */
    199
    200     abstract public int getAttributesScope(String name);
    201
    202     /**
    203      * Enumerate all the attributes in a given scope.
    204      *
    205      * @param scope the scope to enumerate all the attributes for
    206      * @return an enumeration of names (java.lang.String) of all the
    207      *     attributes the specified scope
    208      * @throws IllegalArgumentException if the scope is invalid
    209      * @throws IllegalStateException if the scope is
    210      *     PageContext.SESSION_SCOPE but the page that was requested
    211      *     does not participate in a session or the session has been
    212      *     invalidated.
    213      */
    214
    215     abstract public Enumeration getAttributeNamesInScope(int scope);
    216
    217     /**
    218      * The current value of the out object (a JspWriter).
    219      *
    220      * @return the current JspWriter stream being used for client response
    221      */
    222     abstract public JspWriter getOut();
    223
    224     /**
    225      * Provides programmatic access to the ExpressionEvaluator.
    226      * The JSP Container must return a valid instance of an
    227      * ExpressionEvaluator that can parse EL expressions.
    228      *
    229      * @return A valid instance of an ExpressionEvaluator.
    230      * @since 2.0
    231      */
    232     public abstract ExpressionEvaluator getExpressionEvaluator();
    233
    234     /**
    235      * Returns an instance of a VariableResolver that provides access to the
    236      * implicit objects specified in the JSP specification using this JspContext
    237      * as the context object.
    238      *
    239      * @return A valid instance of a VariableResolver.
    240      * @since 2.0
    241      */
    242     public abstract VariableResolver getVariableResolver();
    243
    244     /**
    245      * Return a new JspWriter object that sends output to the
    246      * provided Writer.  Saves the current "out" JspWriter,
    247      * and updates the value of the "out" attribute in the
    248      * page scope attribute namespace of the JspContext.
    249      * <p>The returned JspWriter must implement all methods and
    250      * behave as though it were unbuffered.  More specifically:
    251      * <ul>
    252      *   <li>clear() must throw an IOException</li>
    253      *   <li>clearBuffer() does nothing</li>
    254      *   <li>getBufferSize() always returns 0</li>
    255      *   <li>getRemaining() always returns 0</li>
    256      * </ul>
    257      * </p>
    258      *
    259      * @param writer The Writer for the returned JspWriter to send
    260      *     output to.
    261      * @return a new JspWriter that writes to the given Writer.
    262      * @since 2.0
    263      */
    264     public JspWriter pushBody( java.io.Writer writer ) {
    265         return null; // XXX to implement
    266     }
    267
    268     /**
    269      * Return the previous JspWriter "out" saved by the matching
    270      * pushBody(), and update the value of the "out" attribute in
    271      * the page scope attribute namespace of the JspContext.
    272      *
    273      * @return the saved JspWriter.
    274      */
    275     public JspWriter popBody() {
    276         return null; // XXX to implement
    277     }
    278 }