Setting Up the Integration with Gantt Charts

To start using Gantt Charts 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 Gantt Charts version.

To use API classes, add the following dependency:

CODE

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

Gantt Charts 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 Gantt Charts services

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

XML

<!-- 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 Gantt Charts API services injected into your component

JAVA

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 Gantt Charts 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:

XML

<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 Gantt Charts, or when you generally write code that uses Gantt Charts API but also should work when Gantt Charts 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 Gantt Charts API classes, your bundle will load - but if your code tries to access a class from the Gantt Charts API, you'll get a NoClassDefFoundError.
To avoid this, you need to isolate the dependency on Gantt Charts API classes - typically in some wrapper classes.

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

JAVA

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;
    }
  }
}