Summary: Methods | [Expand All]
@Immutable @ExperimentalApi public interface

HelpUrlsParser

com.atlassian.jira.help.HelpUrlsParser
Known Indirect Subclasses

@ExperimentalApi

This interface is considered usable by external developers but its contracts have not stabilized.

Experimental APIs may be changed at any time before being marked @Internal or @PublicApi.

Class Overview

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

Summary

Public Methods
@Nonnull @Deprecated HelpUrlsParser defaultUrl(String url, String title)
This method is deprecated. use {@@link HelpUrlsParserBuilderFactory} to configure parser
@Nonnull @Deprecated HelpUrlsParser onDemand(boolean onDemand)
This method is deprecated. use {@@link HelpUrlsParserBuilderFactory} to configure parser
@Nonnull HelpUrls parse(Map<String, String> properties)
Parse the passed properties and return an equivalent HelpUrls instance.
@Nonnull HelpUrls parse(Properties properties)
Parse the passed properties and return an equivalent HelpUrls instance.
@Internal @Nonnull @Deprecated HelpUrls parse(Properties externalProperties, Properties internalProperties)
Parse the passed properties and return an equivalent HelpUrls instance.
@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.

Public Methods

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

This method is deprecated.
use {@@link HelpUrlsParserBuilderFactory} 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.

@Nonnull @Deprecated public HelpUrlsParser onDemand (boolean onDemand)

This method is deprecated.
use {@@link HelpUrlsParserBuilderFactory} 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

@Nonnull public HelpUrls parse (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.

@Nonnull public HelpUrls parse (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.

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

@Internal

This method is an internal implementation detail and will change without notice.

Clients that depend on @Internal classes and interfaces can not expect to be compatible with any version other than the version they were compiled against (even minor version and milestone releases may break binary compatibility with respect to @Internal elements).

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.

@Nonnull public 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.