Package 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

In 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 object is immutable, however, you can easily create new instances of HelpUrlParser with different settings using HelpUrlsParserBuilderFactory.HelpUrlsParserBuilder.

The default URL specified via {@link builder.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. builder.defaultUrl(null, null)) and with the correct OnDemand status (i.e. builder.onDemand(inOnDemand)).

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 Details

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