com.atlassian.plugin.webresource
Class WebResourceManagerImpl

java.lang.Object
  com.atlassian.plugin.webresource.WebResourceManagerImpl

All Implemented Interfaces:

WebResourceManager

public class WebResourceManagerImpl
extends Object
implements WebResourceManager

A handy super-class that handles most of the resource management.

To use this manager, you need to have the following UrlRewriteFilter code:

 <rule>
 <from>^/s/(.*)/_/(.*)</from>
 <run class="com.atlassian.plugin.servlet.ResourceDownloadUtils" method="addCachingHeaders" />
 <to type="forward">/$2</to>
 </rule>
 

Sub-classes should implement the abstract methods

Nested Class Summary

Nested classes/interfaces inherited from interface com.atlassian.plugin.webresource.WebResourceManager

WebResourceManager.IncludeMode

Field Summary

protected ResourceBatchingConfiguration	batchingConfiguration
protected com.atlassian.plugin.webresource.ResourceDependencyResolver	dependencyResolver
protected PluginResourceLocator	pluginResourceLocator
protected static List<com.atlassian.plugin.webresource.WebResourceFormatter>	webResourceFormatters
protected WebResourceIntegration	webResourceIntegration

Fields inherited from interface com.atlassian.plugin.webresource.WebResourceManager

DELAYED_INCLUDE_MODE, INLINE_INCLUDE_MODE

Constructor Summary

WebResourceManagerImpl(PluginResourceLocator pluginResourceLocator, WebResourceIntegration webResourceIntegration, WebResourceUrlProvider webResourceUrlProvider)

WebResourceManagerImpl(PluginResourceLocator pluginResourceLocator, WebResourceIntegration webResourceIntegration, WebResourceUrlProvider webResourceUrlProvider, ResourceBatchingConfiguration batchingConfiguration)

WebResourceManagerImpl(PluginResourceLocator pluginResourceLocator, WebResourceIntegration webResourceIntegration, WebResourceUrlProvider webResourceUrlProvider, ResourceBatchingConfiguration batchingConfiguration, com.atlassian.plugin.webresource.ResourceDependencyResolver dependencyResolver)

Method Summary

<T> T	executeInNewContext(com.google.common.base.Supplier<T> nestedExecution) Executes a Supplier within a new WebResourceManager context.
String	getRequiredResources() Deprecated.
String	getRequiredResources(UrlMode urlMode) This is the equivalent of calling getRequiredResources(UrlMode, WebResourceFilter) with the given url mode and a DefaultWebResourceFilter.
String	getRequiredResources(UrlMode urlMode, WebResourceFilter filter) Returns a String of the resources tags to the previously required resources called via requireResource methods for the specified url mode and resource filter.
protected String	getRequiredResources(UrlMode urlMode, WebResourceFilter webResourceFilter, Set<String> excludedResourceKeys, List<String> excludedContexts) Get the resources that have been required but excluding certain resource keys and certain contexts.
String	getResourceTags(String moduleCompleteKey) Deprecated.
String	getResourceTags(String moduleCompleteKey, UrlMode urlMode) Returns the resource tags of the specified resource.
protected String	getResourceTagsForAdditionalContexts(List<String> contexts) Create the HTML tags necessary for requesting the supplied contexts in addition to any contexts already requested of the WebResourceManager (using requireResourcesForContext(String)).
protected String	getResourceTagsForAdditionalContexts(List<String> contexts, UrlMode urlMode, WebResourceFilter filter)
String	getStaticPluginResource(ModuleDescriptor<?> moduleDescriptor, String resourceName) Deprecated.
String	getStaticPluginResource(ModuleDescriptor<?> moduleDescriptor, String resourceName, UrlMode urlMode) A helper method to return a url for 'plugin' resources.
String	getStaticPluginResource(String moduleCompleteKey, String resourceName) Deprecated.
String	getStaticPluginResource(String moduleCompleteKey, String resourceName, UrlMode urlMode) A helper method to return a url for 'plugin' resources.
String	getStaticPluginResourcePrefix(ModuleDescriptor<?> moduleDescriptor, String resourceName) Deprecated.
String	getStaticResourcePrefix() Deprecated.
String	getStaticResourcePrefix(String resourceCounter) Deprecated.
String	getStaticResourcePrefix(String resourceCounter, UrlMode urlMode) A helper method to return a prefix for 'system' static resources.
String	getStaticResourcePrefix(UrlMode urlMode) Deprecated.
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.
void	includeResources(Writer writer, UrlMode urlMode) This is the equivalent of of calling includeResources(Writer, UrlMode, WebResourceFilter) with the given url mode and a DefaultWebResourceFilter.
void	includeResources(Writer writer, UrlMode urlMode, WebResourceFilter webResourceFilter) Writes out the resource tags to the previously required resources called via requireResource methods for the specified url mode and resource filter.
void	requireResource(String moduleCompleteKey) Indicates that a given plugin web resource is required.
void	requireResource(String moduleCompleteKey, Writer writer) Deprecated.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

