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

Class ForestSpec

Object
ForestSpec
@PublicApi @Immutable public final class ForestSpec extends Object

ForestSpec is used to identify structured content. All content that can be displayed by the Structure Widget in the Grid panels — structures, queries and others — is identified by ForestSpec.

An instance of ForestSpec can be created through one of the factory methods, or deserialized from JSON. It then can be fed to ForestService to obtain ForestSource. The ForestSource can be asked for an update of the forest content, based on the last version that the caller has observed and cached.

Unlike ForestSource, instances of ForestSpec can be stored for a long time.

ForestSpec parameters belong to two groups: base content specification and adjustment specification. A ForestSource will first produce the base content and then will make additional adjustments to it, according to the spec.

Base content specification

Base content can be of the following types, each having its own factory method:

Adjustments

The following parameters adjust the produced content:

  • Transformations apply generators to the base content — see transform(String, Map). This is what Structure uses in the transformations and quick transformations panels.
  • "Secured" parameter specifies that the content must be filtered for access and all sub-trees with the items that the user cannot see must be removed. Very important — secure(String)
  • Setting title parameter to true would make the content placed under the top-level "title" item — ForestSpec.Builder.setTitle(boolean)
  • Setting skeleton parameter to true would prevent Structure engine from generating the dynamic content. The result would be a forest with only static content, including generators, but without generators' action — skeleton(long)

Additionally, userKey parameter specifies the account, which is used to:

  • secure the forest, if secured parameter is set, and
  • run transformations under, if transformations are specified.

Note that there are no permission checks when ForestSpec is created. Permissions are checked only when ForestService.getForestSource(ForestSpec) is called.

