1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.myfaces.renderkit.html.util;
20
21 import javax.faces.context.FacesContext;
22 import javax.servlet.ServletContext;
23 import javax.servlet.http.HttpServletRequest;
24 import javax.servlet.http.HttpServletResponse;
25 import java.io.IOException;
26
27 /**
28 * This interface defines methods necessary to render links to resources used
29 * by custom components.
30 * Mostly used to avoid having to include [script src="..."][/script]
31 * in the head of the pages before using a component.
32 *
33 * @author Sylvain Vieujot (latest modification by $Author: skitching $)
34 * @version $Revision: 673833 $ $Date: 2008-07-03 16:58:05 -0500 (Thu, 03 Jul 2008) $
35 */
36 public interface AddResource
37 {
38 public static final ResourcePosition HEADER_BEGIN = new ResourcePosition(0);
39
40 public static final ResourcePosition BODY_END = new ResourcePosition(1);
41
42 public static final ResourcePosition BODY_ONLOAD = new ResourcePosition(2);
43
44 // Methods to add resources
45
46 /**
47 * set the context path of the web-app
48 */
49 public void setContextPath(String contextPath);
50
51 /**
52 * Insert a [script src="url"] entry at the current location in the response.
53 * The resource is expected to be in the classpath, at the same location as the
54 * specified component + "/resource".
55 * <p>
56 * Example: when customComponent is class example.Widget, and
57 * resourceName is script.js, the resource will be retrieved from
58 * "example/Widget/resource/script.js" in the classpath.
59 */
60 public void addJavaScriptHere(FacesContext context, Class myfacesCustomComponent,
61 String resourceName) throws IOException;
62
63 /**
64 * Insert a [script src="url"] entry at the current location in the response.
65 *
66 * @param uri is the location of the desired resource, relative to the base
67 * directory of the webapp (ie its contextPath).
68 */
69 public void addJavaScriptHere(FacesContext context, String uri) throws IOException;
70
71 /**
72 * Insert a [script src="url"] entry at the current location in the response.<br />
73 * In constrast to the other methods this will not encode the url. So
74 * ,depending on the use case, it wont work in cookie-only environments.
75 *
76 * @param uri is the location of the desired resource, relative to the base
77 * directory of the webapp (ie its contextPath).
78 * @deprecated just to help to workaround a dojo bug
79 */
80 public void addJavaScriptHerePlain(FacesContext context, String uri) throws IOException;
81
82 /**
83 * Insert a [script src="url"] entry at the current location in the response.
84 *
85 * @param context
86 *
87 * @param resourceHandler is an object which specifies exactly how to build the url
88 * that is emitted into the script tag. Code which needs to generate URLs in ways
89 * that this class does not support by default can implement a custom ResourceHandler.
90 *
91 * @throws IOException
92 */
93 public void addJavaScriptHere(FacesContext context, ResourceHandler resourceHandler)
94 throws IOException;
95
96 public void addResourceHere(FacesContext context, ResourceHandler resourceHandler)
97 throws IOException;
98
99 /**
100 * Adds the given Javascript resource to the document header at the specified
101 * document positioy by supplying a resourcehandler instance.
102 * <p>
103 * Use this method to have full control about building the reference url
104 * to identify the resource and to customize how the resource is
105 * written to the response. In most cases, however, one of the convenience
106 * methods on this class can be used without requiring a custom ResourceHandler
107 * to be provided.
108 * <p>
109 * If the script has already been referenced, it's added only once.
110 * <p>
111 * Note that this method <i>queues</i> the javascript for insertion, and that
112 * the script is inserted into the buffered response by the ExtensionsFilter
113 * after the page is complete.
114 */
115 public void addJavaScriptAtPosition(FacesContext context, ResourcePosition position,
116 ResourceHandler resourceHandler);
117
118 /**
119 * Insert a [script src="url"] entry into the document header at the
120 * specified document position. If the script has already been
121 * referenced, it's added only once.
122 * <p>
123 * The resource is expected to be in the classpath, at the same location as the
124 * specified component + "/resource".
125 * <p>
126 * Example: when customComponent is class example.Widget, and
127 * resourceName is script.js, the resource will be retrieved from
128 * "example/Widget/resource/script.js" in the classpath.
129 */
130 public void addJavaScriptAtPosition(FacesContext context, ResourcePosition position,
131 Class myfacesCustomComponent, String resourceName);
132
133 /**
134 * Insert a [script src="url"] entry into the document header at the
135 * specified document position. If the script has already been
136 * referenced, it's added only once.
137 *
138 * @param defer specifies whether the html attribute "defer" is set on the
139 * generated script tag. If this is true then the browser will continue
140 * processing the html page without waiting for the specified script to
141 * load and be run.
142 */
143 public void addJavaScriptAtPosition(FacesContext context, ResourcePosition position,
144 Class myfacesCustomComponent, String resourceName, boolean defer);
145
146 /**
147 * Insert a [script src="url"] entry into the document header at the
148 * specified document position. If the script has already been
149 * referenced, it's added only once.
150 *
151 * @param uri is the location of the desired resource, relative to the base
152 * directory of the webapp (ie its contextPath).
153 */
154 public void addJavaScriptAtPosition(FacesContext context, ResourcePosition position, String uri);
155
156 /**
157 * Adds the given Javascript resource at the specified document position.
158 * If the script has already been referenced, it's added only once.
159 */
160 public void addJavaScriptAtPosition(FacesContext context, ResourcePosition position, String uri,
161 boolean defer);
162
163 public void addJavaScriptToBodyTag(FacesContext context, String javascriptEventName,
164 String addedJavaScript);
165
166 /**
167 * Adds the given Javascript resource at the specified document position.
168 * If the script has already been referenced, it's added only once.
169 */
170 public void addJavaScriptAtPosition(FacesContext context, ResourcePosition position,
171 ResourceHandler resourceHandler, boolean defer);
172
173 /**
174 * Adds the given Javascript resource at the specified document position.
175 * If the script has already been referenced, it's added only once.<br />
176 * In constrast to the other methods this will not encode the url. So
177 * ,depending on the use case, it wont work in cookie-only environments.
178 *
179 * @deprecated just to help to workaround a dojo bug
180 */
181 public void addJavaScriptAtPositionPlain(FacesContext context, ResourcePosition position,
182 Class myfacesCustomComponent, String resourceName);
183
184 /**
185 * Adds the given Style Sheet at the specified document position.
186 * If the style sheet has already been referenced, it's added only once.
187 */
188 public void addStyleSheet(FacesContext context, ResourcePosition position,
189 Class myfacesCustomComponent, String resourceName);
190
191 /**
192 * Adds the given Style Sheet at the specified document position.
193 * If the style sheet has already been referenced, it's added only once.
194 */
195 public void addStyleSheet(FacesContext context, ResourcePosition position, String uri);
196
197 /**
198 * Adds the given Style Sheet at the specified document position.
199 * If the style sheet has already been referenced, it's added only once.
200 */
201 public void addStyleSheet(FacesContext context, ResourcePosition position,
202 ResourceHandler resourceHandler);
203
204 /**
205 * Adds the given Inline Style at the specified document position.
206 */
207 public void addInlineStyleAtPosition(FacesContext context, ResourcePosition position, String inlineStyle);
208
209 /**
210 * Adds the given Inline Script at the specified document position.
211 */
212 public void addInlineScriptAtPosition(FacesContext context, ResourcePosition position,
213 String inlineScript);
214
215 /**
216 * Return a URI that can be embedded into an HTML page to reference a resource
217 * from a Tomahawk jarfile.
218 * <p>
219 * This method is intended for internal use by the Tomahawk project only,
220 * and will not serve resources for other projects (unless a custom
221 * AddResource implementation has been configured). Non-tomahawk code should
222 * use the variants that take an explicit ResourceHandler class.
223 * <p>
224 * Parameter myfacesCustomComponent is a tomahawk class that the resource
225 * is associated with. The resource is then expected to be in the classpath
226 * in the same package as the specified class (or a subpackage).
227 * <p>
228 * Parameter resource is a path relative to the .class file of the specified
229 * myfacesCustomComponent class.
230 *
231 * Param withContextPath controls whether the webapp name is prefixed to
232 * the generated url.
233 */
234 public String getResourceUri(FacesContext context, Class myfacesCustomComponent,
235 String resource, boolean withContextPath);
236
237 public String getResourceUri(FacesContext context, Class myfacesCustomComponent, String resource);
238
239 /**
240 * Get the Path used to retrieve an resource.
241 */
242 public String getResourceUri(FacesContext context, ResourceHandler resourceHandler);
243
244 /**
245 * Get the Path used to retrieve an resource.
246 */
247 public String getResourceUri(FacesContext context, ResourceHandler resourceHandler,
248 boolean withContextPath);
249
250 /**
251 * Get the Path used to retrieve an resource.
252 */
253 public String getResourceUri(FacesContext context, String uri);
254
255 /**
256 * Get the Path used to retrieve an resource.
257 */
258 public String getResourceUri(FacesContext context, String uri, boolean withContextPath);
259
260
261 public boolean isResourceUri(ServletContext servletContext, HttpServletRequest request);
262
263 public void serveResource(ServletContext context, HttpServletRequest request,
264 HttpServletResponse response) throws IOException;
265
266 /**
267 * Parses the response to mark the positions where code will be inserted
268 */
269 public void parseResponse(HttpServletRequest request, String bufferedResponse,
270 HttpServletResponse response) throws IOException;
271
272 /**
273 * Writes the javascript code necessary for myfaces in every page, just befode the closing </body> tag
274 */
275 public void writeMyFacesJavascriptBeforeBodyEnd(HttpServletRequest request,
276 HttpServletResponse response) throws IOException;
277
278 /**
279 * Add the resources to the <head> of the page.
280 * If the head tag is missing, but the <body> tag is present, the head tag is added.
281 * If both are missing, no resource is added.
282 *
283 * The ordering is such that the user header CSS & JS override the MyFaces' ones.
284 */
285 public void writeWithFullHeader(HttpServletRequest request,
286 HttpServletResponse response) throws IOException;
287
288 /**
289 * Writes the response
290 */
291 public void writeResponse(HttpServletRequest request,
292 HttpServletResponse response) throws IOException;
293
294 /**
295 * return true if you require the complete response buffered
296 */
297 public boolean requiresBuffer();
298
299 /**
300 * called when the response start
301 */
302 public void responseStarted();
303
304 /**
305 * called when the response has finished
306 */
307 public void responseFinished();
308
309 /**
310 * check there is something to write to the header
311 */
312 public boolean hasHeaderBeginInfos();
313 }