This page provides a high-level overview of the External System subsystem. There are multiple project management systems (Apache Maven, Gradle, sbt, etc.) and IntelliJ Platform provides a mechanism to support them in IDEs.
Most of the project management systems provide a similar set of facilities from the integration point of view:
build a project from external system config (pom.xml, build.gradle.kts, etc.)
provide a list of available tasks
allow executing a particular task
and more
That means that we can separate external system-specific logic and general IDE processing. The External System subsystem provides an API for wrapping external system elements and extensible IDE-specific processing logic.
Project Management Project Data DomainThe 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:
parent DataNode DataNode child n DataNode ... child 1 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 a directed graph where every edge identifies parent-child relation.
For example, a simple one-module project might look as below:
DataNode<ProjectData> DataNode<ModuleData> DataNode<LibraryData> (JUnit) DataNode<ContentRootData> DataNode<LibraryDependencyData> (JUnit)
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.
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 the corresponding service.
Custom services can be registered via the 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 a particular technology and then every external system integration can build corresponding data if necessary using it.
The IntelliJ Platform provides an API for importing projects from external models:
There are two classes built on the template method pattern that simplify implementation:
Note that AbstractExternalProjectImportBuilder is built on top of the 'external system settings' controls.
Concrete implementations should be registered in com.intellij.projectImportBuilder extension point and com.intellij.projectImportProvider extension point accordingly.
Example of the project import provider and builder for Gradle:
Auto-ImportIt's possible to configure external system integration to automatically refresh the project structure when external project's config files are modified.
From 2020.1, auto-import cannot be disabled by a user.
Auto-Import forExternalSystemManager Implementation
Describe the project's settings files to track by having external system ExternalSystemManager implement ExternalSystemAutoImportAware.
The ExternalSystemAutoImportAware.getAffectedExternalProjectPath() method is called quite often, that's why it's expected to return control as soon as possible. Helper CachingExternalSystemAutoImportAware class might be used for caching, i.e. ExternalSystemManager which implements ExternalSystemAutoImportAware can have a field like new CachingExternalSystemAutoImportAware(new MyExternalSystemAutoImportAware()) and delegate ExternalSystemAutoImportAware.getAffectedExternalProjectPath() calls to it.
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 that describes settings files for tracking and an action to reload the project model. Then register the instance with ExternalSystemProjectTracker to start tracking.
Multiple ExternalSystemProjectAware instances can correspond to a single external system. It allows performing project reload differently depending on the set of settings files (project aware per settings file, per module, per external project, etc.).
The icon for reload notification can be specified per external system. Implement ExternalSystemIconProvider and register in com.intellij.externalIconProvider extension point in plugin.xml. Alternatively, set the reloadIcon field if the external system implements ExternalSystemIconProvider directly.
All external system settings controls are represented by implementations of ExternalSystemSettingsControl. There are general and linked project-level external system settings. A particular external system settings UI contains the following items:
General system settings
Linked external projects list
Project-level settings for the selected project
It's recommended to extend from AbstractExternalProjectSettingsControl for implementing project-level settings control as it already handles some of them.
Examples:
GradleSystemSettingsControl handling the General settings in
GradleProjectSettingsControl handling the selected Gradle project settings in
A similar approach is used for providing settings in importing external project UI. Implementation is expected to extend AbstractImportFromExternalSystemControl and instead of the linked external projects list it contains target external project path control.
Use com.jetbrains.intellij.platform:external-system-test-framework from IntelliJ Platform Artifacts Repositories.
Relevant base classes:
23 April 2025
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4