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 javax.servlet.Servlet;
    27  import javax.servlet.ServletRequest;
    28  import javax.servlet.ServletResponse;
    29
    30  /**
    31   * <p>
    32   * The JspFactory is an abstract class that defines a number of factory
    33   * methods available to a JSP page at runtime for the purposes of creating
    34   * instances of various interfaces and classes used to support the JSP
    35   * implementation.
    36   * <p>
    37   * A conformant JSP Engine implementation will, during it's initialization
    38   * instantiate an implementation dependent subclass of this class, and make
    39   * it globally available for use by JSP implementation classes by registering
    40   * the instance created with this class via the
    41   * static <code> setDefaultFactory() </code> method.
    42   * <p>
    43   * The PageContext and the JspEngineInfo classes are the only implementation-dependent
    44   * classes that can be created from the factory.
    45   * <p>
    46   * JspFactory objects should not be used by JSP page authors.
    47   */
    48
    49  public abstract class JspFactory {
    50
    51      private static JspFactory deflt = null;
    52
    53      /**
    54       * Sole constructor. (For invocation by subclass constructors,
    55       * typically implicit.)
    56       */
    57      public JspFactory() {
    58      }
    59
    60      /**
    61       * <p>
    62       * set the default factory for this implementation. It is illegal for
    63       * any principal other than the JSP Engine runtime to call this method.
    64       * </p>
    65       *
    66       * @param deflt	The default factory implementation
    67       */
    68
    69      public static synchronized void setDefaultFactory(JspFactory deflt) {
    70  	JspFactory.deflt = deflt;
    71      }
    72
    73      /**
    74       * Returns the default factory for this implementation.
    75       *
    76       * @return the default factory for this implementation
    77       */
    78
    79      public static synchronized JspFactory getDefaultFactory() {
    80  	return deflt;
    81      }
    82
    83      /**
    84       * <p>
    85       * obtains an instance of an implementation dependent
    86       * javax.servlet.jsp.PageContext abstract class for the calling Servlet
    87       * and currently pending request and response.
    88       * </p>
    89       *
    90       * <p>
    91       * This method is typically called early in the processing of the
    92       * _jspService() method of a JSP implementation class in order to
    93       * obtain a PageContext object for the request being processed.
    94       * </p>
    95       * <p>
    96       * Invoking this method shall result in the PageContext.initialize()
    97       * method being invoked. The PageContext returned is properly initialized.
    98       * </p>
    99       * <p>
    100      * All PageContext objects obtained via this method shall be released
    101      * by invoking releasePageContext().
    102      * </p>
    103      *
    104      * @param servlet   the requesting servlet
    105      * @param request	the current request pending on the servlet
    106      * @param response	the current response pending on the servlet
    107      * @param errorPageURL the URL of the error page for the requesting JSP, or null
    108      * @param needsSession true if the JSP participates in a session
    109      * @param buffer	size of buffer in bytes, PageContext.NO_BUFFER if no buffer,
    110      *			PageContext.DEFAULT_BUFFER if implementation default.
    111      * @param autoflush	should the buffer autoflush to the output stream on buffer
    112      *			overflow, or throw an IOException?
    113      *
    114      * @return the page context
    115      *
    116      * @see javax.servlet.jsp.PageContext
    117      */
    118
    119     public abstract PageContext getPageContext(Servlet	       servlet,
    120 				    	       ServletRequest  request,
    121 				    	       ServletResponse response,
    122 				    	       String	       errorPageURL,
    123 				    	       boolean         needsSession,
    124 				    	       int             buffer,
    125 				    	       boolean         autoflush);
    126
    127     /**
    128      * <p>
    129      * called to release a previously allocated PageContext object.
    130      * Results in PageContext.release() being invoked.
    131      * This method should be invoked prior to returning from the _jspService() method of a JSP implementation
    132      * class.
    133      * </p>
    134      *
    135      * @param pc A PageContext previously obtained by getPageContext()
    136      */
    137
    138     public abstract void releasePageContext(PageContext pc);
    139
    140     /**
    141      * <p>
    142      * called to get implementation-specific information on the current JSP engine.
    143      * </p>
    144      *
    145      * @return a JspEngineInfo object describing the current JSP engine
    146      */
    147
    148     public abstract JspEngineInfo getEngineInfo();
    149 }