1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. 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 package javax.servlet.jsp;
18
19 import javax.servlet.Servlet;
20 import javax.servlet.ServletContext;
21 import javax.servlet.ServletRequest;
22 import javax.servlet.ServletResponse;
23 import javax.servlet.jsp.PageContext;
24
25 /**
26 * <p>
27 * The JspFactory is an abstract class that defines a number of factory
28 * methods available to a JSP page at runtime for the purposes of creating
29 * instances of various interfaces and classes used to support the JSP
30 * implementation.
31 * <p>
32 * A conformant JSP Engine implementation will, during it's initialization
33 * instantiate an implementation dependent subclass of this class, and make
34 * it globally available for use by JSP implementation classes by registering
35 * the instance created with this class via the
36 * static <code> setDefaultFactory() </code> method.
37 * <p>
38 * The PageContext and the JspEngineInfo classes are the only implementation-dependent
39 * classes that can be created from the factory.
40 * <p>
41 * JspFactory objects should not be used by JSP page authors.
42 */
43
44 public abstract class JspFactory {
45
46 private static volatile JspFactory deflt = null;
47
48 /**
49 * Sole constructor. (For invocation by subclass constructors,
50 * typically implicit.)
51 */
52 public JspFactory() {
53 }
54
55 /**
56 * <p>
57 * set the default factory for this implementation. It is illegal for
58 * any principal other than the JSP Engine runtime to call this method.
59 * </p>
60 *
61 * @param deflt The default factory implementation
62 */
63
64 public static void setDefaultFactory(JspFactory deflt) {
65 JspFactory.deflt = deflt;
66 }
67
68 /**
69 * Returns the default factory for this implementation.
70 *
71 * @return the default factory for this implementation
72 */
73
74 public static JspFactory getDefaultFactory() {
75 return deflt;
76 }
77
78 /**
79 * <p>
80 * obtains an instance of an implementation dependent
81 * javax.servlet.jsp.PageContext abstract class for the calling Servlet
82 * and currently pending request and response.
83 * </p>
84 *
85 * <p>
86 * This method is typically called early in the processing of the
87 * _jspService() method of a JSP implementation class in order to
88 * obtain a PageContext object for the request being processed.
89 * </p>
90 * <p>
91 * Invoking this method shall result in the PageContext.initialize()
92 * method being invoked. The PageContext returned is properly initialized.
93 * </p>
94 * <p>
95 * All PageContext objects obtained via this method shall be released
96 * by invoking releasePageContext().
97 * </p>
98 *
99 * @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 }