External System Integration

Project Data Domain

The external system wrapper is required to be able to build project info on the basis of the given external system config. That information is built with the following base classes:

• DataNode

• Key

• ExternalEntityData

The DataNode class is just a holder for the target data (a data type is defined by the Key). Multiple DataNode objects might be organized in directed graph where every edge identifies parent-child relation.

For example, a simple one-module project might look as below:

The IDE provides a set of built-in Key and ExternalEntityData classes but any external system integration or third-party plugin developer might enhance project data by defining custom Key and ExternalEntityData and store them at a child of appropriate DataNode.

Managing Project Data

Processing project data built on an external system config basis can be performed with ProjectDataService. It is a strategy which knows how to manage particular ExternalEntityData. For example, when we want to import a project from an external model, we can start with the top level DataNode which references project info and then import its data using corresponding service.

Custom services can be registered via com.intellij.externalProjectDataService extension point.

The good thing is that we can separate project parsing and management here. That means that a set of DataNode, Key and ProjectDataServices can be introduced for particular technology and then every external system integration can build corresponding data if necessary using it.

Importing from External Model

The IntelliJ Platform provides an API for importing projects from external models:

• ProjectImportBuilder

• ProjectImportProvider

There are two classes built on the template method pattern which simplify implementation:

• AbstractExternalProjectImportBuilder

• AbstractExternalProjectImportProvider

Note that AbstractExternalProjectImportBuilder is built on top of the 'external system settings' controls.

Concrete implementations should be registered in com.intellij.projectImportBuilder and com.intellij.projectImportProvider extension points accordingly.

Example of the project import provider and builder for Gradle:

• JavaGradleProjectImportProvider

• JavaGradleProjectImportBuilder

Auto-Import for ExternalSystemManager Implementation

Describe project's settings files to track by having external system ExternalSystemManager implement ExternalSystemAutoImportAware.

Auto-Import for Standalone External Systems

Some external systems don't have ExternalSystemManager (e.g., Maven), but they also can use auto-import core to track changes in settings files. For this, implement ExternalSystemProjectAware interface that describes settings files for tracking and an action to reload the project model. Then register the instance with ExternalSystemProjectTracker to start tracking.

Icon for Reload Notification

From 2020.1, the icon for reload notification can be specified per external system. Implement ExternalSystemIconProvider and register via com.intellij.externalIconProvider extension point in plugin.xml. Alternatively, set reloadIcon field external system implements ExternalSystemIconProvider directly.