webResourceIntegration

protected final WebResourceIntegration webResourceIntegration

pluginResourceLocator

protected final PluginResourceLocator pluginResourceLocator

batchingConfiguration

protected final ResourceBatchingConfiguration batchingConfiguration

dependencyResolver

protected final com.atlassian.plugin.webresource.ResourceDependencyResolver dependencyResolver

webResourceFormatters

protected static final List<com.atlassian.plugin.webresource.WebResourceFormatter> webResourceFormatters

Constructor Detail

WebResourceManagerImpl

public WebResourceManagerImpl(PluginResourceLocator pluginResourceLocator,
                              WebResourceIntegration webResourceIntegration,
                              WebResourceUrlProvider webResourceUrlProvider)

WebResourceManagerImpl

public WebResourceManagerImpl(PluginResourceLocator pluginResourceLocator,
                              WebResourceIntegration webResourceIntegration,
                              WebResourceUrlProvider webResourceUrlProvider,
                              ResourceBatchingConfiguration batchingConfiguration)

WebResourceManagerImpl

public WebResourceManagerImpl(PluginResourceLocator pluginResourceLocator,
                              WebResourceIntegration webResourceIntegration,
                              WebResourceUrlProvider webResourceUrlProvider,
                              ResourceBatchingConfiguration batchingConfiguration,
                              com.atlassian.plugin.webresource.ResourceDependencyResolver dependencyResolver)

Method Detail

requireResource

public void requireResource(String moduleCompleteKey)

Description copied from interface: WebResourceManager

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

Specified by:

requireResource in interface WebResourceManager

Parameters:

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

See Also:

WebResourceManager.includeResources(Writer, UrlMode)

requireResourcesForContext

public void requireResourcesForContext(String context)

Description copied from interface: WebResourceManager

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

Specified by:

requireResourcesForContext in interface WebResourceManager

Parameters:

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

includeResources

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

Description copied from interface: WebResourceManager

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 WebResourceManager.requireResource(String).

Specified by:

includeResources in interface WebResourceManager

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

includeResources

public void includeResources(Writer writer,
                             UrlMode urlMode)

This is the equivalent of of calling includeResources(Writer, UrlMode, WebResourceFilter) with the given url mode and a DefaultWebResourceFilter.

Specified by:

includeResources in interface WebResourceManager

See Also:

includeResources(Writer, UrlMode, WebResourceFilter)

includeResources

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

Writes out the resource tags to the previously required resources called via requireResource methods for the specified url mode and resource filter. Note that this method will clear the list of previously required resources.

Specified by:

includeResources in interface WebResourceManager

Parameters:

writer - the writer to write the links to

urlMode - the url mode to write resource url links in

webResourceFilter - the resource filter to filter resources on

Since:

2.4

getRequiredResources

public String getRequiredResources(UrlMode urlMode)

This is the equivalent of calling getRequiredResources(UrlMode, WebResourceFilter) with the given url mode and a DefaultWebResourceFilter.

Specified by:

getRequiredResources in interface WebResourceManager

Returns:

the resource tags for all resources previously required

See Also:

getRequiredResources(UrlMode, WebResourceFilter)

getRequiredResources

public String getRequiredResources(UrlMode urlMode,
                                   WebResourceFilter filter)

Returns a String of the resources tags to the previously required resources called via requireResource methods for the specified url mode and resource filter. Note that this method will NOT clear the list of previously required resources.

Specified by:

getRequiredResources in interface WebResourceManager

Parameters:

urlMode - the url mode to write out the resource tags

filter - the web resource filter to filter resources on

Returns:

a String of the resource tags

Since:

2.4

See Also:

WebResourceManager.includeResources(Writer, UrlMode, WebResourceFilter)

getRequiredResources

protected String getRequiredResources(UrlMode urlMode,
                                      WebResourceFilter webResourceFilter,
                                      Set<String> excludedResourceKeys,
                                      List<String> excludedContexts)

Get the resources that have been required but excluding certain resource keys and certain contexts.

You should note that the WebResourceManager cannot break context batch resources down beyond the granularity of the context so excluding particular resource keys does not necessary exclude them from a context batch. To safely use this method it is expected that after the initial page load any subsequent "dynamic" requests for resources should be at the granularity of individual resources and not contexts. However you can request contexts if you are confident that there hasn't been an overlap of contexts and dynamically requested macros. A typical safe example is in Confluence when rendering macros the macro rendering process will have requested individual resources which will not exist in any contexts.

