com.atlassian.plugin.webresource

Interface WebResourceUrlProvider

All Known Implementing Classes:

WebResourceUrlProviderImpl

public interface WebResourceUrlProvider

Provides the prefixes a 'system' static resource as well as the base url of the application to be used as a prefix for other web resources.

Since:

2.9.0

Method Summary

Modifier and Type	Method and Description
String	getBaseUrl() Returns the base URL for this application.
String	getBaseUrl(UrlMode urlMode) Returns the base URL for this application in either relative or absolute format, depending on the value of urlMode.
String	getResourceUrl(String pluginModuleKey, String resourceName) Constructs and returns url for the given resource.
String	getStaticPluginResourceUrl(com.atlassian.plugin.ModuleDescriptor<?> moduleDescriptor, String resourceName, UrlMode urlMode) A helper method to return a url for 'plugin' resources.
String	getStaticPluginResourceUrl(String moduleCompleteKey, String resourceName, UrlMode urlMode) A helper method to return a url for 'plugin' resources.
String	getStaticResourcePrefix(String contributedHash, String resourceCounter, UrlMode urlMode) A helper method to return a prefix for 'system' static resources.
String	getStaticResourcePrefix(String resourceCounter, UrlMode urlMode) A helper method to return a prefix for 'system' static resources.
String	getStaticResourcePrefix(UrlMode urlMode) A helper method to return a prefix for 'system' static resources.

Method Detail

getStaticResourcePrefix

String getStaticResourcePrefix(UrlMode urlMode)

A helper method to return a prefix for 'system' static resources. Generally the implementation will return

/s/{build num}/{system counter}/_

Note that the servlet context is prepended, and there is no trailing slash.

Typical usage is to replace:

<%= request.getContextPath() %>/styles/global.css with <%= webResourceManager.getStaticResourcePrefix() %>/styles/global.css

This method returns a URL in either a relative or an absolute format, depending on the value of urlMode. See UrlMode for details of the different options for URL format.

Parameters:

urlMode - specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to decide

Returns:

A prefix that can be used to prefix 'static system' resources.

Since:

2.9.0

getStaticResourcePrefix

String getStaticResourcePrefix(String resourceCounter,
                               UrlMode urlMode)

A helper method to return a prefix for 'system' static resources. This method should be used for resources that change more frequently than system resources, and therefore have their own resource counter.

Generally the implementation will return

/s/{build num}/{system counter}/{resource counter}/_

Note that the servlet context is prepended, and there is no trailing slash.

Typical usage is to replace:

<%= request.getContextPath() %>/styles/global.css with <%= webResourceManager.getStaticResourcePrefix(resourceCounter) %>/styles/global.css

This method returns a URL in either a relative or an absolute format, depending on the value of urlMode. See UrlMode for details of the different options for URL format.

Parameters:

resourceCounter - A number that represents the unique version of the resource you require. Every time this resource changes, you need to increment the resource counter

urlMode - specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to decide

Returns:

A prefix that can be used to prefix 'static system' resources.

Since:

2.9.0

getStaticResourcePrefix

String getStaticResourcePrefix(String contributedHash,
                               String resourceCounter,
                               UrlMode urlMode)

A helper method to return a prefix for 'system' static resources. This method should be used for resources that change more frequently than system resources, and therefore have their own resource counter.

Generally the implementation will return

/s/{contributed Hash}/{build num}/{system counter}/{resource counter}/_

Note that the servlet context is prepended, and there is no trailing slash.

Typical usage is to replace:

<%= request.getContextPath() %>/styles/global.css with <%= webResourceManager.getStaticResourcePrefix(resourceCounter) %>/styles/global.css

This method returns a URL in either a relative or an absolute format, depending on the value of urlMode. See UrlMode for details of the different options for URL format.

Parameters:

contributedHash - hash contributed by resource mutators such as transforms or conditions

resourceCounter - A number that represents the unique version of the resource you require. Every time this resource changes, you need to increment the resource counter

urlMode - specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to decide

Returns:

A prefix that can be used to prefix 'static system' resources.

Since:

3.0.0

