1 package com.atlassian.plugin.webresource;
2
3 import com.atlassian.plugin.ModuleDescriptor;
4
5 import java.io.Writer;
6
7 /**
8 * Manage 'css', 'javascript' and other 'resources' that are usually linked at the top of pages using {@code <script>
9 * and <link>} tags.
10 * <p/>
11 * By using the WebResourceManager, components can declare dependencies on javascript and css that they would otherwise
12 * have to embed inline (which means that it can't be cached, and are often duplicated in a page).
13 */
14 public interface WebResourceManager
15 {
16 /**
17 * Indicates that a given plugin web resource is required. All resources called via this method must be included
18 * when {@link #includeResources(Writer)} is called.
19 *
20 * @param moduleCompleteKey The fully qualified plugin web resource module (eg <code>jira.webresources:scriptaculous</code>)
21 * @see #includeResources(Writer, UrlMode)
22 */
23 void requireResource(String moduleCompleteKey);
24
25 /**
26 * Writes out the resource tags to the previously required resources called via {@link #requireResource(String)}. If
27 * you need it as a String to embed the tags in a template, use {@link #getRequiredResources()}.
28 * <p/>
29 * Example - if a 'javascript' resource has been required earlier with requireResource(), this method should
30 * output:
31 * <pre>
32 * {@literal <script type="text/javascript" src="$contextPath/scripts/javascript.js"></script>}
33 * </pre>
34 * Similarly for other supported resources
35 * <p/>
36 * In general, the behavior of this method should be equivalent to calling {@link #includeResources(Writer,
37 * UrlMode)} with a {@code urlMode} value of {@link UrlMode#AUTO}.
38 *
39 * @param writer The writer to write the links to
40 * @deprecated As of 2.3.0, replaced by {@link #includeResources(Writer, UrlMode)}
41 */
42 @Deprecated
43 void includeResources(Writer writer);
44
45 /**
46 * Writes out the resource tags for a specified set of required resources and their dependencies. Does not write out
47 * tags for resources specified in calls to {@link #requireResource(String)}.
48 *
49 * @param moduleCompleteKeys The set of web resource modules to include
50 * @param writer the writer to write the links to
51 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to
52 * decide
53 * @since 2.4.0
54 */
55 void includeResources(Iterable<String> moduleCompleteKeys, Writer writer, UrlMode urlMode);
56
57 /**
58 * This is the equivalent of calling {@link #includeResources(Writer, UrlMode, WebResourceFilter)} with
59 * the given url mode and a default web resource filter that is dependent on the implementation.
60 *
61 * @see #includeResources(Writer, UrlMode, WebResourceFilter)
62 * @since 2.3.0
63 */
64 void includeResources(Writer writer, UrlMode urlMode);
65
66 /**
67 * Writes out the resource tags to the previously required resources called via {@link #requireResource(String)} for
68 * the specified resource type. If you need it as a String to embed the tags in a template, use
69 * {@link #getRequiredResources(UrlMode)}.
70 * <p/>
71 * Example - if a 'javascript' resource has been required earlier with requireResource() and this method is called
72 * with {@link JavascriptWebResource.FILTER_INSTANCE}, it should output:
73 * <pre>
74 * {@literal <script type="text/javascript" src="$contextPath/scripts/javascript.js"></script>}
75 * </pre>
76 * Similarly for other supported resources.
77 * <p/>
78 * This method formats resource URLs in either relative or absolute format, depending on the value of {@code
79 * urlMode}. See {@link UrlMode} for details of the different options for URL format.
80 *
81 * @param writer the writer to write the links to
82 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to
83 * decide
84 * @param webResourceFilter the web resource filter to filter resources on
85 * @since 2.4
86 */
87 void includeResources(Writer writer, UrlMode urlMode, WebResourceFilter webResourceFilter);
88
89 /**
90 * Returns the resource tags for the previously required resources called via {@link #requireResource(String)}. If
91 * you are outputting the value to a {@link Writer}, use {@link #includeResources(Writer)}.
92 * <p/>
93 * Example - if a 'javascript' resource has been required earlier with requireResource(), this method should
94 * return:
95 * <pre>
96 * {@literal <script type="text/javascript" src="$contextPath/scripts/javascript.js"></script>}
97 * </pre>
98 * Similarly for other supported resources
99 * <p/>
100 * In general, the behavior of this method should be equivalent to calling {@link #getRequiredResources(UrlMode)}
101 * with a {@code urlMode} value of {@link UrlMode#AUTO}.
102 *
103 * @return the resource tags for all resources previously required
104 * @see #includeResources(Writer)
105 * @deprecated As of 2.3.0, replaced by {@link #getRequiredResources(UrlMode)}
106 */
107 @Deprecated
108 String getRequiredResources();
109
110 /**
111 * This is the equivalent of calling {@link #getRequiredResources(UrlMode, WebResourceFilter)} with the given url
112 * mode and a default filter that is dependent on the implementation.
113 *
114 * @return the resource tags for all resources previously required
115 * @see #includeResources(Writer, UrlMode)
116 * @see #getRequiredResources(UrlMode, WebResourceFilter)
117 * @since 2.3.1
118 */
119 String getRequiredResources(UrlMode urlMode);
120
121 /**
122 * Returns the resource tags for the previously required resources called via {@link #requireResource(String)} that
123 * match the specified web resource filter. If you are outputting the value to a {@link Writer}, use
124 * {@link #includeResources(Writer, UrlMode)}.
125 * <p/>
126 * Example - if a 'javascript' resource has been required earlier with requireResource() and this method is called
127 * with {@link JavascriptWebResource.FILTER_INSTANCE}, it should return:
128 * <pre>
129 * {@literal <script type="text/javascript" src="$contextPath/scripts/javascript.js"></script>}
130 * </pre>
131 * Similarly for other supported resources.
132 * <p/>
133 * This method formats resource URLs in either relative or absolute format, depending on the value of {@code
134 * urlMode}. See {@link UrlMode} for details of the different options for URL format.
135 * <p/>
136 *
137 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to
138 * decide
139 * @param webResourceFilter the web resource filter to filter resources on
140 * @return the resource tags for all resources previously required
141 * @see #includeResources(Writer, UrlMode, WebResourceFilter)
142 * @since 2.4
143 */
144 String getRequiredResources(UrlMode urlMode, WebResourceFilter webResourceFilter);
145
146 /**
147 * Writes the resource tags of the specified resource to the writer. If you need it as a String to embed the tags in
148 * a template, use {@link #getResourceTags(String)}.
149 * <p/>
150 * In general, the behavior of this method should be equivalent to calling {@link #requireResource(String, Writer,
151 * UrlMode)} with a {@code urlMode} value of {@link UrlMode#AUTO}.
152 *
153 * @param moduleCompleteKey The fully qualified plugin web resource module (eg <code>jira.webresources:scriptaculous</code>)
154 * @param writer The writer to write the resource tags to.
155 * @deprecated As of 2.3.0, replaced by {@link #requireResource(String, Writer, UrlMode)}
156 */
157 @Deprecated
158 void requireResource(String moduleCompleteKey, Writer writer);
159
160 /**
161 * Writes the resource tags of the specified resource to the writer. If you need it as a String to embed the tags in
162 * a template, use {@link #getResourceTags(String, UrlMode)}.
163 * <p/>
164 * This method formats resource URLs in either relative or absolute format, depending on the value of {@code
165 * urlMode}. See {@link UrlMode} for details of the different options for URL format.
166 *
167 * @param moduleCompleteKey The fully qualified plugin web resource module (eg <code>jira.webresources:scriptaculous</code>)
168 * @param writer The writer to write the resource tags to.
169 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
170 * implementation to decide
171 * @since 2.3.0
172 */
173 void requireResource(String moduleCompleteKey, Writer writer, UrlMode urlMode);
174
175 /**
176 * Writes the resource tags of all resources that have the given context specified in their descriptor.
177 *
178 * @param context The name of the context for which you want to require resources (eg "atl.admin")
179 * @since 2.5.0
180 */
181 void requireResourcesForContext(String context);
182
183 /**
184 * Returns the resource tags of the specified resource. If you are outputting the value to a {@link Writer}, use
185 * {@link #requireResource(String, java.io.Writer)}.
186 * <p/>
187 * In general, the behavior of this method should be equivalent to calling {@link #getResourceTags(String, UrlMode)}
188 * with a {@code urlMode} value of {@link UrlMode#AUTO}.
189 *
190 * @param moduleCompleteKey The fully qualified plugin web resource module (eg <code>jira.webresources:scriptaculous</code>)
191 * @return the resource tags for the specified resource
192 * @see #requireResource(String, Writer)
193 * @since 2.2
194 * @deprecated As of 2.3.0, replaced by {@link #getResourceTags(String, UrlMode)}
195 */
196 @Deprecated
197 String getResourceTags(String moduleCompleteKey);
198
199 /**
200 * Returns the resource tags of the specified resource. If you are outputting the value to a {@link Writer}, use
201 * {@link #requireResource(String, java.io.Writer, UrlMode)}.
202 * <p/>
203 * This method formats resource URLs in either relative or absolute format, depending on the value of {@code
204 * urlMode}. See {@link UrlMode} for details of the different options for URL format.
205 *
206 * @param moduleCompleteKey The fully qualified plugin web resource module (eg <code>jira.webresources:scriptaculous</code>)
207 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
208 * implementation to decide
209 * @return the resource tags for the specified resource
210 * @see #requireResource(String, Writer, UrlMode)
211 * @since 2.3.0
212 */
213 String getResourceTags(String moduleCompleteKey, UrlMode urlMode);
214
215 /**
216 * A helper method to return a prefix for 'system' static resources. Generally the implementation will return
217 * <p/>
218 * {@code /s/{build num}/{system counter}/_}
219 * <p/>
220 * Note that the servlet context is prepended, and there is no trailing slash.
221 * <p/>
222 * Typical usage is to replace:
223 * <p/>
224 * {@code <%= request.getContextPath() %>/styles/global.css} with {@code <%= webResourceManager.getStaticResourcePrefix()
225 * %>/styles/global.css}
226 * <p/>
227 * In general, the behavior of this method should be equivalent to calling {@link #getStaticResourcePrefix(UrlMode)}
228 * with a {@code urlMode} value of {@link UrlMode#AUTO}.
229 *
230 * @return A prefix that can be used to prefix 'static system' resources.
231 * @deprecated As of 2.3.0, replaced by {@link #getStaticResourcePrefix(UrlMode)}
232 */
233 @Deprecated
234 String getStaticResourcePrefix();
235
236 /**
237 * A helper method to return a prefix for 'system' static resources. Generally the implementation will return
238 * <p/>
239 * {@code /s/{build num}/{system counter}/_}
240 * <p/>
241 * Note that the servlet context is prepended, and there is no trailing slash.
242 * <p/>
243 * Typical usage is to replace:
244 * <p/>
245 * {@code <%= request.getContextPath() %>/styles/global.css} with {@code <%= webResourceManager.getStaticResourcePrefix()
246 * %>/styles/global.css}
247 * <p/>
248 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
249 * See {@link UrlMode} for details of the different options for URL format.
250 *
251 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to
252 * decide
253 * @return A prefix that can be used to prefix 'static system' resources.
254 * @since 2.3.0
255 */
256 String getStaticResourcePrefix(UrlMode urlMode);
257
258 /**
259 * A helper method to return a prefix for 'system' static resources. This method should be used for resources that
260 * change more frequently than system resources, and therefore have their own resource counter.
261 * <p/>
262 * Generally the implementation will return
263 * <p/>
264 * {@code /s/{build num}/{system counter}/{resource counter}/_}
265 * <p/>
266 * Note that the servlet context is prepended, and there is no trailing slash.
267 * <p/>
268 * Typical usage is to replace:
269 * <p/>
270 * {@code <%= request.getContextPath() %>/styles/global.css} with {@code <%= webResourceManager.getStaticResourcePrefix(resourceCounter)
271 * %>/styles/global.css}
272 * <p/>
273 * In general, the behavior of this method should be equivalent to calling {@link #getStaticResourcePrefix(String,
274 * UrlMode)} with a {@code urlMode} value of {@link UrlMode#AUTO}.
275 *
276 * @param resourceCounter A number that represents the unique version of the resource you require. Every time this
277 * resource changes, you need to increment the resource counter
278 * @return A prefix that can be used to prefix 'static system' resources.
279 * @deprecated As of 2.3.0, replaced by {@link #getStaticResourcePrefix(String, UrlMode)}
280 */
281 @Deprecated
282 String getStaticResourcePrefix(String resourceCounter);
283
284 /**
285 * A helper method to return a prefix for 'system' static resources. This method should be used for resources that
286 * change more frequently than system resources, and therefore have their own resource counter.
287 * <p/>
288 * Generally the implementation will return
289 * <p/>
290 * {@code /s/{build num}/{system counter}/{resource counter}/_}
291 * <p/>
292 * Note that the servlet context is prepended, and there is no trailing slash.
293 * <p/>
294 * Typical usage is to replace:
295 * <p/>
296 * {@code <%= request.getContextPath() %>/styles/global.css} with {@code <%= webResourceManager.getStaticResourcePrefix(resourceCounter)
297 * %>/styles/global.css}
298 * <p/>
299 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
300 * See {@link UrlMode} for details of the different options for URL format.
301 *
302 * @param resourceCounter A number that represents the unique version of the resource you require. Every time this
303 * resource changes, you need to increment the resource counter
304 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
305 * implementation to decide
306 * @return A prefix that can be used to prefix 'static system' resources.
307 * @since 2.3.0
308 */
309 String getStaticResourcePrefix(String resourceCounter, UrlMode urlMode);
310
311 /**
312 * A helper method to return a url for 'plugin' resources. Generally the implementation will return
313 * <p/>
314 * {@code /s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name}
315 * <p/>
316 * Note that the servlet context is prepended, and there is no trailing slash.
317 * <p/>
318 * Typical usage is to replace:
319 * <p/>
320 * {@code <%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name} with {@code <%=
321 * webResourceManager.getStaticPluginResource(descriptor, resourceName) %>}
322 * <p/>
323 * In general, the behavior of this method should be equivalent to calling {@link #getStaticPluginResource(String,
324 * String, UrlMode)} with a {@code urlMode} value of {@link UrlMode#AUTO}.
325 *
326 * @param moduleCompleteKey complete plugin module key
327 * @param resourceName the name of the resource as defined in the plugin manifest
328 * @return A url that can be used to request 'plugin' resources.
329 * @deprecated As of 2.3.0, replaced by {@link #getStaticPluginResource(String, String, UrlMode)}
330 */
331 @Deprecated
332 String getStaticPluginResource(String moduleCompleteKey, String resourceName);
333
334 /**
335 * A helper method to return a url for 'plugin' resources. Generally the implementation will return
336 * <p/>
337 * {@code /s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name}
338 * <p/>
339 * Note that the servlet context is prepended, and there is no trailing slash.
340 * <p/>
341 * Typical usage is to replace:
342 * <p/>
343 * {@code <%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name} with {@code <%=
344 * webResourceManager.getStaticPluginResource(descriptor, resourceName) %>}
345 * <p/>
346 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
347 * See {@link UrlMode} for details of the different options for URL format.
348 *
349 * @param moduleCompleteKey complete plugin module key
350 * @param resourceName the name of the resource as defined in the plugin manifest
351 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
352 * implementation to decide
353 * @return A url that can be used to request 'plugin' resources.
354 * @since 2.3.0
355 */
356 String getStaticPluginResource(String moduleCompleteKey, String resourceName, UrlMode urlMode);
357
358 /**
359 * A helper method to return a url for 'plugin' resources. Generally the implementation will return
360 * <p/>
361 * {@code /s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name}
362 * <p/>
363 * Note that the servlet context is prepended, and there is no trailing slash.
364 * <p/>
365 * Typical usage is to replace:
366 * <p/>
367 * {@code <%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name} with {@code <%=
368 * webResourceManager.getStaticPluginResource(descriptor, resourceName) %>}
369 * <p/>
370 * In general, the behavior of this method should be equivalent to calling {@link
371 * #getStaticPluginResource(ModuleDescriptor, String, UrlMode)} with a {@code urlMode} value of {@link
372 * UrlMode#AUTO}.
373 *
374 * @param moduleDescriptor plugin module descriptor that contains the resource
375 * @param resourceName the name of the resource as defined in the plugin manifest
376 * @return returns the url of this plugin resource
377 * @see #getStaticPluginResource(String, String)
378 * @deprecated As of 2.3.0, replaced by {@link #getStaticPluginResource(ModuleDescriptor, String, UrlMode)}
379 */
380 @Deprecated
381 String getStaticPluginResource(ModuleDescriptor<?> moduleDescriptor, String resourceName);
382
383 /**
384 * A helper method to return a url for 'plugin' resources. Generally the implementation will return
385 * <p/>
386 * {@code /s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name}
387 * <p/>
388 * Note that the servlet context is prepended, and there is no trailing slash.
389 * <p/>
390 * Typical usage is to replace:
391 * <p/>
392 * {@code <%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name} with {@code <%=
393 * webResourceManager.getStaticPluginResource(descriptor, resourceName) %>}
394 * <p/>
395 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
396 * See {@link UrlMode} for details of the different options for URL format.
397 *
398 * @param moduleDescriptor plugin module descriptor that contains the resource
399 * @param resourceName the name of the resource as defined in the plugin manifest
400 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
401 * implementation to decide
402 * @return returns the url of this plugin resource
403 * @see #getStaticPluginResource(String, String, UrlMode)
404 * @since 2.3.0
405 */
406 String getStaticPluginResource(ModuleDescriptor<?> moduleDescriptor, String resourceName, UrlMode urlMode);
407
408 // Deprecated methods
409
410 /**
411 * @deprecated Use #getStaticPluginResource instead
412 */
413 @Deprecated
414 String getStaticPluginResourcePrefix(ModuleDescriptor<?> moduleDescriptor, String resourceName);
415
416 /**
417 * Whether resources should be included inline, or at the top of the page. In most cases, you want to leave this
418 * as the default. However, for pages that don't have a decorator, you will not be able to 'delay' including
419 * the resources (css, javascript), and therefore need to include them directly inline.
420 *
421 * @param includeMode If there is no decorator for this request, set this to be {@link #INLINE_INCLUDE_MODE}
422 * @see #DELAYED_INCLUDE_MODE
423 * @see #INLINE_INCLUDE_MODE
424 * @deprecated Since 2.2.
425 */
426 @Deprecated
427 void setIncludeMode(IncludeMode includeMode);
428
429 /**
430 * @deprecated Since 2.2. Use {@link #requireResource(String, Writer, UrlMode)} instead.
431 */
432 @Deprecated
433 public static final IncludeMode DELAYED_INCLUDE_MODE = new IncludeMode()
434 {
435 public String getModeName()
436 {
437 return "delayed";
438 }
439 };
440
441 /**
442 * @deprecated Since 2.2. Use {@link #requireResource(String)} instead.
443 */
444 @Deprecated
445 public static final IncludeMode INLINE_INCLUDE_MODE = new IncludeMode()
446 {
447 public String getModeName()
448 {
449 return "inline";
450 }
451 };
452
453 /**
454 * @deprecated Since 2.2
455 */
456 @Deprecated
457 public static interface IncludeMode
458 {
459 public String getModeName();
460 }
461 }