ForestSpec (Structure API 17.24.0 API)

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:
- A specific structure — see structure(long)
- A query — see sQuery(String, String)
- A specific version of a structure — see version(long, int)
- A user's clipboard — see clipboard(String)
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:

ForestService, ForestSpec.Builder

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ForestSpec.Builder` A builder for forest spec.
`static class`	`ForestSpec.SQuery` Represents a SQuery.
`static class`	`ForestSpec.Transformation` Represents a transformation, which is a call to a generator with specified parameters.
`static interface`	`ForestSpec.Visitor<T>`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`<T> T`	`accept(ForestSpec.Visitor<T> visitor)` Applies `ForestSpec.Visitor` to this spec.
`static ForestSpec.Builder`	`builder()` Creates a new builder for `ForestSpec`.
`static ForestSpec.Builder`	`builder(ForestSpec spec)` Creates a new build that can be used to adjust a given `ForestSpec`.
`static ForestSpec`	`clipboard(String sessionId)` Constructs `ForestSpec` that represents a user's clipboard.
`boolean`	`equals(Object o)`
`static ForestSpec`	`fromRest(RestForestSpec rfs)` This method can be used to restore a forest spec from a REST transfer object.
`String`	`getClipboardSessionId()` Returns session ID used to identify the clipboard if the base content is a clipboard, null otherwise.
`ForestSpec.Transformation`	`getLastTransformation()` Returns the last transformation used by this forest spec.
`ForestSpec`	`getLastTransformedSpec()` For a forest spec with transformations, returns the forest spec without the last used transformation.
`ForestSpec.SQuery`	`getSQuery()` Returns `ForestSpec.SQuery` if the base content is a SQuery, null otherwise.
`Long`	`getStructureId()` Returns structure ID if the base content is a structure or a structure version, null otherwise.
`List<ForestSpec.Transformation>`	`getTransformations()` Returns the list of transformations applied to the base forest.
`ForestSpec`	`getUnsecured()` Returns the same forest spec, but with `secured` flag turned off.
`ForestSpec`	`getUntransformedSpec()` Returns the same forest spec but without transformations.
`String`	`getUserKey()` Returns user key that is used to run transformations and to secure the forest, if corresponding options are present.
`Integer`	`getVersion()` Returns version if the base content is a structure version, null otherwise.
`int`	`hashCode()`
`boolean`	`hasTitle()` Returns true if forest spec has `title` option on.
`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.
`boolean`	`isSkeleton()` Returns true if forest spec produces a base forest without running generators.
`boolean`	`isTransformed()` Returns true if this forest spec contains transformation.
`ForestSpec`	`secure(String userKey)` Creates a new `ForestSpec` that is secured for the specified user.
`static ForestSpec`	`skeleton(long structureId)` Constructs `ForestSpec` that represents a structure with no dynamic content.
`static ForestSpec`	`sQuery(String type, String query)` Constructs `ForestSpec` that represents a structured query.
`static ForestSpec`	`structure(long structureId)` Constructs `ForestSpec` that represents a structure.
`static ForestSpec`	`structure(long structureId, ApplicationUser user)` Constructs `ForestSpec` that represents a structure.
`RestForestSpec`	`toRest()` Produces REST forest specification based on this instance's parameters.
`String`	`toString()`
`ForestSpec`	`transform(String module, Map<String,Object> params)` Creates a transformed `ForestSpec` that adds a single transformation to the result of the original forest spec.
`static ForestSpec`	`unsecuredStructure(long structureId)` Constructs `ForestSpec` that represents a structure.
`static ForestSpec`	`version(long structureId, int version)` Constructs `ForestSpec` that represents a historical version of a structure.
`ForestSpec`	`withoutTitle()` Returns the same forest spec but without `title` option.
`ForestSpec`	`withTitle()` Returns the same forest spec but with `title` option.

Methods inherited from class Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - 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(long, ApplicationUser), unsecuredStructure(long), ForestService.getForestSource(ForestSpec), StructureAuth
  - 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:
    
    structure(long), unsecuredStructure(long), ForestService.getForestSource(ForestSpec)
  - 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:
    
    structure(long), structure(long, ApplicationUser)
  - 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:
    
    HistoryService
  - 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:
    
    CoreStructureGenerators, CoreGeneratorParameters
  - 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()
  - getLastTransformation
```
@Nullable
public ForestSpec.Transformation getLastTransformation()
```
    Returns the last transformation used by this forest spec. Returns null if there are no transformations.
    
    See Also:
    
    getLastTransformedSpec()
  - 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.

Class ForestSpec

Base content specification

Adjustments

Nested Class Summary

Method Summary

Methods inherited from class Object

Method Detail

builder

builder

structure

structure

unsecuredStructure

skeleton

version

sQuery

clipboard

secure

transform

isTransformed

getLastTransformedSpec

getLastTransformation

getUntransformedSpec

getStructureId

getVersion

getSQuery

getClipboardSessionId

getUserKey

getTransformations

isSecured

isSkeleton

hasTitle

getUnsecured

withoutTitle

withTitle

accept

equals

hashCode

toString

fromRest

toRest