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