NavBuilder

A key which is wrapped in TOKEN_PREFIX and TOKEN_SUFFIX to produce a base URL token.

The key used needs to contain (preferably end with) something which is escaped when URL-encoded. Doing so causes the end token to be different depending on whether the base URL has been encoded and allows callers to encode the value they replace it with. That, in turn, ensures the resulting full URL has correct encoding from beginning to end.

Over and above containing something which requires encoding, the value needs to encode reliably. That means if the token has been encoded 4 times, any caller performing the substitution should be able to detect that count, because they will need to encode the replacement value 4 times over as well.

The current choice is a single trailing %. On first encoding, this produces "%25"; second produces "%2525", third produces "%252525", etc. This allows for two use cases:

1. I don't care about encoding: Use a regular expression which ignores any number of 25s after the trailing % and before the closing TOKEN_SUFFIX
2. I want to encode by depth: Use the index of TOKEN_PREFIX + this key to find the first 25, if any are present, and the location of the first TOKEN_SUFFIX to find the end. Use the number of 25s present to determine the depth

The fully-computed base URL token, comprised of TOKEN_PREFIX, BASE_URL_KEY and TOKEN_SUFFIX.

A prefix which is applied to the beginning of tokens which are emitted in built URLs.

A suffix which is appended to the ending of tokens which are emitted in built URLs.

The query parameter on the request which indicates the base URL on emitted URLs should be replaced with BASE_URL_TOKEN instead. Using this token allows callers to format in their own base URL for producing links which are correct based on their context.

For example, to better explain the need for this, consider the following:

• A Jira instance is running with a public address of http://jira.example.com
• A Stash instance is running with a public address of http://stash.example.com
• These two machines, in addition to having public-facing URLs, have a private backplane network which connects them as jira.private.example.com and stash.private.example.com
• The application link from Jira to Stash has an RPC URL of http://stash.private.example.com, so that RPC uses the fast backplane network, and a display URL of http://stash.example.com so that end users get valid links
• When requests come into Stash, if the base URL calculated by buildAbsolute() uses the HTTP request (which is the default behaviour), links are emitted pointing to http://stash.private.example.com. From an end user's browser, however, such links will not work
• Rather than trying to manually munge the URLs in the client, which is problematic and brittle, the caller can add this parameter to their request and a token suitable for replacement will be emitted in the URLs instead of a fixed base URL

/projects

/repos

This method respects the USE_BASE_URL_TOKEN parameter if present on the context request. Use buildBaseUrl() if you with to avoid this behaviour. Note: if the USE_BASE_URL_TOKEN is present this method may return a String that is not a syntactically valid URI. The base URL (the scheme, host, port etc and webapp context) will be taken from the context HTTP request, if one is present, or otherwise fall back to the configured base URL for the server.

This method does not respect the USE_BASE_URL_TOKEN parameter. Unless you have a specific need to avoid the token substitution behaviour for this particular URL, you should use buildAbsolute().

This method is equivalent to buildAbsolute(), but ignores any context HTTP request and always uses the server's configured base URL for generating the scheme, host, port etc and webapp context components of the URL.

/captcha

/getting-started

/login

/login

/passwordreset

/profile

/projects/PROJ

/projects/PROJ

/projects/PROJ/repos/REPO

/retrievePassword

/j_atl_security_check

/setup

/signup

/tmp

Retrieve a builder for constructing URLs related to temporary data.

/users/SLUG or /bots/SLUG

/users/SLUG or /bots/SLUG

/mvc/xsrfNotification (as this is generated by a forward it doesn't go through the rewrite filter, and so needs the /mvc explicitly)