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
9 * <code><script></code> and <code><link> tags.
10 * <p/>
11 * By using the WebResourceManager, components can declare dependencies on javascript and css that they would
12 * otherwise 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 * Called by a component to indicate that a certain resource is required to be inserted into
18 * this page. Note that this will always include the resources as if we are in {@link #DELAYED_INCLUDE_MODE}.
19 * Use this if you do not want to inline a resource.
20 *
21 * @param resourceName The fully qualified plugin name to include (eg <code>jira.webresources:scriptaculous</code>)
22 * @throws IllegalStateException If this method is called while not in {@link #DELAYED_INCLUDE_MODE}.
23 */
24 void requireResource(String resourceName);
25
26 /**
27 * Called by a component to indicate that a certain resource is required to be inserted into
28 * this page.
29 *
30 * @param resourceName The fully qualified plugin name to include (eg <code>jira.webresources:scriptaculous</code>)
31 * @param writer The writer to write the links to if the {@link WebResourceManager.IncludeMode} equals {@link WebResourceManager#INLINE_INCLUDE_MODE}
32 */
33 public void requireResource(String resourceName, Writer writer);
34
35 /**
36 * Include the resources that have already been specified by the request in the page. This is done by including
37 * links to the resources that have been specified.
38 * <p/>
39 * Example - if a 'javascript' resource has been specified, this method should output:
40 * <pre><code>
41 * <script type="text/javascript" src="$contextPath/scripts/javascript.js"></script>
42 * </code></pre>
43 * Similarly for other supported resources
44 *
45 * @param writer The writer to write the links to
46 */
47 public void includeResources(Writer writer);
48
49 /**
50 * A helper method to return a prefix for 'system' static resources. Generally the implementation will return
51 * <p/>
52 * <pre><code>/s/{build num}/{system counter}/_</code></pre>
53 * <p/>
54 * Note that the servlet context is prepended, and there is no trailing slash.
55 * <p/>
56 * <p/>
57 * Typical usage is to replace:
58 * <p/>
59 * <pre><code><%= request.getContextPath() %>/styles/global.css</code></pre>
60 * with
61 * <pre><code><%= webResourceManager.getStaticResourcePrefix() %>/styles/global.css</code></pre>
62 *
63 * @return A prefix that can be used to prefix 'static system' resources.
64 */
65 public String getStaticResourcePrefix();
66
67 /**
68 * A helper method to return a prefix for 'system' static resources. This method should be used for
69 * resources that change more frequently than system resources, and therefore have their own resource counter.
70 * <p/>
71 * Generally the implementation will return
72 * <p/>
73 * <pre><code>/s/{build num}/{system counter}/{resource counter}/_</code></pre>
74 * <p/>
75 * Note that the servlet context is prepended, and there is no trailing slash.
76 * <p/>
77 * <p/>
78 * Typical usage is to replace:
79 * <p/>
80 * <pre><code><%= request.getContextPath() %>/styles/global.css</code></pre>
81 * with
82 * <pre><code><%= webResourceManager.getStaticResourcePrefix(resourceCounter) %>/styles/global.css</code></pre>
83 *
84 * @param resourceCounter A number that represents the unique version of the resource you require. Every time this
85 * resource changes, you need to increment the resource counter
86 * @return A prefix that can be used to prefix 'static system' resources.
87 */
88 public String getStaticResourcePrefix(String resourceCounter);
89
90 /**
91 * A helper method to return a url for 'plugin' resources. Generally the implementation will return
92 * <p/>
93 * <pre><code>/s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name</code></pre>
94 * <p/>
95 * Note that the servlet context is prepended, and there is no trailing slash.
96 * <p/>
97 * <p/>
98 * Typical usage is to replace:
99 * <p/>
100 * <pre><code><%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name</code></pre>
101 * with
102 * <pre><code><%= webResourceManager.getStaticPluginResource(descriptor, resourceName) %></code></pre>
103 *
104 * @return A url that can be used to request 'plugin' resources.
105 */
106 public String getStaticPluginResource(ModuleDescriptor moduleDescriptor, String resourceName);
107
108 /**
109 * @deprecated Use #getStaticPluginResource instead
110 */
111 public String getStaticPluginResourcePrefix(ModuleDescriptor moduleDescriptor, String resourceName);
112
113 /**
114 * @param pluginModuleKey complete plugin module key
115 * @return returns the url of this plugin resource
116 */
117 public String getStaticPluginResource(String pluginModuleKey, String resourceName);
118
119 /**
120 * Whether resources should be included inline, or at the top of the page. In most cases, you want to leave this
121 * as the default. However, for pages that don't have a decorator, you will not be able to 'delay' including
122 * the resources (css, javascript), and therefore need to include them directly inline.
123 *
124 * @param includeMode If there is no decorator for this request, set this to be {@link #INLINE_INCLUDE_MODE}
125 * @see #DELAYED_INCLUDE_MODE
126 * @see #INLINE_INCLUDE_MODE
127 */
128 public void setIncludeMode(IncludeMode includeMode);
129
130 public static final IncludeMode DELAYED_INCLUDE_MODE = new IncludeMode()
131 {
132 public String getModeName()
133 {
134 return "delayed";
135 }
136 };
137
138 public static final IncludeMode INLINE_INCLUDE_MODE = new IncludeMode()
139 {
140 public String getModeName()
141 {
142 return "inline";
143 }
144 };
145
146 public static interface IncludeMode
147 {
148 public String getModeName();
149 }
150
151 }