View Javadoc

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 &lt;/body&gt; tag
274      */
275     public void writeMyFacesJavascriptBeforeBodyEnd(HttpServletRequest request,
276             HttpServletResponse response) throws IOException;
277 
278     /**
279      * Add the resources to the &lt;head&gt; of the page.
280      * If the head tag is missing, but the &lt;body&gt; 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 }