Package com.almworks.jira.structure.api.attribute.loader

Interface PropagateAttributeLoader<T>

Type Parameters:
T - type of the loaded value
All Superinterfaces:
AttributeLoader<T>, MultiRowAttributeLoader<T>, RowAttributeLoader<T>
All Known Implementing Classes:
AbstractPropagateLoader, DelegatingPropagateAttributeLoader, InheritedValueLoader
@PublicSpi public interface PropagateAttributeLoader<T> extends MultiRowAttributeLoader<T>

Propagate attributes have values calculated down through the hierarchy. The child row depends on the value of its parent. For example, an issue field value may be inherited from the parent unless the issue has its own value in that field.

Propagate loader represents a propagate attribute. Propagate loading function for a row R can calculate values based on:

  • Already calculated value of the same attribute for the parent row of R;
  • Values of attribute dependencies for the row R (but not its parent or siblings);
  • StructureRow data for R, its parent and siblings;
  • Context values, if declared with AttributeLoader.getContextDependencies().

The loader must be a stable function. It must not depend on any other inputs, and should provide the same result for the same inputs every time: V(row) = PROPAGATE(V(parent(row)), dependencies(row)).

Loading one sibling should not depend, imply or affect loading another sibling. Only some of the siblings may be loaded in one request.

The value for the parent rows and the dependencies for the current row are guaranteed to be loaded by the time the loading function is called. Note that you cannot get dependency values for the parent row - only for the child rows that are actually being loaded.

Using loader data

Note that sometimes a propagate loader will need to store more data in AttributeValue than the resulting Java type allows. In that case, use loader data - see AttributeValue.withData(java.lang.Object).

Sensitive data control

A propagate, as well as all multi-row loaders, is potentially capable of accessing data calculated for rows that the requesting user is not allowed to see. For example, an allocated budget may be inherited from a larger-scope budgeting parent issue, and a user may not have access to that issue.

If the propagated attribute is considered sensitive (according to StructureConfiguration.getAttributeSensitivitySettings()), then the calls to AttributeLoaderContext.getDependencyValue(com.almworks.jira.structure.api.attribute.AttributeSpec<V>) will not disclose the hidden value. Instead, the loader function will receive AttributeValue.inaccessible().

In other words, you should not worry about implementing security checks in a propagate, the system does it for you.

Super-root support

Propagates may calculate a value for the super-root row. (See SuperRootRow.) This value will then be used as the parent value when calculating values for forest roots.

However, that feature is optional and disabled by default. In order to allow loading a value for the super-root, the propagate loader must override isLoadingSuperRoot() method.

Super-root value is loaded via the usual call to loadChildren(com.almworks.jira.structure.api.attribute.AttributeValue<T>, com.almworks.jira.structure.api.attribute.loader.PropagateAttributeContext.Parent), with super-root being the child (!), the parent row being null, and the parent row value being AttributeValue.undefined().

See Also:

  • Method Details

    • loadChildren

      @Nullable BiFunction<StructureRow,PropagateAttributeContext,AttributeValue<T>> loadChildren(@NotNull AttributeValue<T> parentValue, @NotNull PropagateAttributeContext.Parent context)

      Provider of a loading function for the children of the given parent row. When there's a need to load a propagate value for row R, then first this method is called for the parent of R. Then the function that is received will be called to calculate the value for R and any other siblings that are also requested in this loading process.

      The implementation can make preparatory calculations and then return a function that will produce results for specific rows. The value of the dependencies for the children rows are available only when that function is called.

      You should not include costly calculations for all the children rows in the implementation of this method, because loadChildren() may called even when only one child row needs to be calculated.

      The implementation must be a stable function - see PropagateAttributeLoader. Note that loadChildren() and the functions it produced may be called intermittently without any particular order. In other words, the function produced by loadChildren() should be working even after another loadChildren() is called.

      If for some reason this loader is not applicable for the given row, it should return null. Note, however, that if multiple propagate loaders work on the same attribute, it could be tricky and lead to unexpected results.

      Parameters:
      parentValue - the value of this attribute for the parent row, or AttributeValue.undefined() if there's no parent
      context - loading context
      Returns:
      a function that will produce a value for every child row of this parent, given the child row and the loading context, or null if the values for the children rows of this parent cannot be loaded with this loader

    • isLoadingSuperRoot

      default boolean isLoadingSuperRoot()

      Determines if this loader can provide a value for the super-root row.

      When this method returns false, the super-root value will always be AttributeValue.undefined(). When it is true, the super-root value will be determined by calling loadChildren(com.almworks.jira.structure.api.attribute.AttributeValue<T>, com.almworks.jira.structure.api.attribute.loader.PropagateAttributeContext.Parent) with null as the parent row and super-root as the child row.

      The returned value must be the same throughout the lifetime of the object.

      Returns:
      true if this loader should be called to load the value for the super-root item
      See Also:
      • SuperRootRow