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:

ForestSpec, ForestSource

Method Summary

Modifier and Type	Method and Description
String	getDisplayName(ForestSpec spec) Suggests a user-readable name fo the given forest spec.
ForestSource	getForestSource(ForestSpec spec) Creates a forest source based on the forest spec.

Method Detail

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