1 package com.atlassian.plugin.webresource;
2
3 import com.atlassian.plugin.PluginAccessor;
4
5 import com.google.common.annotations.Beta;
6
7 import java.io.File;
8 import java.util.Map;
9
10 /**
11 * The integration layer between Plugin's Web Resource Handler, and specific applications (eg JIRA, Confluence).
12 *
13 * @see WebResourceManagerImpl#WebResourceManagerImpl(PluginResourceLocator, WebResourceIntegration)
14 */
15 public interface WebResourceIntegration
16 {
17 /**
18 * Applications must implement this method to get access to the application's PluginAccessor
19 */
20 PluginAccessor getPluginAccessor();
21
22 /**
23 * This must be a thread-local cache that will be accessible from both the page, and the decorator
24 */
25 Map<String, Object> getRequestCache();
26
27 /**
28 * Represents the unique number for this system, which when updated will flush the cache. This should be a number
29 * and is generally stored in the global application-properties.
30 *
31 * @return A string representing the count
32 */
33 String getSystemCounter();
34
35 /**
36 * Represents the last time the system was updated. This is generally obtained from BuildUtils or similar.
37 */
38 String getSystemBuildNumber();
39
40 /**
41 * Returns the base URL for this application. This method may return either an absolute or a relative URL.
42 * Implementations are free to determine which mode to use based on any criteria of their choosing. For example, an
43 * implementation may choose to return a relative URL if it detects that it is running in the context of an HTTP
44 * request, and an absolute URL if it detects that it is not. Or it may choose to always return an absolute URL, or
45 * always return a relative URL. Callers should only use this method when they are sure that either an absolute or
46 * a relative URL will be appropriate, and should not rely on any particular observed behavior regarding how this
47 * value is interpreted, which may vary across different implementations.
48 * <p/>
49 * In general, the behavior of this method should be equivalent to calling {@link
50 * #getBaseUrl(UrlMode)} with a {@code urlMode} value of {@link
51 * UrlMode#AUTO}.
52 *
53 * @return the string value of the base URL of this application
54 */
55 String getBaseUrl();
56
57 /**
58 * Returns the base URL for this application in either relative or absolute format, depending on the value of {@code
59 * urlMode}.
60 * <p/>
61 * If {@code urlMode == {@link UrlMode#ABSOLUTE}}, this method returns an absolute URL, with URL
62 * scheme, hostname, port (if non-standard for the scheme), and context path.
63 * <p/>
64 * If {@code urlMode == {@link UrlMode#RELATIVE}}, this method returns a relative URL containing
65 * just the context path.
66 * <p/>
67 * If {@code urlMode == {@link UrlMode#AUTO}}, this method may return either an absolute or a
68 * relative URL. Implementations are free to determine which mode to use based on any criteria of their choosing.
69 * For example, an implementation may choose to return a relative URL if it detects that it is running in the
70 * context of an HTTP request, and an absolute URL if it detects that it is not. Or it may choose to always return
71 * an absolute URL, or always return a relative URL. Callers should only use {@code
72 * WebResourceManager.UrlMode#AUTO} when they are sure that either an absolute or a relative URL will be
73 * appropriate, and should not rely on any particular observed behavior regarding how this value is interpreted,
74 * which may vary across different implementations.
75 *
76 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to
77 * decide
78 * @return the string value of the base URL of this application
79 * @since 2.3.0
80 */
81 String getBaseUrl(UrlMode urlMode);
82
83 /**
84 * This version number is used for caching URL generation, and needs to be incremented every time the contents
85 * of the superbatch may have changed. Practically this means updating every time the plugin system state changes
86 *
87 * @return a version number
88 */
89 String getSuperBatchVersion();
90
91 /**
92 * The locale identifier that should be inserted into static resource urls for the current request, if appropriate.
93 * @return null if the url should not have a locale component
94 */
95 String getStaticResourceLocale();
96
97 /**
98 * A reference to the temporary directory the application want the plugin system to use. The temporary directory can
99 * be cleared at any time by the application and can be used by the plugin system to cache things like batches or
100 * other things that can easily be re-generated. It is recommended that this directory be /apphome/tmp/webresources.
101 * The plugin system can delete any or all files it sees fit that exists under this directory at any time.
102 * The directory does not need to exist.
103 * @return a File reference to the temporary directory. This can not return null.
104 * @since 2.9.0
105 */
106 File getTemporaryDirectory();
107
108 /**
109 * EXPERIMENTAL - PLUG-888. This method is likely to change or be removed after 2.13.x
110 * <p>
111 * This is used to replace any <code>${var}</code> variables in the location of a <resource>.
112 *
113 * This will be called at resource-fetch time and page-render time. Therefore, for example, if the return value
114 * depends on the current user, then the current user needs to be available at resource-fetch
115 * time as well as page-render time.
116 *
117 * @return a map of variable-name to value.
118 * @since 2.13.0 EXPERIMENTAL
119 */
120 @Beta
121 Map<String,String> getResourceSubstitutionVariables();
122 }