See Also:

  • Method Details

    • builder

      @NotNull public static ForestSpec.Builder builder()
      Creates a new builder for ForestSpec.

    • builder

      @NotNull public static ForestSpec.Builder builder(@Nullable ForestSpec spec)
      Creates a new build that can be used to adjust a given ForestSpec.

    • structure

      @NotNull public static ForestSpec structure(long structureId)

      Constructs ForestSpec that represents a structure. The resulting content would display the specified structure with all dynamic content properly calculated.

      The resulting forest spec is secured for the current user. The forests produced by the corresponding forest source will exclude sub-trees that do not contain items visible to the user.

      Parameters:
      structureId - structure ID
      Returns:
      forest spec
      See Also:

    • structure

      @NotNull public static ForestSpec structure(long structureId, @Nullable ApplicationUser user)

      Constructs ForestSpec that represents a structure. The resulting content would display the specified structure with all dynamic content properly calculated.

      The resulting forest spec is secured for the specified user. The forests produced by the corresponding forest source will exclude sub-trees that do not contain items visible to the user.

      Parameters:
      structureId - structure ID
      Returns:
      forest spec
      See Also:

    • unsecuredStructure

      @NotNull public static ForestSpec unsecuredStructure(long structureId)

      Constructs ForestSpec that represents a structure. The resulting content would display the specified structure with all dynamic content properly calculated.

      The resulting forest spec is unsecured. Use secure(String) or structure(long, ApplicationUser) to properly filter the content for a given user.

      Parameters:
      structureId - structure ID
      Returns:
      forest spec
      See Also:

    • skeleton

      @NotNull public static ForestSpec skeleton(long structureId)

      Constructs ForestSpec that represents a structure with no dynamic content. The resulting content would show only static rows of the structure, including generators, but generators will not have acted.

      The resulting forest spec is unsecured. Use secure(String) to properly filter the content for a given user.

      Parameters:
      structureId - structure ID
      Returns:
      forest spec

    • version

      @NotNull public static ForestSpec version(long structureId, int version)

      Constructs ForestSpec that represents a historical version of a structure. The resulting content would only display the manually added rows — automation does not work on historical versions.

      The resulting forest spec is unsecured. Use secure(String) to properly filter the content for a given user.

      Parameters:
      structureId - structure ID
      version - version number
      Returns:
      forest spec
      See Also:

    • sQuery

      @NotNull public static ForestSpec sQuery(@NotNull String type, @NotNull String query)

      Constructs ForestSpec that represents a structured query. A structured query is a textual, human-readable definition of the content.

      There may be different types of SQuery. So far, the following are supported:

      • jql query produces a flat structure with results of JQL query (up to 1000 issues).
      • text query produces a flat structure with results of text-based JQL query (up to 1000 issues).
      • cql query works only if Structure.Pages is installed and configured, it produces a flat structure with results of CQL query in all connected Confluence instances (up to 1000 pages).

      The resulting forest spec is secured for the current user (see also StructureAuth). The result will be filtered according to the user's access to the items. Use getUnsecured() to get an unsecured version of the result, or secure(String) to secure it for another user.

      Parameters:
      type - type of query
      query - query text
      Returns:
      forest spec

    • clipboard

      @NotNull public static ForestSpec clipboard(@NotNull String sessionId)

      Constructs ForestSpec that represents a user's clipboard. The clipboard's lifecycle is tied to the user's session, so we're using session ID to identify the user.

      Parameters:
      sessionId - session ID from servlet subsystem
      Returns:
      forest spec
      See Also:
      • HttpServletRequest.getSession()

    • secure

      @NotNull public ForestSpec secure(@Nullable String userKey)

      Creates a new ForestSpec that is secured for the specified user. The rows will be checked and all sub-trees that contain only the items that the user does not have read access to will be removed.

      Parameters:
      userKey - user key
      Returns:
      adjusted forest spec

    • transform

      @NotNull public ForestSpec transform(@NotNull String module, @Nullable Map<String,Object> params)

      Creates a transformed ForestSpec that adds a single transformation to the result of the original forest spec. The transformation is specified by the module key of the generator and the parameters map.

      The new ForestSpec will have the current user as its userKey parameter. Note that this is the user account under which the generators will execute, when performing all transformations, not only the most recent one.

      The resulting forest spec's "secured" flag will be the same as isSecured() for this forest spec.

      Parameters:
      module - complete plugin module key of the generator that should perform the transformation
      params - parameters for the generator
      Returns:
      adjusted forest spec
      See Also:

    • isTransformed

      public boolean isTransformed()
      Returns true if this forest spec contains transformation.

    • getLastTransformedSpec

      @Nullable public ForestSpec getLastTransformedSpec()
      For a forest spec with transformations, returns the forest spec without the last used transformation. If the forest spec does not contain transformations, returns null.
      See Also:

    • getLastTransformation

      @Nullable public ForestSpec.Transformation getLastTransformation()
      Returns the last transformation used by this forest spec. Returns null if there are no transformations.
      See Also:

    • getUntransformedSpec

      @NotNull public ForestSpec getUntransformedSpec()
      Returns the same forest spec but without transformations.

    • getStructureId

      @Nullable public Long getStructureId()
      Returns structure ID if the base content is a structure or a structure version, null otherwise.

    • getVersion

      @Nullable public Integer getVersion()
      Returns version if the base content is a structure version, null otherwise.

    • getSQuery

      @Nullable public ForestSpec.SQuery getSQuery()
      Returns ForestSpec.SQuery if the base content is a SQuery, null otherwise.

    • getClipboardSessionId

      @Nullable public String getClipboardSessionId()
      Returns session ID used to identify the clipboard if the base content is a clipboard, null otherwise.

    • getUserKey

      @Nullable public String getUserKey()
      Returns user key that is used to run transformations and to secure the forest, if corresponding options are present.

    • getTransformations

      @NotNull public List<ForestSpec.Transformation> getTransformations()
      Returns the list of transformations applied to the base forest.

    • isSecured

      public boolean isSecured()
      Returns true if the result will be secured, that is, the items in the forest will be checked for being accessible to the user and fully inaccessible sub-trees will be removed.

    • isSkeleton

      public boolean isSkeleton()
      Returns true if forest spec produces a base forest without running generators.

    • hasTitle

      public boolean hasTitle()
      Returns true if forest spec has title option on.

    • getUnsecured

      @NotNull public ForestSpec getUnsecured()
      Returns the same forest spec, but with secured flag turned off.

    • withoutTitle

      @NotNull public ForestSpec withoutTitle()
      Returns the same forest spec but without title option.

    • withTitle

      @NotNull public ForestSpec withTitle()
      Returns the same forest spec but with title option.

    • accept

      public <T> T accept(ForestSpec.Visitor<T> visitor) throws StructureException
      Applies ForestSpec.Visitor to this spec.
      Throws:
      StructureException

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • fromRest

      @NotNull public static ForestSpec fromRest(@Nullable RestForestSpec rfs) throws IllegalArgumentException
      This method can be used to restore a forest spec from a REST transfer object.
      Parameters:
      rfs - REST forest spec
      Returns:
      ForestSpec
      Throws:
      IllegalArgumentException - if the transfer object is invalid

    • toRest

      @NotNull public RestForestSpec toRest()
      Produces REST forest specification based on this instance's parameters.