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