intellij-sdk-code-samples/basics/plugin_structure/plugin_components.md

layout	title
editable	Plugin Components

Components are the fundamental concept of plugins integration. There are three kinds of components:

• Application-level

• Project-level

• Module-level

Application-level components are created and initialized on IDEA start-up. They can be acquired from the Application instance with the getComponent(Class) method.

Project-level components are created for each Project instance in IDEA (please note that components might be created for even unopened projects). They can be acquired from the Project instance with the getComponent(Class) method.

Module-level components are created for each Module in every project loaded in IDEA. Module-level component can be acquired from Module instance with the same method.

Every component should have interface and implementation classes specified in the configuration file. The interface class will be used for retrieving the component from other components and the implementation class will be used for component instantiation. Note that two components of the same level ( Application, Project or Module ) cannot have the same interface class. Interface and implementation classes can be the same.

Each component has the unique name which is used for its externalization and other internal needs. The name of a component is returned by its getComponentName() method.

Components Naming Notation

It's recommended to name components in <plugin_name>.<component_name> form.

Application Level Components

Optionally, application-level component's implementation class may implement the ApplicationComponent interface. An application component that has no dependencies should have a constructor with no parameters which will be used for its instantiation. If an application component depends on other application components, it can specify these components as constructor parameters, and IDEA will ensure that the components are instantiated in correct order to satisfy the dependencies. Note that application-level components must be registered in the <application-components> section of the plugin.xml file (see Plugin Configuration File below).

Quick creation of application components

IntelliJ IDEA suggests a simplified way of creating application components, with all the required infrastructure. The IntelliJ interface will help you declare the application component's implementation class and automatically makes appropriate changes to the <application-components> section of the plugin.xml file.

To create and register an application component:

1. In your project, on the context menu of the destination package click New or press ALT + INSERT.

2. On the New menu, click Application Component.

3. In the New Application Component dialog box that opens, enter the application component name, and then click OK.

IntelliJ IDEA generates a new Java class that implements the ApplicationComponent interface, registers the newly created component in the plugin.xml file, adds a node to the module tree view, and opens the created application component class file in the editor.

Project Level Components

Project-level component's implementation class may implement the

ProjectComponent interface. The constructor of a project-level component can have a parameter of the Project type, if it needs the project instance. It can also specify other application-level or project-level components as parameters, if it depends on those components.

Note that project-level components must be registered in the <project-components> section of the plugin.xml file (see Plugin Configuration File below).

Quick creation of project components

IntelliJ IDEA suggests a simplified way of creating project components, with all the required infrastructure. The IDEA interface will help you declare the project component's implementation class and automatically makes appropriate changes to the <project-components> section of the

plugin.xml file.

To create and register a project component

1. In your project, on the context menu of the destination package click New or press ALT + INSERT.

2. On the New menu, click Project Component.

3. In the New Project Component dialog box that opens, enter the project component name, and then click OK.

IntelliJ IDEA generates a new Java class that implements the ProjectComponent interface, registers the newly created component in the plugin.xml file, adds a node to the module tree view, and opens the created application component class file in the editor.

Module Level Components

Optionally, Module-level component's implementation class may implement the ModuleComponent interface. The constructor of a module-level component can have a parameter of the Module type, if it needs the module instance. It can also specify other application-level, project-level or module-level components as parameters, if it depends on those components.

Note that module-level components must be registered in the <module-components> section of the plugin.xml file (see Plugin Configuration File below).

Quick creation of module components

IntelliJ IDEA suggests a simplified way of creating module components, with all the required infrastructure. The IDEA interface will help you declare the module component's implementation class and automatically makes appropriate changes to the section of the plugin.xml file.

To create and register a module component

• In your project, on the context menu of the destination package click New or press ALT + INSERT.
• On the New menu, click Module Component.
• In the New Module Component dialog box that opens, enter the module component name, and then click OK.

IntelliJ IDEA generates a new Java class that implements the ModuleComponent interface, registers the newly created component in the plugin.xml file, adds a node to the module tree view, and opens the created application component class file in the editor.

Persisting State of Components

The state of every component will be automatically saved and loaded if the component's class implements the JDOMExternalizable (deprecated) or PersistentStateComponent interface.

When the component's class implements the PersistentStateComponent interface, the component state is saved in an XML file that you can specify using the @State and @Storage annotations in your Java code.

When the component's class implements the JDOMExternalizable interface, the components save their state in the following files:

• Project-level components save their state to the project (.ipr) file. However, if the workspace option in the plugin.xml file is set to true, the component saves its configuration to the workspace (.iws) file instead.

• Module-level components save their state to the module (.iml) file.

For more information and samples, refer to Persisting State of Components.

Defaults

Defaults (components' predefined settings) should be placed in the <component_name>.xml file. Put this file in the plugin's classpath in the folder corresponding to the default package. The readExternal() method will be called on the root tag.

If a component has defaults, the readExternal() method is called twice:

• the first time for defaults

• the second time for saved configuration

Plugin Components Lifecycle

The components are loaded in the following order:

• Creation - constructor is invoked.

• Initialization - the initComponent method is invoked (if the component implements the ApplicationComponent interface).

• Configuration - the readExternal method is invoked (if the component implements JDOMExternalizable interface), or the loadState method is invoked (if the component implements PersistentStateComponent and has non-default persisted state).

• For module components, the moduleAdded method of the ModuleComponent interface is invoked to notify that a module has been added to the project.

• For project components, the projectOpened method of the ProjectComponent interface is invoked to notify that a project has been loaded.

The components are unloaded in the following order:

• Saving configuration - the writeExternal method is invoked (if the component implements the JDOMExternalizable interface), or the getState method is invoked (if the component implements PersistentStateComponent).

• Disposal - the disposeComponent method is invoked.

Note that you should not request any other components using the getComponent() method in the constructor of your component, otherwise you'll get an assertion. If you need access to other components when initializing your component, you can specify them as constructor parameters or access them in the initComponent method.