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 {@link JavascriptWebResource.FILTER_INSTANCE}, 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 {@link JavascriptWebResource.FILTER_INSTANCE}, 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 @Deprecated
186 String getStaticResourcePrefix(UrlMode urlMode);
187
188 /**
189 * A helper method to return a prefix for 'system' static resources. This method should be used for resources that
190 * change more frequently than system resources, and therefore have their own resource counter.
191 * <p/>
192 * Generally the implementation will return
193 * <p/>
194 * {@code /s/{build num}/{system counter}/{resource counter}/_}
195 * <p/>
196 * Note that the servlet context is prepended, and there is no trailing slash.
197 * <p/>
198 * Typical usage is to replace:
199 * <p/>
200 * {@code <%= request.getContextPath() %>/styles/global.css} with {@code <%= webResourceManager.getStaticResourcePrefix(resourceCounter)
201 * %>/styles/global.css}
202 * <p/>
203 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
204 * See {@link UrlMode} for details of the different options for URL format.
205 *
206 * @param resourceCounter A number that represents the unique version of the resource you require. Every time this
207 * resource changes, you need to increment the resource counter
208 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
209 * implementation to decide
210 * @return A prefix that can be used to prefix 'static system' resources.
211 * @since 2.3.0
212 * @deprecated As of 2.9.0, replaced by {@link WebResourceUrlProvider#getStaticResourcePrefix(String, UrlMode)}
213 */
214 @Deprecated
215 String getStaticResourcePrefix(String resourceCounter, UrlMode urlMode);
216
217 /**
218 * A helper method to return a url for 'plugin' resources. Generally the implementation will return
219 * <p/>
220 * {@code /s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name}
221 * <p/>
222 * Note that the servlet context is prepended, and there is no trailing slash.
223 * <p/>
224 * Typical usage is to replace:
225 * <p/>
226 * {@code <%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name} with {@code <%=
227 * webResourceManager.getStaticPluginResource(descriptor, resourceName) %>}
228 * <p/>
229 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
230 * See {@link UrlMode} for details of the different options for URL format.
231 *
232 * @param moduleCompleteKey complete plugin module key
233 * @param resourceName the name of the resource as defined in the plugin manifest
234 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
235 * implementation to decide
236 * @return A url that can be used to request 'plugin' resources.
237 * @since 2.3.0
238 * @deprecated As of 2.9.0, replaced by {@link WebResourceUrlProvider#getStaticPluginResourceUrl(String, String, UrlMode)}
239 */
240 @Deprecated
241 String getStaticPluginResource(String moduleCompleteKey, String resourceName, UrlMode urlMode);
242
243 /**
244 * A helper method to return a url for 'plugin' resources. Generally the implementation will return
245 * <p/>
246 * {@code /s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name}
247 * <p/>
248 * Note that the servlet context is prepended, and there is no trailing slash.
249 * <p/>
250 * Typical usage is to replace:
251 * <p/>
252 * {@code <%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name} with {@code <%=
253 * webResourceManager.getStaticPluginResource(descriptor, resourceName) %>}
254 * <p/>
255 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
256 * See {@link UrlMode} for details of the different options for URL format.
257 *
258 * @param moduleDescriptor plugin module descriptor that contains the resource
259 * @param resourceName the name of the resource as defined in the plugin manifest
260 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
261 * implementation to decide
262 * @return returns the url of this plugin resource
263 * @see #getStaticPluginResource(String, String, UrlMode)
264 * @since 2.3.0
265 * @deprecated As of 2.9.0, replaced by {@link WebResourceUrlProvider#getStaticPluginResourceUrl(com.atlassian.plugin.ModuleDescriptor, String, UrlMode)}
266 */
267 @Deprecated
268 String getStaticPluginResource(ModuleDescriptor<?> moduleDescriptor, String resourceName, UrlMode urlMode);
269
270 //
271 // deprecated since 2.3 or earlier
272 //
273
274 /**
275 * @deprecated As of 2.3.0, replaced by {@link #includeResources(Writer, UrlMode)}
276 */
277 @Deprecated
278 void includeResources(Writer writer);
279
280 /**
281 * @deprecated As of 2.3.0, replaced by {@link #getRequiredResources(UrlMode)}
282 */
283 @Deprecated
284 String getRequiredResources();
285
286 /**
287 * @deprecated As of 2.3.0, replaced by {@link #requireResource(String, Writer, UrlMode)}
288 */
289 @Deprecated
290 void requireResource(String moduleCompleteKey, Writer writer);
291
292 /**
293 * @deprecated As of 2.3.0, replaced by {@link #getResourceTags(String, UrlMode)}
294 */
295 @Deprecated
296 String getResourceTags(String moduleCompleteKey);
297
298 /**
299 * @deprecated As of 2.3.0, replaced by {@link #getStaticResourcePrefix(UrlMode)}
300 */
301 @Deprecated
302 String getStaticResourcePrefix();
303
304 /**
305 * @deprecated As of 2.3.0, replaced by {@link #getStaticResourcePrefix(String, UrlMode)}
306 */
307 @Deprecated
308 String getStaticResourcePrefix(String resourceCounter);
309
310 /**
311 * @deprecated As of 2.3.0, replaced by {@link #getStaticPluginResource(String, String, UrlMode)}
312 */
313 @Deprecated
314 String getStaticPluginResource(String moduleCompleteKey, String resourceName);
315
316 /**
317 * @deprecated As of 2.3.0, replaced by {@link #getStaticPluginResource(ModuleDescriptor, String, UrlMode)}
318 */
319 @Deprecated
320 String getStaticPluginResource(ModuleDescriptor<?> moduleDescriptor, String resourceName);
321
322 /**
323 * @deprecated Since 2.2 Use #getStaticPluginResource instead
324 */
325 @Deprecated
326 String getStaticPluginResourcePrefix(ModuleDescriptor<?> moduleDescriptor, String resourceName);
327
328 /**
329 * @see #INLINE_INCLUDE_MODE
330 * @deprecated Since 2.2.
331 */
332 @Deprecated
333 void setIncludeMode(IncludeMode includeMode);
334
335 /**
336 * @deprecated Since 2.2. Use {@link #requireResource(String, Writer, UrlMode)} instead.
337 */
338 @Deprecated
339 public static final IncludeMode DELAYED_INCLUDE_MODE = new IncludeMode()
340 {
341 public String getModeName()
342 {
343 return "delayed";
344 }
345 };
346
347 /**
348 * @deprecated Since 2.2. Use {@link #requireResource(String)} instead.
349 */
350 @Deprecated
351 public static final IncludeMode INLINE_INCLUDE_MODE = new IncludeMode()
352 {
353 public String getModeName()
354 {
355 return "inline";
356 }
357 };
358
359 /**
360 * @deprecated Since 2.2
361 */
362 @Deprecated
363 public static interface IncludeMode
364 {
365 public String getModeName();
366 }
367 }