Plugin Services
A service is a plugin component loaded on demand when your plugin calls the getService()
method of ServiceManager
.
The IntelliJ Platform ensures that only one instance of a service is loaded even though it is called several times.
A service must have an implementation class that is used for service instantiation. A service may also have an interface class used to obtain the service instance and provide the service's API.
A service needing a shutdown hook/cleanup routine can implement Disposable
and perform necessary work in dispose()
(see Automatically Disposed Objects).
Types
The IntelliJ Platform offers three types of services: application level services (global singleton), project level services, and module level services. For the latter two, a separate instance of the service is created for each instance of its corresponding scope, see Project Model Introduction.
Constructor
Project/Module level service constructors can have a Project
/ Module
argument. To improve startup performance, avoid any heavy initializations in the constructor.
Light Services
A service not going to be overridden does not need to be registered in plugin.xml
(see Declaring a Service). Instead, annotate service class with @Service
. The service instance will be created in scope according to the caller (see Retrieving a Service).
Restrictions:
Service class must be
final
.Constructor injection is not supported (since it is deprecated).
If service is a PersistentStateComponent, roaming must be disabled (
roamingType = RoamingType.DISABLED
).
See Project Level Service below for a sample.
Declaring a Service
To register a non-Light Service, distinct extension points are provided for each type:
com.intellij.applicationService
- application level servicecom.intellij.projectService
- project level servicecom.intellij.moduleService
- module level service (not recommended, see Note above)
To expose service API, create separate class for serviceInterface
and extend it in corresponding class registered in serviceImplementation
. If serviceInterface
isn't specified, it's supposed to have the same value as serviceImplementation
.
To provide custom implementation for test/headless environment, specify testServiceImplementation
/ headlessImplementation
additionally.
plugin.xml
Retrieving a Service
Getting service doesn't need a read action and can be performed from any thread. If service is requested from several threads, it will be initialized in the first thread, and other threads will be blocked until service is fully initialized.
To retrieve a service in Java code:
In Kotlin code, use convenience methods:
Project Service Sample
This minimal sample shows Light Service ProjectService
interacting with another project level service AnotherService
(not shown here).
ProjectService.java
Sample Plugin
This sample plugin illustrates how to create and use a plugin service. This plugin has an application service counting the number of currently opened projects in the IDE. If this number exceeds the maximum number of simultaneously opened projects allowed by the plugin, it displays a warning message.
To install and run the sample plugin
Download the included sample plugin project located here.
Start IntelliJ IDEA, on the starting page, click Open Project, and then use the Open Project dialog box to open the project.
On the main menu, choose Run | Run or press Shift + F10.
If necessary, change the Run/Debug Configurations.