public interface ForestSource extends VersionedDataSource<VersionedForestUpdate>
ForestSource
is used to retrieve a forest and get forest updates.
A forest is a core concept in Structure — structures and queries all generate a forest, which is then shown in the forest panels in the Structure Widget.
A ForestSource
is a pull-based source of data, using versioning to deliver full or incremental
updates to the caller. See VersionedDataSource
for the general concept of versioned data source.
You can get an instance of ForestSource
from ForestService
by providing a ForestSpec
.
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.
The full state of the ForestSource
is represented by VersionedForest
, which is just a
Forest
tagged with a DataVersion
. When applying full update, the caller should replace the
old forest with the new VersionedForest
.
The incremental update is represented as a list of ForestChange
objects, each describing an atomic
change. When applying incremental update, forest changes must be applied to the old state one by one in the
correct order.
Most ForestSource
instances support actions — changes that are applied to the source of the
forest such as items addition or movement. ForestAction
abstract class and its sub-classes define
the range of possible actions. They are really basic: add, move, remove or copy specific rows in the forest.
To apply the action, call apply(ForestAction)
method. A successful application of an action may
lead to various effects — represented by AppliedEffect
. In a fully static structure, without
dynamic content, all actions will update the contents of the structure. In a dynamic structure, a forest
action applied to the dynamic content may actually change something like JIRA issue values, links or anything
else, in such a way that the next forest update will show the desired result (item moved, added or removed).
ForestService
,
VersionedDataSource
,
VersionedForestUpdate
Modifier and Type | Method and Description |
---|---|
default ActionResult |
apply(ForestAction action)
Convenient method to call
apply(ForestAction, Map) with an empty parameter map. |
ActionResult |
apply(ForestAction action,
Map<String,Object> parameters)
Applies a forest action to this source.
|
default ForestSourceHealthStatus |
getHealth() |
VersionedForest |
getLatest()
Returns a snapshot of the current state.
|
boolean |
hasUpdate(DataVersion sinceVersion)
This method allows to quickly check if the caller has the last version of the forest.
|
default boolean |
isActionable()
Checks if the forest source supports actions in principle.
|
getCurrentVersion, getUpdate
@NotNull VersionedForest getLatest()
boolean hasUpdate(@NotNull DataVersion sinceVersion)
This method allows to quickly check if the caller has the last version of the forest.
Although the same can be done by just requesting an update, this method can be optimized by the Structure engine.
Note that if this method returns true
, it is not guaranteed that there will be a non-empty update.
sinceVersion
- current version of the forest that the caller hasfalse
if the version is the most recent, i.e. calling VersionedDataSource.getUpdate(DataVersion)
would
definitely result in an empty update; true
if the version specified is probably not the most
recent, i.e. calling VersionedDataSource.getUpdate(DataVersion)
maybe would result in an update.@NotNull ActionResult apply(ForestAction action, Map<String,Object> parameters) throws StructureException
Applies a forest action to this source. If the method returns and does not throw an exception, the action
has been successful and the outcome can be retrieved from the returned ActionResult
.
The method throws StructureException
if the action cannot be applied. The exception object can be
inspected for additional information about the problem — use StructureException.getLocalizedMessage()
for a (hopefully) user-friendly message, and StructureException.getRow()
to identify the row ID that is
associated with the problem.
A special case of the action application problem is represented by StructureInteractionException
.
This exception, a sub-class of StructureException
, is thrown when Structure needs additional information
from the user to execute an action. It can be a decision about which generator must process the action, or a
confirmation from the user about a bulk action, or something else. The calling code may figure out the answers
and apply the action again, passing the answers in parameters
.
action
- the action to applyparameters
- additional parameters. Some parameters are defined in ActionParameters
.StructureInteractionException
- if additional information is needed from the actorStructureException
- if the action cannot be executeddefault ActionResult apply(ForestAction action) throws StructureException
apply(ForestAction, Map)
with an empty parameter map.action
- the action to applyStructureInteractionException
- if additional information is needed from the actorStructureException
- if the action cannot be executeddefault boolean isActionable()
false
result means that any call to apply(com.almworks.jira.structure.api.forest.action.ForestAction, java.util.Map<java.lang.String, java.lang.Object>)
would fail. A true
result means that some actions may succeed.false
if it is guaranteed that apply()
methods would fail every time@NotNull default ForestSourceHealthStatus getHealth()
Copyright © 2024 Tempo Software. All Rights Reserved.