getStaticPluginResourceUrl

String getStaticPluginResourceUrl(String moduleCompleteKey,
                                  String resourceName,
                                  UrlMode urlMode)

A helper method to return a url for 'plugin' resources. Generally the implementation will return

/s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name

Note that the servlet context is prepended, and there is no trailing slash.

Typical usage is to replace:

<%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name with <%= webResourceManager.getStaticPluginResource(descriptor, resourceName) %>

This method returns a URL in either a relative or an absolute format, depending on the value of urlMode. See UrlMode for details of the different options for URL format. If a module with the given key cannot be found null is returned.

Parameters:

moduleCompleteKey - complete plugin module key

resourceName - the name of the resource as defined in the plugin manifest

urlMode - specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to decide

Returns:

A url that can be used to request 'plugin' resources.

Since:

2.3.0

getStaticPluginResourceUrl

String getStaticPluginResourceUrl(com.atlassian.plugin.ModuleDescriptor<?> moduleDescriptor,
                                  String resourceName,
                                  UrlMode urlMode)

A helper method to return a url for 'plugin' resources. Generally the implementation will return

/s/{build num}/{system counter}/{plugin version}/_/download/resources/plugin.key:module.key/resource.name

Note that the servlet context is prepended, and there is no trailing slash.

Typical usage is to replace:

<%= request.getContextPath() %>/download/resources/plugin.key:module.key/resource.name with <%= webResourceManager.getStaticPluginResource(descriptor, resourceName) %>

This method returns a URL in either a relative or an absolute format, depending on the value of urlMode. See UrlMode for details of the different options for URL format.

Parameters:

moduleDescriptor - plugin module descriptor that contains the resource

resourceName - the name of the resource as defined in the plugin manifest

urlMode - specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to decide

Returns:

returns the url of this plugin resource

Since:

2.3.0

See Also:

getStaticPluginResourceUrl(String, String, UrlMode)

getResourceUrl

String getResourceUrl(String pluginModuleKey,
                      String resourceName)

Constructs and returns url for the given resource. This method is not responsible for adding any static caching url prefixes.

Parameters:

pluginModuleKey - a plugin module's complete key

resourceName - the name of the resource described in the module

getBaseUrl

String getBaseUrl()

Returns the base URL for this application. This method may return either an absolute or a relative URL. Implementations are free to determine which mode to use based on any criteria of their choosing. For example, an implementation may choose to return a relative URL if it detects that it is running in the context of an HTTP request, and an absolute URL if it detects that it is not. Or it may choose to always return an absolute URL, or always return a relative URL. Callers should only use this method when they are sure that either an absolute or a relative URL will be appropriate, and should not rely on any particular observed behavior regarding how this value is interpreted, which may vary across different implementations.

In general, the behavior of this method should be equivalent to calling getBaseUrl(UrlMode) with a urlMode value of UrlMode.AUTO.

Returns:

the string value of the base URL of this application

getBaseUrl

String getBaseUrl(UrlMode urlMode)

Returns the base URL for this application in either relative or absolute format, depending on the value of urlMode.

If urlMode == {@link UrlMode#ABSOLUTE}, this method returns an absolute URL, with URL scheme, hostname, port (if non-standard for the scheme), and context path.

If urlMode == {@link UrlMode#RELATIVE}, this method returns a relative URL containing just the context path.

If urlMode == {@link UrlMode#AUTO}, this method may return either an absolute or a relative URL. Implementations are free to determine which mode to use based on any criteria of their choosing. For example, an implementation may choose to return a relative URL if it detects that it is running in the context of an HTTP request, and an absolute URL if it detects that it is not. Or it may choose to always return an absolute URL, or always return a relative URL. Callers should only use WebResourceManager.UrlMode#AUTO when they are sure that either an absolute or a relative URL will be appropriate, and should not rely on any particular observed behavior regarding how this value is interpreted, which may vary across different implementations.

Parameters:

urlMode - specifies whether to use absolute URLs, relative URLs, or allow the concrete implementation to decide

Returns:

the string value of the base URL of this application

Since:

2.3.0