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

Interface ForestSource

All Superinterfaces:
VersionedDataSource<VersionedForestUpdate>
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.

State

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.

Actions

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).

See Also:

  • Method Details

    • getLatest

      @NotNull VersionedForest getLatest()
      Returns a snapshot of the current state.

    • hasUpdate

      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.

      Parameters:
      sinceVersion - current version of the forest that the caller has
      Returns:
      false 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.

    • apply

      @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.

      Parameters:
      action - the action to apply
      parameters - additional parameters. Some parameters are defined in ActionParameters.
      Returns:
      the result of successful application of the action
      Throws:
      StructureInteractionException - if additional information is needed from the actor
      StructureException - if the action cannot be executed

    • apply

      default ActionResult apply(ForestAction action) throws StructureException
      Convenient method to call apply(ForestAction, Map) with an empty parameter map.
      Parameters:
      action - the action to apply
      Returns:
      the result of successful application of the action
      Throws:
      StructureInteractionException - if additional information is needed from the actor
      StructureException - if the action cannot be executed

    • isActionable

      default boolean isActionable()
      Checks if the forest source supports actions in principle. A 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.
      Returns:
      false if it is guaranteed that apply() methods would fail every time

    • getHealth

      @NotNull default ForestSourceHealthStatus getHealth()