com.atlassian.jira.help

Interface HelpUrlsParser

All Known Implementing Classes:

InitialHelpUrlsParser, MockHelpUrlsParser

@Immutable
 @ExperimentalApi
public interface HelpUrlsParser

A parser that a creates HelpUrls from name-value pairs. Starting with version 7.0 the recommended way of obtaining a new instance is by using HelpUrlsParserBuilderFactory.

Consider the following properties file:

   url-prefix=https:///DOCS/docs-${docs.version}/
   url-prefix.ondemand=https://CAC/display/AOD/

   jira101.url=JIRA+101
   jira101.url.ondemand=JIRA+OnDemand
   jira101.title=JIRA 101
   jira101.title.ondemand=JIRA OnDemand

   default.url = Index
   default.title = JIRA Help
 

It OnDemand it produces a HelpUrls where:

• urls.getDefault() == HelpUrl{url: https://CAC/display/AOD/Index, title: "JIRA Help"}
• urls.get(default) == HelpUrl{url: https://CAC/display/AOD/Index, title: "JIRA Help"}
• urls.get(jira101) == HelpUrl{url: https://CAC/display/AOD/JIRA+OnDemand, title: "JIRA OnDemand"}
• urls.get(anyOtherKey) == HelpUrl{url: https://CAC/display/AOD/Index, title: "JIRA Help"}

In a non-OnDemand 6.2.x instance produces a HelpUrls where:

• urls.getDefault() == HelpUrl{url: https:///DOCS/docs-062/Index, title: "JIRA Help"}
• urls.get(default) == HelpUrl{url: https:///DOCS/docs-062/Index, title: "JIRA Help"}
• urls.get(jira101) == HelpUrl{url: https:///DOCS/docs-062/JIRA+101, title: "JIRA 101"}
• urls.get(anyOtherKey) == HelpUrl{url: https:///DOCS/docs-062/Index, title: "JIRA Help"}

The default URL specified via defaultUrl(String, String) is used when a default URL is not configured in the passed properties.

An injected instance is configured with the default url being null (i.e. defaultUrl(null, null)) and with the correct OnDemand status (i.e. onDemand(inOnDemand)). The object is immutable, however, you can easily create new instances of HelpUrlParser with different settings using onDemand(boolean) or defaultUrl(String, String).

An injected instance will also replace ${docs.version} and ${doc.version} text in url-prefix property with value of BuildUtilsInfo.getDocVersion(). Instance created with HelpUrlsParserBuilderFactory will perform the same substitution but may also be configured with additional target help space which will also replace ${application.help.space} placeholder in url-prefix.

Since:

v6.2.4

Method Summary

Modifier and Type	Method and Description
HelpUrlsParser	defaultUrl(String url, String title) Deprecated. use to configure parser
HelpUrlsParser	onDemand(boolean onDemand) Deprecated. use to configure parser
HelpUrls	parse(Map<String,String> properties) Parse the passed properties and return an equivalent HelpUrls instance.
HelpUrls	parse(Map<String,String> userProperties, Map<String,String> adminProperties) Parse two passed maps with user and admin properties and return an equivalent HelpUrls instance.
HelpUrls	parse(Properties properties) Parse the passed properties and return an equivalent HelpUrls instance.
HelpUrls	parse(Properties externalProperties, Properties internalProperties) Deprecated.

Method Detail

onDemand

@Nonnull
 @Deprecated
HelpUrlsParser onDemand(boolean onDemand)

Deprecated. use to configure parser

Returns a new parser that will either use or ignore .ondemand properties.

Parameters:

onDemand - true if the parser should use .ondemand properties, or false if they should be ignored.

Returns:

a new parser configured to either use or ignore .ondemand properties

defaultUrl

@Nonnull
 @Deprecated
HelpUrlsParser defaultUrl(String url,
                                                String title)

Deprecated. use to configure parser

Returns a new parser that will use the passed URL (title) in URLs that don't have a URL (title) set. It is possible for the parser to ignore these values if the input name-value pairs during a parse have their own configured default.

Parameters:

url - the default URL.

title - the default title of the URL.

Returns:

a new parser with the URL and title of the default HelpUrl configured.

parse

@Nonnull
HelpUrls parse(@Nonnull
                        Properties properties)

Parse the passed properties and return an equivalent HelpUrls instance.

Parameters:

properties - the properties to parse.

Returns:

the HelpUrls representation of the passed properties.

parse

@Internal
 @Nonnull
 @Deprecated
HelpUrls parse(@Nonnull
                                                Properties externalProperties,
                                                @Nonnull
                                                Properties internalProperties)

Deprecated.

Parse the passed properties and return an equivalent HelpUrls instance.

This method should not be called by plugins as the format of internalProperties is not documented and is subject to change.

Parameters:

externalProperties - the properties to parse.

internalProperties - the internal properties to parse. These properties follow a different format to the that documented on this interface and should only be used by JIRA internally.

Returns:

the HelpUrls representation of the passed properties.

parse

@Nonnull
HelpUrls parse(@Nonnull
                        Map<String,String> properties)

Parse the passed properties and return an equivalent HelpUrls instance.

Parameters:

properties - the properties to parse.

Returns:

the HelpUrls representation of the passed properties.

parse

@Nonnull
HelpUrls parse(Map<String,String> userProperties,
                        Map<String,String> adminProperties)

Parse two passed maps with user and admin properties and return an equivalent HelpUrls instance. Default url will be read from the first map. Any other entries existing in both maps will be overwritten by entries from second (admin properties) map.

Parameters:

userProperties - map containing user properties

adminProperties - map containing admin properties

Returns:

the HelpUrls representation of the passed properties.