Package com.almworks.jira.structure.api.forest

Interface ForestService

@PublicApi public interface ForestService

ForestService manages all structured content.

This component provides instances of ForestSource that correspond to a ForestSpec. The forest spec serves as an identifier of the forest and a recipe for its assembly. The forest source provides live updates to the forest content that can be shown to the user or used in calculations.

The automation engine, which produces dynamic content for the forests, is also working behind the scenes in this component. Unless skeleton flag is specified in the ForestSpec (and also unless showing a historical version of a structure), all content coming out of forest source will have the results of automation.

The instances of ForestSource can be cached by Structure and shared among different threads and callers. However, the caller should not store ForestSource for an extended period of time — normally, an instance must be requested from ForestService every time a new request comes.

See Also:

  • Method Details

    • getForestSource

      @NotNull ForestSource getForestSource(@Nullable ForestSpec spec) throws StructureException

      Creates a forest source based on the forest spec.

      If spec is secured (see ForestSpec.secure(String), this method also checks that the user the spec is secured for has permissions to view the referred structure. If permission check fails, StructureException is thrown.

      Parameters:
      spec - forest specification
      Returns:
      forest source
      Throws:
      StructureException - if the forest source cannot be created

    • getDisplayName

      @NotNull String getDisplayName(@Nullable ForestSpec spec)

      Suggests a user-readable name fo the given forest spec. This can be displayed as the title of the forest.

      Provides text in the current user's locale.

      Parameters:
      spec - forest specification
      Returns:
      non-empty string that can be used to name the content