Package com.atlassian.bitbucket.nav

Interface NavBuilder

public interface NavBuilder
Helps build URLs using a fluent interface. All returned URLs are URL encoded. Example usages:
  • nb.allProjects().startAt(0).withLimit(25).buildAbsolute() => http://localhost:7990/bitbucket/projects?start=0&limit=25
  • nb.project("EX").repo("example").settings().buildRelative() => /stash/projects/EX/repos/example/settings
  • nb.project("EX").repo("example").browse().resource("foo/bar/baz.xml").buildNoContext() => /projects/EX/repos/example/browse/foo/bar/baz.xml
  • nb.project("EX").repo("example").browse().resource("foo/bar/baz.xml").onBranch("stash1.0").buildNoContext() => /projects/EX/repos/example/browse/foo/bar/baz.xml?branchName=stash1.0
  • nb.project("EX").repo("example").pullRequest("7636").buildNoContext() => /projects/EX/repos/example/pull-request/7636

  • Field Details

    • BASE_URL_KEY

      static final String BASE_URL_KEY
      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
      See Also:

    • TOKEN_PREFIX

      static final String TOKEN_PREFIX
      A prefix which is applied to the beginning of tokens which are emitted in built URLs.
      See Also:

    • TOKEN_SUFFIX

      static final String TOKEN_SUFFIX
      A suffix which is appended to the ending of tokens which are emitted in built URLs.
      See Also:

    • BASE_URL_TOKEN

      static final String BASE_URL_TOKEN
      The fully-computed base URL token, comprised of TOKEN_PREFIX, BASE_URL_KEY and TOKEN_SUFFIX.
      See Also:

    • USE_BASE_URL_TOKEN

      static final String USE_BASE_URL_TOKEN
      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
      See Also:

  • Method Details

    • buildAbsolute

      String buildAbsolute()
      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.
      Returns:
      the absolute base url (e.g. http://hostname:7990/context), with no trailing slash
      See Also:

    • buildConfigured

      String buildConfigured()
      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.
      Returns:
      the absolute base url configured for this server

    • buildBaseUrl

      String buildBaseUrl()
      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().
      Returns:
      the absolute base url (e.g. http://hostname:7990/context), with no trailing slash
      See Also:

    • buildRelative

      String buildRelative()
      Returns:
      the relative base url (e.g. /context), with no trailing slash
      See Also:

    • admin

      NavBuilder.Admin admin()

    • about

      NavBuilder.Builder<?> about()

    • pluginServlets

      NavBuilder.PluginServlets pluginServlets()

    • rest

      NavBuilder.Rest rest()

    • tmp

      NavBuilder.Tmp tmp()
      /tmp

      Retrieve a builder for constructing URLs related to temporary data.

      Returns:
      a builder for temporary data URLs

    • addons

      NavBuilder.Addons addons()
      Returns:
      a builder for UPM created URLs

    • project

      NavBuilder.Project project(@Nonnull String key)
      /projects/PROJ
      Parameters:
      key - project key
      Returns:
      a builder for urls of the named project

    • project

      NavBuilder.Project project(@Nonnull Project project)
      /projects/PROJ
      Parameters:
      project - the project
      Returns:
      a builder for urls of the named project

    • repo

      NavBuilder.Repo repo(@Nonnull Repository repository)
      /projects/PROJ/repos/REPO
      Parameters:
      repository - the repository
      Returns:
      a builder for urls of the named repository

    • login

      NavBuilder.Login login()
      /login
      Returns:
      a Login builder for the url to the login page

    • logout

      NavBuilder.Builder<?> logout()
      /login
      Returns:
      a builder for the url to the logout page

    • signup

      NavBuilder.Builder<?> signup()
      /signup
      Returns:
      a builder for the url to the signup page

    • captcha

      NavBuilder.Builder<?> captcha()
      /captcha
      Returns:
      a builder for the url to the captcha image

    • retrievePassword

      NavBuilder.Builder<?> retrievePassword()
      /retrievePassword
      Returns:
      a builder for the url to the page to retrieve your password

    • passwordReset

      NavBuilder.Builder<?> passwordReset()
      /passwordreset
      Returns:
      a builder for the url to the page to reset your password

    • profile

      NavBuilder.Profile profile()
      /profile
      Returns:
      a builder for the url to the profile page of the current user

    • user

      NavBuilder.Profile user(ApplicationUser user)
      /users/SLUG or /bots/SLUG
      Parameters:
      user - the user
      Returns:
      a builder for the url to the profile page of the supplied user

    • userBySlug

      NavBuilder.Profile userBySlug(String userSlug, UserType type)
      /users/SLUG or /bots/SLUG
      Parameters:
      userSlug - the user slug
      type - the user type
      Returns:
      a builder for the url to the profile page of the supplied user's slug

    • securityCheck

      NavBuilder.Builder<?> securityCheck()
      /j_atl_security_check
      Returns:
      a builder for the url used to check authentication credentials when logging in

    • xsrfNotification

      NavBuilder.Builder<?> xsrfNotification()
      /mvc/xsrfNotification (as this is generated by a forward it doesn't go through the rewrite filter, and so needs the /mvc explicitly)
      Returns:
      a builder for the url to use when an invalid xsrf token is detected.

    • setup

      NavBuilder.Builder<?> setup()
      /setup
      Returns:
      a builder for the first run wizard

    • allProjects

      NavBuilder.ListProjects allProjects()
      /projects
      Returns:
      a builder for the url to list all projects

    • allRepos

      NavBuilder.GlobalListRepos allRepos()
      /repos
      Returns:
      a builder for the url to list all repositories

    • createProject

      NavBuilder.CreateProject createProject()
      Returns:
      a builder for urls of the form /projects?create

    • account

      NavBuilder.UserAccount account()
      Returns:
      a builder for urls of the form /account[/*]

    • gettingStarted

      NavBuilder.GettingStarted gettingStarted()
      /getting-started
      Returns:
      a builder for urls to the Getting Started '/getting-started' page

    • dashboard

      NavBuilder.Dashboard dashboard()