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 }