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

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. 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

@Deprecated
void includeResources(Writer writer)

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

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

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

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

Similarly for other supported resources

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

Parameters:

writer - The writer to write the links to

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 JavascriptWebResource.FILTER_INSTANCE, 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

@Deprecated
String getRequiredResources()

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

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

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

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

Similarly for other supported resources

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

Returns:

the resource tags for all resources previously required

See Also:

includeResources(Writer)

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 JavascriptWebResource.FILTER_INSTANCE, 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

@Deprecated
void requireResource(String moduleCompleteKey,
                                Writer writer)

Deprecated. As of 2.3.0, replaced by requireResource(String, Writer, 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).

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

Parameters:

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

writer - The writer to write the resource tags to.

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

@Deprecated
String getResourceTags(String moduleCompleteKey)

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

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

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

Parameters:

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

Returns:

the resource tags for the specified resource

Since:

2.2

See Also:

requireResource(String, Writer)

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)

getStaticResourcePrefix

@Deprecated
String getStaticResourcePrefix()

Deprecated. As of 2.3.0, replaced by 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

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

Returns:

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

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)

Deprecated. As of 2.3.0, replaced by 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

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

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

Returns:

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

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)

Deprecated. As of 2.3.0, replaced by getStaticPluginResource(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) %>

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

Parameters:

moduleCompleteKey - complete plugin module key

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

Returns:

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

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)

Deprecated. As of 2.3.0, replaced by getStaticPluginResource(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) %>

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

Parameters:

moduleDescriptor - plugin module descriptor that contains the resource

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

Returns:

returns the url of this plugin resource

See Also:

getStaticPluginResource(String, String)

getStaticPluginResource

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)

getStaticPluginResourcePrefix

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

Deprecated. Use #getStaticPluginResource instead

setIncludeMode

@Deprecated
void setIncludeMode(WebResourceManager.IncludeMode includeMode)

Deprecated. Since 2.2.

Whether resources should be included inline, or at the top of the page. In most cases, you want to leave this as the default. However, for pages that don't have a decorator, you will not be able to 'delay' including the resources (css, javascript), and therefore need to include them directly inline.

Parameters:

includeMode - If there is no decorator for this request, set this to be INLINE_INCLUDE_MODE

See Also:

DELAYED_INCLUDE_MODE, INLINE_INCLUDE_MODE