1 package com.atlassian.plugin.webresource;
2
3 import com.atlassian.plugin.PluginAccessor;
4
5 import java.util.Map;
6
7 /**
8 * The integration layer between Plugin's Web Resource Handler, and specific applications (eg JIRA, Confluence).
9 *
10 * @see WebResourceManagerImpl#WebResourceManagerImpl(PluginResourceLocator, WebResourceIntegration)
11 */
12 public interface WebResourceIntegration
13 {
14 /**
15 * Applications must implement this method to get access to the application's PluginAccessor
16 */
17 PluginAccessor getPluginAccessor();
18
19 /**
20 * This must be a thread-local cache that will be accessible from both the page, and the decorator
21 */
22 Map<String, Object> getRequestCache();
23
24 /**
25 * Represents the unique number for this system, which when updated will flush the cache. This should be a number
26 * and is generally stored in the global application-properties.
27 *
28 * @return A string representing the count
29 */
30 String getSystemCounter();
31
32 /**
33 * Represents the last time the system was updated. This is generally obtained from BuildUtils or similar.
34 */
35 String getSystemBuildNumber();
36
37 /**
38 * Returns the base URL for this application. This method may return either an absolute or a relative URL.
39 * Implementations are free to determine which mode to use based on any criteria of their choosing. For example, an
40 * implementation may choose to return a relative URL if it detects that it is running in the context of an HTTP
41 * request, and an absolute URL if it detects that it is not. Or it may choose to always return an absolute URL, or
42 * always return a relative URL. Callers should only use this method when they are sure that either an absolute or
43 * a relative URL will be appropriate, and should not rely on any particular observed behavior regarding how this
44 * value is interpreted, which may vary across different implementations.
45 * <p/>
46 * In general, the behavior of this method should be equivalent to calling {@link
47 * #getBaseUrl(UrlMode)} with a {@code urlMode} value of {@link
48 * UrlMode#AUTO}.
49 *
50 * @return the string value of the base URL of this application
51 */
52 String getBaseUrl();
53
54 /**
55 * Returns the base URL for this application in either relative or absolute format, depending on the value of {@code
56 * urlMode}.
57 * <p/>
58 * If {@code urlMode == {@link UrlMode#ABSOLUTE}}, this method returns an absolute URL, with URL
59 * scheme, hostname, port (if non-standard for the scheme), and context path.
60 * <p/>
61 * If {@code urlMode == {@link UrlMode#RELATIVE}}, this method returns a relative URL containing
62 * just the context path.
63 * <p/>
64 * If {@code urlMode == {@link UrlMode#AUTO}}, this method may return either an absolute or a
65 * relative URL. Implementations are free to determine which mode to use based on any criteria of their choosing.
66 * For example, an implementation may choose to return a relative URL if it detects that it is running in the
67 * context of an HTTP request, and an absolute URL if it detects that it is not. Or it may choose to always return
68 * an absolute URL, or always return a relative URL. Callers should only use {@code
69 * WebResourceManager.UrlMode#AUTO} when they are sure that either an absolute or a relative URL will be
70 * appropriate, and should not rely on any particular observed behavior regarding how this value is interpreted,
71 * which may vary across different implementations.
72 *
73 * @param urlMode specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to
74 * decide
75 * @return the string value of the base URL of this application
76 * @since 2.3.0
77 */
78 String getBaseUrl(UrlMode urlMode);
79
80 /**
81 * This version number is used for caching URL generation, and needs to be incremented every time the contents
82 * of the superbatch may have changed. Practically this means updating every time the plugin system state changes
83 *
84 * @return a version number
85 */
86 String getSuperBatchVersion();
87 }