This method is available for use by sub-classes but is not part of the public interface since it does not form a complete solution for dynamic resource handling.

Parameters:

urlMode - the url mode to write out the resource tags

filter - the web resource filter to filter resources on

excludedResourceKeys - the complete key of resources to be excluded. These exclusion will not apply to any requested contexts so if a context happens to include these resource keys it will still be served (unless excluded as a context).

excludedContexts - contexts to be excluded when the tags are written

Returns:

a String of the resource tags

Since:

2.12.5

requireResource

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

Description copied from interface: WebResourceManager

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

Specified by:

requireResource in interface WebResourceManager

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

getResourceTags

public String getResourceTags(String moduleCompleteKey,
                              UrlMode urlMode)

Description copied from interface: WebResourceManager

Returns the resource tags of the specified resource. If you are outputting the value to a Writer, use WebResourceManager.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.

Specified by:

getResourceTags in interface WebResourceManager

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

See Also:

WebResourceManager.requireResource(String, Writer, UrlMode)

getResourceTagsForAdditionalContexts

protected String getResourceTagsForAdditionalContexts(List<String> contexts)

Create the HTML tags necessary for requesting the supplied contexts in addition to any contexts already requested of the WebResourceManager (using requireResourcesForContext(String)).

This is intended to be useful in the case of storing in a page render the requests that will need to be made if you want to dynamically add additional contexts after the initial render. This doesn't form a complete solution to dynamically adding resources to a page which is the reason this method is not part of the public API.

Parameters:

contexts - the additional contexts to create tags for

Returns:

the HTML tags required to request the additional context resources

getResourceTagsForAdditionalContexts

protected String getResourceTagsForAdditionalContexts(List<String> contexts,
                                                      UrlMode urlMode,
                                                      WebResourceFilter filter)

getStaticResourcePrefix

public String getStaticResourcePrefix(String resourceCounter,
                                      UrlMode urlMode)

Description copied from interface: WebResourceManager

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.

Specified by:

getStaticResourcePrefix in interface WebResourceManager

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.

getStaticPluginResource

public String getStaticPluginResource(String moduleCompleteKey,
                                      String resourceName,
                                      UrlMode urlMode)

Description copied from interface: WebResourceManager

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.

Specified by:

getStaticPluginResource in interface WebResourceManager

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.

getStaticPluginResource

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

Description copied from interface: WebResourceManager

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.

Specified by:

getStaticPluginResource in interface WebResourceManager

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:

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

See Also:

WebResourceManager.getStaticPluginResource(String, String, UrlMode)

executeInNewContext

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

Description copied from interface: WebResourceManager

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.

Specified by:

executeInNewContext in interface WebResourceManager

Parameters:

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

Returns:

the value returned by nestedExection.get()

getRequiredResources

@Deprecated
public String getRequiredResources()

Deprecated.

Specified by:

getRequiredResources in interface WebResourceManager

getResourceTags

@Deprecated
public String getResourceTags(String moduleCompleteKey)

Deprecated.

Specified by:

getResourceTags in interface WebResourceManager

getStaticPluginResource

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

Deprecated.

Specified by:

getStaticPluginResource in interface WebResourceManager

getStaticPluginResource

@Deprecated
public String getStaticPluginResource(String moduleCompleteKey,
                                                 String resourceName)

Deprecated.

Specified by:

getStaticPluginResource in interface WebResourceManager

getStaticPluginResourcePrefix

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

Deprecated.

Specified by:

getStaticPluginResourcePrefix in interface WebResourceManager

getStaticResourcePrefix

@Deprecated
public String getStaticResourcePrefix()

Deprecated.

Specified by:

getStaticResourcePrefix in interface WebResourceManager

getStaticResourcePrefix

@Deprecated
public String getStaticResourcePrefix(UrlMode urlMode)

Deprecated.

Description copied from interface: WebResourceManager

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.

Specified by:

getStaticResourcePrefix in interface WebResourceManager

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.

getStaticResourcePrefix

@Deprecated
public String getStaticResourcePrefix(String resourceCounter)

Deprecated.

Specified by:

getStaticResourcePrefix in interface WebResourceManager

includeResources

@Deprecated
public void includeResources(Writer writer)

Deprecated.

Specified by:

includeResources in interface WebResourceManager

requireResource

@Deprecated
public void requireResource(String moduleCompleteKey,
                                       Writer writer)

Deprecated.

Specified by:

requireResource in interface WebResourceManager

setIncludeMode

@Deprecated
public void setIncludeMode(WebResourceManager.IncludeMode includeMode)

Deprecated.

Specified by:

setIncludeMode in interface WebResourceManager

See Also:

WebResourceManager.INLINE_INCLUDE_MODE