com.atlassian.plugin.webresource
Interface WebResourceManager

All Known Implementing Classes:

WebResourceManagerImpl

public interface WebResourceManager

Manage 'css', 'javascript' and other 'resources' that are usually linked at the top of pages using <script> and <link> tags.

By using the WebResourceManager, components can declare dependencies on javascript and css that they would otherwise have to embed inline (which means that it can't be cached, and are often duplicated in a page).

Nested Class Summary

static interface

WebResourceManager.IncludeMode Deprecated. Since 2.2

Field Summary

static WebResourceManager.IncludeMode	DELAYED_INCLUDE_MODE Deprecated. Since 2.2. Use requireResource(String, Writer, UrlMode) instead.
static WebResourceManager.IncludeMode	INLINE_INCLUDE_MODE Deprecated. Since 2.2. Use requireResource(String) instead.

Method Summary

<T> T	executeInNewContext(com.google.common.base.Supplier<T> nestedExecution) Executes a Supplier within a new WebResourceManager context.
String	getRequiredResources() Deprecated. As of 2.3.0, replaced by getRequiredResources(UrlMode)
String	getRequiredResources(UrlMode urlMode) This is the equivalent of calling getRequiredResources(UrlMode, WebResourceFilter) with the given url mode and a default filter that is dependent on the implementation.
String	getRequiredResources(UrlMode urlMode, WebResourceFilter webResourceFilter) Returns the resource tags for the previously required resources called via requireResource(String) that match the specified web resource filter.
String	getResourceTags(String moduleCompleteKey) Deprecated. As of 2.3.0, replaced by getResourceTags(String, UrlMode)
String	getResourceTags(String moduleCompleteKey, UrlMode urlMode) Returns the resource tags of the specified resource.
String	getStaticPluginResource(ModuleDescriptor<?> moduleDescriptor, String resourceName) Deprecated. As of 2.3.0, replaced by getStaticPluginResource(ModuleDescriptor, String, UrlMode)
String	getStaticPluginResource(ModuleDescriptor<?> moduleDescriptor, String resourceName, UrlMode urlMode) Deprecated. As of 2.9.0, replaced by WebResourceUrlProvider.getStaticPluginResourceUrl(com.atlassian.plugin.ModuleDescriptor, String, UrlMode)
String	getStaticPluginResource(String moduleCompleteKey, String resourceName) Deprecated. As of 2.3.0, replaced by getStaticPluginResource(String, String, UrlMode)
String	getStaticPluginResource(String moduleCompleteKey, String resourceName, UrlMode urlMode) Deprecated. As of 2.9.0, replaced by WebResourceUrlProvider.getStaticPluginResourceUrl(String, String, UrlMode)
String	getStaticPluginResourcePrefix(ModuleDescriptor<?> moduleDescriptor, String resourceName) Deprecated. Since 2.2 Use #getStaticPluginResource instead
String	getStaticResourcePrefix() Deprecated. As of 2.3.0, replaced by getStaticResourcePrefix(UrlMode)
String	getStaticResourcePrefix(String resourceCounter) Deprecated. As of 2.3.0, replaced by getStaticResourcePrefix(String, UrlMode)
String	getStaticResourcePrefix(String resourceCounter, UrlMode urlMode) Deprecated. As of 2.9.0, replaced by WebResourceUrlProvider.getStaticResourcePrefix(String, UrlMode)
String	getStaticResourcePrefix(UrlMode urlMode) Deprecated. As of 2.9.0, replaced by WebResourceUrlProvider.getStaticResourcePrefix(UrlMode)
void	includeResources(Iterable<String> moduleCompleteKeys, Writer writer, UrlMode urlMode) Writes out the resource tags for a specified set of required resources and their dependencies.
void	includeResources(Writer writer) Deprecated. As of 2.3.0, replaced by includeResources(Writer, UrlMode)
void	includeResources(Writer writer, UrlMode urlMode) This is the equivalent of calling includeResources(Writer, UrlMode, WebResourceFilter) with the given url mode and a default web resource filter that is dependent on the implementation.
void	includeResources(Writer writer, UrlMode urlMode, WebResourceFilter webResourceFilter) Writes out the resource tags to the previously required resources called via requireResource(String) for the specified resource type.
void	requireResource(String moduleCompleteKey) Indicates that a given plugin web resource is required.
void	requireResource(String moduleCompleteKey, Writer writer) Deprecated. As of 2.3.0, replaced by requireResource(String, Writer, UrlMode)
void	requireResource(String moduleCompleteKey, Writer writer, UrlMode urlMode) Writes the resource tags of the specified resource to the writer.
void	requireResourcesForContext(String context) Writes the resource tags of all resources that have the given context specified in their descriptor.
void	setIncludeMode(WebResourceManager.IncludeMode includeMode) Deprecated. Since 2.2.

Field Detail

DELAYED_INCLUDE_MODE

@Deprecated
static final WebResourceManager.IncludeMode DELAYED_INCLUDE_MODE

Deprecated. Since 2.2. Use requireResource(String, Writer, UrlMode) instead.

INLINE_INCLUDE_MODE

@Deprecated
static final WebResourceManager.IncludeMode INLINE_INCLUDE_MODE

Deprecated. Since 2.2. Use requireResource(String) instead.

Method Detail

requireResource

void requireResource(String moduleCompleteKey)

Indicates that a given plugin web resource is required. All resources called via this method must be included when includeResources(Writer) is called.

Parameters:

moduleCompleteKey - The fully qualified plugin web resource module (eg jira.webresources:scriptaculous)

See Also:

includeResources(Writer, UrlMode)

includeResources

void includeResources(Iterable<String> moduleCompleteKeys,
                      Writer writer,
                      UrlMode urlMode)

Writes out the resource tags for a specified set of required resources and their dependencies. Does not write out tags for resources specified in calls to requireResource(String).

Parameters:

moduleCompleteKeys - The set of web resource modules to include

writer - the writer to write the links to

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

Since:

2.4.0

includeResources

void includeResources(Writer writer,
                      UrlMode urlMode)

This is the equivalent of calling includeResources(Writer, UrlMode, WebResourceFilter) with the given url mode and a default web resource filter that is dependent on the implementation.

Since:

2.3.0

See Also:

includeResources(Writer, UrlMode, WebResourceFilter)

includeResources

void includeResources(Writer writer,
                      UrlMode urlMode,
                      WebResourceFilter webResourceFilter)

Writes out the resource tags to the previously required resources called via requireResource(String) for the specified resource type. If you need it as a String to embed the tags in a template, use getRequiredResources(UrlMode).

Example - if a 'javascript' resource has been required earlier with requireResource() and this method is called with a JavascriptWebResource, it should output:

  <script type="text/javascript" src="$contextPath/scripts/javascript.js"></script>
 

Similarly for other supported resources.

This method formats resource URLs in either relative or absolute format, depending on the value of urlMode. See UrlMode for details of the different options for URL format.

Parameters:

writer - the writer to write the links to

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

webResourceFilter - the web resource filter to filter resources on

Since:

2.4

getRequiredResources

String getRequiredResources(UrlMode urlMode)

This is the equivalent of calling getRequiredResources(UrlMode, WebResourceFilter) with the given url mode and a default filter that is dependent on the implementation.

Returns:

the resource tags for all resources previously required

Since:

2.3.1

See Also:

includeResources(Writer, UrlMode), getRequiredResources(UrlMode, WebResourceFilter)

getRequiredResources

String getRequiredResources(UrlMode urlMode,
                            WebResourceFilter webResourceFilter)

Returns the resource tags for the previously required resources called via requireResource(String) that match the specified web resource filter. If you are outputting the value to a Writer, use includeResources(Writer, UrlMode).

Example - if a 'javascript' resource has been required earlier with requireResource() and this method is called with a JavascriptWebResource, it should return:

  <script type="text/javascript" src="$contextPath/scripts/javascript.js"></script>
 

Similarly for other supported resources.

This method formats resource URLs in either relative or 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

webResourceFilter - the web resource filter to filter resources on

Returns:

the resource tags for all resources previously required

Since:

2.4

See Also:

includeResources(Writer, UrlMode, WebResourceFilter)

requireResource

void requireResource(String moduleCompleteKey,
                     Writer writer,
                     UrlMode urlMode)

Writes the resource tags of the specified resource to the writer. If you need it as a String to embed the tags in a template, use getResourceTags(String, UrlMode).

This method formats resource URLs in either relative or absolute format, depending on the value of urlMode. See UrlMode for details of the different options for URL format.

Parameters:

moduleCompleteKey - The fully qualified plugin web resource module (eg jira.webresources:scriptaculous)

writer - The writer to write the resource tags to.

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

Since:

2.3.0

requireResourcesForContext

void requireResourcesForContext(String context)

Writes the resource tags of all resources that have the given context specified in their descriptor.

Parameters:

context - The name of the context for which you want to require resources (eg "atl.admin")

Since:

2.5.0

getResourceTags

String getResourceTags(String moduleCompleteKey,
                       UrlMode urlMode)

Returns the resource tags of the specified resource. If you are outputting the value to a Writer, use requireResource(String, java.io.Writer, UrlMode).

This method formats resource URLs in either relative or absolute format, depending on the value of urlMode. See UrlMode for details of the different options for URL format.

Parameters:

moduleCompleteKey - The fully qualified plugin web resource module (eg jira.webresources:scriptaculous)

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

Returns:

the resource tags for the specified resource

Since:

2.3.0

See Also:

requireResource(String, Writer, UrlMode)

executeInNewContext

<T> T executeInNewContext(com.google.common.base.Supplier<T> nestedExecution)

Executes a Supplier within a new WebResourceManager context. The request-local state manipulated by requireResource and requireResourcesForContext is preserved, an empty state is initialized for the execution of nestedExecution and after the nestedExecution is run, the old state is restored. If no return is required from the nestedExecution then Suppier can be used. Useful for rendering of pages which include nested pages (such as gadgets), which need to resolve the requirements of the inner pages without polluting the outer page's resources.

Parameters:

nestedExecution - the code to be executed in the empty context.

Returns:

the value returned by nestedExection.get()

Since:

2.10.0

getStaticResourcePrefix

@Deprecated
String getStaticResourcePrefix(UrlMode urlMode)

Deprecated. As of 2.9.0, replaced by WebResourceUrlProvider.getStaticResourcePrefix(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.3.0

getStaticResourcePrefix

@Deprecated
String getStaticResourcePrefix(String resourceCounter,
                                          UrlMode urlMode)

Deprecated. As of 2.9.0, replaced by WebResourceUrlProvider.getStaticResourcePrefix(String, 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.3.0

getStaticPluginResource

@Deprecated
String getStaticPluginResource(String moduleCompleteKey,
                                          String resourceName,
                                          UrlMode urlMode)

Deprecated. As of 2.9.0, replaced by WebResourceUrlProvider.getStaticPluginResourceUrl(String, String, 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:

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

getStaticPluginResource

@Deprecated
String getStaticPluginResource(ModuleDescriptor<?> moduleDescriptor,
                                          String resourceName,
                                          UrlMode urlMode)

Deprecated. As of 2.9.0, replaced by WebResourceUrlProvider.getStaticPluginResourceUrl(com.atlassian.plugin.ModuleDescriptor, String, 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:

getStaticPluginResource(String, String, UrlMode)

includeResources

@Deprecated
void includeResources(Writer writer)

Deprecated. As of 2.3.0, replaced by includeResources(Writer, UrlMode)

getRequiredResources

@Deprecated
String getRequiredResources()

Deprecated. As of 2.3.0, replaced by getRequiredResources(UrlMode)

requireResource

@Deprecated
void requireResource(String moduleCompleteKey,
                                Writer writer)

Deprecated. As of 2.3.0, replaced by requireResource(String, Writer, UrlMode)

getResourceTags

@Deprecated
String getResourceTags(String moduleCompleteKey)

Deprecated. As of 2.3.0, replaced by getResourceTags(String, UrlMode)

getStaticResourcePrefix

@Deprecated
String getStaticResourcePrefix()

Deprecated. As of 2.3.0, replaced by getStaticResourcePrefix(UrlMode)

getStaticResourcePrefix

@Deprecated
String getStaticResourcePrefix(String resourceCounter)

Deprecated. As of 2.3.0, replaced by getStaticResourcePrefix(String, UrlMode)

getStaticPluginResource

@Deprecated
String getStaticPluginResource(String moduleCompleteKey,
                                          String resourceName)

Deprecated. As of 2.3.0, replaced by getStaticPluginResource(String, String, UrlMode)

getStaticPluginResource

@Deprecated
String getStaticPluginResource(ModuleDescriptor<?> moduleDescriptor,
                                          String resourceName)

Deprecated. As of 2.3.0, replaced by getStaticPluginResource(ModuleDescriptor, String, UrlMode)

getStaticPluginResourcePrefix

@Deprecated
String getStaticPluginResourcePrefix(ModuleDescriptor<?> moduleDescriptor,
                                                String resourceName)

Deprecated. Since 2.2 Use #getStaticPluginResource instead

setIncludeMode

@Deprecated
void setIncludeMode(WebResourceManager.IncludeMode includeMode)

Deprecated. Since 2.2.

See Also:

INLINE_INCLUDE_MODE