Setting Up the Integration with Structure.Gantt

To start using Structure.Gantt in your app:

1. Add dependency to your pom.xml

Figure out the Version of the API that you need – it may depend on your Jira and Structure.Gantt version.

To use API classes, add the following dependency:

<dependency>
  <groupId>com.almworks.jira.structure</groupId>
  <artifactId>gantt-api</artifactId>
  <version>1.0.0</version>
  <scope>provided</scope>
</dependency>

Structure.Gantt API has dependencies on the Annotations library from JetBrains, providing @Nullable and @NotNull annotations, used throughout the API.

You don't need to explicitly add dependencies on these libraries.

2. Import Structure.Gantt services

In your atlassian-plugin.xml, use <component-import> module to import necessary Structure.Gantt services.

<!-- Import BaselineManager if you need to manage baselines. -->
<component-import key="gantt-baseline-manager" interface="com.almworks.structure.gantt.api.baseline.BaselineManager"/>

<!-- Import GanttChartManager if you're working with Gantt charts to create, search, update, and delete them. -->
<component-import key="gantt-chart-manager" interface="com.almworks.structure.gantt.api.gantt.GanttChartManager"/>

<!-- Import ResourceLevelingManager if you require functionality related to resources leveling within Gantt charts, such as resolving over-allocations. -->
<component-import key="gantt-resource-leveling-manager" interface="com.almworks.structure.gantt.api.leveling.ResourceLevelingManager"/>

3. Have Structure.Gantt API services injected into your component

public class TestComponent {
  private final BaselineManager myBaselineManager;
  private final GanttChartManager myGanttChartManager;

  public TestComponent(BaselineManager baselineManager, GanttChartManager ganttChartManager) {
    myBaselineManager = baselineManager;
    myGanttChartManager = ganttChartManager;
  }

  ...
}

That's it! Now you can work with Structure.Gantt API.

Controlling Compatibility

You can declare dependency on the specific range of the API versions via OSGi bundle instructions added to your pom.xml or atlassian-plugin.xml. Figure out the compatible OSGi versions range from the API versions table and modify your pom.xml to contain the following:

<plugin>
  <groupId>com.atlassian.maven.plugins</groupId>
  <artifactId>maven-jira-plugin</artifactId>
  ...
  <configuration>
    <instructions>
      <Import-Package>
        com.almworks.structure.gantt.api*;version="[1,2)",
        org.jetbrains.annotations;version="0"
      </Import-Package>
    </instructions>
  </configuration>
</plugin>

Declare Optional Dependency

If you are integrating your app with Structure.Gantt, or when you generally write code that uses Structure.Gantt API but also should work when Structure.Gantt is not present, you need to declare that dependencies are optional and isolate dependencies in the code.

Since your app must first be loaded as an OSGi bundle, it should declare dependencies from the Structure API packages as optional.

Modify <Import-Package> declaration in your pom.xml or atlassian-plugin.xml and add the resoltion:=optional classifier.

<Import-Package>
  com.almworks.jira.structure*;version="[16,17)";resolution:=optional,
  com.almworks.integers*;version="0";resolution:=optional,
  org.jetbrains.annotations;version="0";resolution:=optional
</Import-Package>

So once you have declared the optional resolution of the Structure.Gantt API classes, your bundle will load - but if your code tries to access a class from the Structure.Gantt API, you'll get a NoClassDefFoundError.
To avoid this, you need to isolate the dependency on Structure.Gantt API classes - typically in some wrapper classes.

Here's a sample wrapper for the Structure.Gantt API that provides GanttChartManager wrapper (whatever it does) when Structure.Gantt is available and null otherwise.

public class GanttChartAccessor {
  public static boolean isStructureGanttPresent() {
    if (!ComponentAccessor.getPluginAccessor().isPluginEnabled("com.almworks.structure.gantt")) {
      return false;
    }
    try {
      Class.forName("com.almworks.structure.gantt.api.gantt.GanttChartManager");
    } catch (Exception e) {
      return false;
    }
    return true;
  }

  public static GanttChartManager getGanttChartManager() {
    if (!isStructureGanttPresent()) return null;
    GanttChartManager ganttChartManager;
    try {
      ganttChartManager = ComponentAccessor.getOSGiComponentInstanceOfType(GanttChartManager.class);
      return ganttChartManager;
    } catch (Exception e) {
      return null;
    }
  }
}