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 javax.servlet.Servlet;
029    import javax.servlet.ServletRequest;
030    import javax.servlet.ServletResponse;
031    import javax.servlet.jsp.PageContext;
032    
033    /**
034     * <p>
035     * The JspFactory is an abstract class that defines a number of factory
036     * methods available to a JSP page at runtime for the purposes of creating
037     * instances of various interfaces and classes used to support the JSP 
038     * implementation.
039     * <p>
040     * A conformant JSP Engine implementation will, during it's initialization
041     * instantiate an implementation dependent subclass of this class, and make 
042     * it globally available for use by JSP implementation classes by registering
043     * the instance created with this class via the
044     * static <code> setDefaultFactory() </code> method.
045     * <p>
046     * The PageContext and the JspEngineInfo classes are the only implementation-dependent
047     * classes that can be created from the factory.
048     * <p>
049     * JspFactory objects should not be used by JSP page authors.
050     */
051    
052    public abstract class JspFactory {
053    
054        private static JspFactory deflt = null;
055        
056        /**
057         * Sole constructor. (For invocation by subclass constructors, 
058         * typically implicit.)
059         */
060        public JspFactory() {
061        }
062    
063        /**
064         * <p>
065         * set the default factory for this implementation. It is illegal for
066         * any principal other than the JSP Engine runtime to call this method.
067         * </p>
068         *
069         * @param deflt     The default factory implementation
070         */
071    
072        public static synchronized void setDefaultFactory(JspFactory deflt) {
073            JspFactory.deflt = deflt;
074        }
075    
076        /**
077         * Returns the default factory for this implementation.
078         *
079         * @return the default factory for this implementation
080         */
081    
082        public static synchronized JspFactory getDefaultFactory() {
083            return deflt;
084        }
085    
086        /**
087         * <p>
088         * obtains an instance of an implementation dependent 
089         * javax.servlet.jsp.PageContext abstract class for the calling Servlet
090         * and currently pending request and response.
091         * </p>
092         *
093         * <p>
094         * This method is typically called early in the processing of the 
095         * _jspService() method of a JSP implementation class in order to 
096         * obtain a PageContext object for the request being processed.
097         * </p>
098         * <p>
099         * Invoking this method shall result in the PageContext.initialize()
100         * method being invoked. The PageContext returned is properly initialized.
101         * </p>
102         * <p>
103         * All PageContext objects obtained via this method shall be released
104         * by invoking releasePageContext().
105         * </p>
106         *
107         * @param servlet   the requesting servlet
108         * @param request   the current request pending on the servlet
109         * @param response  the current response pending on the servlet
110         * @param errorPageURL the URL of the error page for the requesting JSP, or null
111         * @param needsSession true if the JSP participates in a session
112         * @param buffer    size of buffer in bytes, PageContext.NO_BUFFER if no buffer,
113         *                  PageContext.DEFAULT_BUFFER if implementation default.
114         * @param autoflush should the buffer autoflush to the output stream on buffer
115         *                  overflow, or throw an IOException?
116         *
117         * @return the page context
118         *
119         * @see javax.servlet.jsp.PageContext
120         */
121    
122        public abstract PageContext getPageContext(Servlet         servlet,
123                                                   ServletRequest  request,
124                                                   ServletResponse response,
125                                                   String          errorPageURL,
126                                                   boolean         needsSession,
127                                                   int             buffer,
128                                                   boolean         autoflush);
129    
130        /**
131         * <p>
132         * called to release a previously allocated PageContext object.
133         * Results in PageContext.release() being invoked.
134         * This method should be invoked prior to returning from the _jspService() method of a JSP implementation
135         * class.
136         * </p>
137         *
138         * @param pc A PageContext previously obtained by getPageContext()
139         */
140    
141        public abstract void releasePageContext(PageContext pc);
142    
143        /**
144         * <p>
145         * called to get implementation-specific information on the current JSP engine.
146         * </p>
147         *
148         * @return a JspEngineInfo object describing the current JSP engine
149         */
150        
151        public abstract JspEngineInfo getEngineInfo();
152    }