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