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

Field Summary

static WebResourceManager.IncludeMode	DELAYED_INCLUDE_MODE
static WebResourceManager.IncludeMode	INLINE_INCLUDE_MODE

Method Summary

java.lang.String	getStaticPluginResource(ModuleDescriptor moduleDescriptor, java.lang.String resourceName) A helper method to return a url for 'plugin' resources.
java.lang.String	getStaticPluginResource(java.lang.String pluginModuleKey, java.lang.String resourceName)
java.lang.String	getStaticPluginResourcePrefix(ModuleDescriptor moduleDescriptor, java.lang.String resourceName) Deprecated. Use #getStaticPluginResource instead
java.lang.String	getStaticResourcePrefix() A helper method to return a prefix for 'system' static resources.
java.lang.String	getStaticResourcePrefix(java.lang.String resourceCounter) A helper method to return a prefix for 'system' static resources.
void	includeResources(java.io.Writer writer) Include the resources that have already been specified by the request in the page.
void	requireResource(java.lang.String resourceName) Called by a component to indicate that a certain resource is required to be inserted into this page.
void	requireResource(java.lang.String resourceName, java.io.Writer writer) Called by a component to indicate that a certain resource is required to be inserted into this page.
void	setIncludeMode(WebResourceManager.IncludeMode includeMode) Whether resources should be included inline, or at the top of the page.

Field Detail

DELAYED_INCLUDE_MODE

static final WebResourceManager.IncludeMode DELAYED_INCLUDE_MODE

INLINE_INCLUDE_MODE

static final WebResourceManager.IncludeMode INLINE_INCLUDE_MODE

Method Detail

requireResource

void requireResource(java.lang.String resourceName)

Called by a component to indicate that a certain resource is required to be inserted into this page. Note that this will always include the resources as if we are in DELAYED_INCLUDE_MODE. Use this if you do not want to inline a resource.

Parameters:

resourceName - The fully qualified plugin name to include (eg jira.webresources:scriptaculous)

Throws:

java.lang.IllegalStateException - If this method is called while not in DELAYED_INCLUDE_MODE.

requireResource

void requireResource(java.lang.String resourceName,
                     java.io.Writer writer)

Called by a component to indicate that a certain resource is required to be inserted into this page.

Parameters:

resourceName - The fully qualified plugin name to include (eg jira.webresources:scriptaculous)

writer - The writer to write the links to if the WebResourceManager.IncludeMode equals INLINE_INCLUDE_MODE

includeResources

void includeResources(java.io.Writer writer)

Include the resources that have already been specified by the request in the page. This is done by including links to the resources that have been specified.

Example - if a 'javascript' resource has been specified, this method should output:

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

Similarly for other supported resources

Parameters:

writer - The writer to write the links to

getStaticResourcePrefix

java.lang.String getStaticResourcePrefix()

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

Returns:

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

getStaticResourcePrefix

java.lang.String getStaticResourcePrefix(java.lang.String resourceCounter)

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

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.

getStaticPluginResource

java.lang.String getStaticPluginResource(ModuleDescriptor moduleDescriptor,
                                         java.lang.String resourceName)

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) %>

Returns:

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

getStaticPluginResourcePrefix

java.lang.String getStaticPluginResourcePrefix(ModuleDescriptor moduleDescriptor,
                                               java.lang.String resourceName)

Deprecated. Use #getStaticPluginResource instead

getStaticPluginResource

java.lang.String getStaticPluginResource(java.lang.String pluginModuleKey,
                                         java.lang.String resourceName)

Parameters:

pluginModuleKey - complete plugin module key

Returns:

returns the url of this plugin resource

setIncludeMode

void setIncludeMode(WebResourceManager.IncludeMode includeMode)

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