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