1 package com.atlassian.plugin.webresource;
2
3 import com.atlassian.plugin.ModuleDescriptor;
4
5 /**
6 * Provides the prefixes a 'system' static resource as well as the base url of the application
7 * to be used as a prefix for other web resources.
8 * @since 2.9.0
9 */
10 public interface WebResourceUrlProvider
11 {
12 /**
13 * A helper method to return a prefix for 'system' static resources. Generally the implementation will return
14 * <p/>
15 * {@code /s/{build num}/{system counter}/_}
16 * <p/>
17 * Note that the servlet context is prepended, and there is no trailing slash.
18 * <p/>
19 * Typical usage is to replace:
20 * <p/>
21 * {@code <%= request.getContextPath() %>/styles/global.css} with {@code <%= webResourceManager.getStaticResourcePrefix()
22 * %>/styles/global.css}
23 * <p/>
24 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
25 * See {@link UrlMode} for details of the different options for URL format.
26 *
27 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to
28 * decide
29 * @return A prefix that can be used to prefix 'static system' resources.
30 * @since 2.9.0
31 */
32 String getStaticResourcePrefix(UrlMode urlMode);
33
34 /**
35 * A helper method to return a prefix for 'system' static resources. This method should be used for resources that
36 * change more frequently than system resources, and therefore have their own resource counter.
37 * <p/>
38 * Generally the implementation will return
39 * <p/>
40 * {@code /s/{build num}/{system counter}/{resource counter}/_}
41 * <p/>
42 * Note that the servlet context is prepended, and there is no trailing slash.
43 * <p/>
44 * Typical usage is to replace:
45 * <p/>
46 * {@code <%= request.getContextPath() %>/styles/global.css} with {@code <%= webResourceManager.getStaticResourcePrefix(resourceCounter)
47 * %>/styles/global.css}
48 * <p/>
49 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
50 * See {@link UrlMode} for details of the different options for URL format.
51 *
52 * @param resourceCounter A number that represents the unique version of the resource you require. Every time this
53 * resource changes, you need to increment the resource counter
54 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
55 * implementation to decide
56 * @return A prefix that can be used to prefix 'static system' resources.
57 * @since 2.9.0
58 */
59 String getStaticResourcePrefix(String resourceCounter, UrlMode urlMode);
60
61 /**
62 * A helper method to return a url for 'plugin' resources. Generally the implementation will return
63 * <p/>
64 * {@code /s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name}
65 * <p/>
66 * Note that the servlet context is prepended, and there is no trailing slash.
67 * <p/>
68 * Typical usage is to replace:
69 * <p/>
70 * {@code <%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name} with {@code <%=
71 * webResourceManager.getStaticPluginResource(descriptor, resourceName) %>}
72 * <p/>
73 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
74 * See {@link UrlMode} for details of the different options for URL format.
75 *
76 * If a module with the given key cannot be found null is returned.
77 *
78 * @param moduleCompleteKey complete plugin module key
79 * @param resourceName the name of the resource as defined in the plugin manifest
80 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
81 * implementation to decide
82 * @return A url that can be used to request 'plugin' resources.
83 * @since 2.3.0
84 */
85 String getStaticPluginResourceUrl(String moduleCompleteKey, String resourceName, UrlMode urlMode);
86
87 /**
88 * A helper method to return a url for 'plugin' resources. Generally the implementation will return
89 * <p/>
90 * {@code /s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name}
91 * <p/>
92 * Note that the servlet context is prepended, and there is no trailing slash.
93 * <p/>
94 * Typical usage is to replace:
95 * <p/>
96 * {@code <%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name} with {@code <%=
97 * webResourceManager.getStaticPluginResource(descriptor, resourceName) %>}
98 * <p/>
99 * This method returns a URL in either a relative or an absolute format, depending on the value of {@code urlMode}.
100 * See {@link UrlMode} for details of the different options for URL format.
101 *
102 * @param moduleDescriptor plugin module descriptor that contains the resource
103 * @param resourceName the name of the resource as defined in the plugin manifest
104 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete
105 * implementation to decide
106 * @return returns the url of this plugin resource
107 * @see #getStaticPluginResourceUrl(String, String, UrlMode)
108 * @since 2.3.0
109 */
110 String getStaticPluginResourceUrl(ModuleDescriptor<?> moduleDescriptor, String resourceName, UrlMode urlMode);
111
112 /**
113 * Constructs and returns url for the given resource.
114 * This method is not responsible for adding any static caching url prefixes.
115 *
116 * @param pluginModuleKey a plugin module's complete key
117 * @param resourceName the name of the resource described in the module
118 */
119 String getResourceUrl(String pluginModuleKey, String resourceName);
120
121 /**
122 * Returns the base URL for this application. This method may return either an absolute or a relative URL.
123 * Implementations are free to determine which mode to use based on any criteria of their choosing. For example, an
124 * implementation may choose to return a relative URL if it detects that it is running in the context of an HTTP
125 * request, and an absolute URL if it detects that it is not. Or it may choose to always return an absolute URL, or
126 * always return a relative URL. Callers should only use this method when they are sure that either an absolute or
127 * a relative URL will be appropriate, and should not rely on any particular observed behavior regarding how this
128 * value is interpreted, which may vary across different implementations.
129 * <p/>
130 * In general, the behavior of this method should be equivalent to calling {@link
131 * #getBaseUrl(UrlMode)} with a {@code urlMode} value of {@link
132 * UrlMode#AUTO}.
133 *
134 * @return the string value of the base URL of this application
135 */
136 String getBaseUrl();
137
138 /**
139 * Returns the base URL for this application in either relative or absolute format, depending on the value of {@code
140 * urlMode}.
141 * <p/>
142 * If {@code urlMode == {@link UrlMode#ABSOLUTE}}, this method returns an absolute URL, with URL
143 * scheme, hostname, port (if non-standard for the scheme), and context path.
144 * <p/>
145 * If {@code urlMode == {@link UrlMode#RELATIVE}}, this method returns a relative URL containing
146 * just the context path.
147 * <p/>
148 * If {@code urlMode == {@link UrlMode#AUTO}}, this method may return either an absolute or a
149 * relative URL. Implementations are free to determine which mode to use based on any criteria of their choosing.
150 * For example, an implementation may choose to return a relative URL if it detects that it is running in the
151 * context of an HTTP request, and an absolute URL if it detects that it is not. Or it may choose to always return
152 * an absolute URL, or always return a relative URL. Callers should only use {@code
153 * WebResourceManager.UrlMode#AUTO} when they are sure that either an absolute or a relative URL will be
154 * appropriate, and should not rely on any particular observed behavior regarding how this value is interpreted,
155 * which may vary across different implementations.
156 *
157 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to
158 * decide
159 * @return the string value of the base URL of this application
160 * @since 2.3.0
161 */
162 String getBaseUrl(UrlMode urlMode);
163 }