Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: qualify some classnames and formatting

...

Using PersistentStateComponent

The com.intellij.openapi.components.PersistentStateComponent interface gives you the most flexibility for defining the values to be persisted, their format and storage location. In order to use it, you should mark a service or a component as implementing the PersistentStateComponent interface, define the state class, and specify the storage location using the @State @com.intellij.openapi.components.State annotation.

Note that instances of extensions cannot persist their state by implementing PersistentStateComponent. If your extension needs to have persistent state, you need to define a separate service responsible for managing that state.

...

In the latter case, you can use the following pattern to implement getState() and loadState() methods:

Code Block
class MyService implements PersistentStateComponent<MyService> {
  public String stateValue;

  public MyService getState() {
    return this;
  }

  public void loadState(MyService state) {
    XmlSerializerUtil.copyBean(state, this);
  }
}

...

In order to exclude a public field or bean property from serialization, you can annotate the field or getter with the @Transient @com.intellij.util.xmlb.annotations.Transient annotation.

Note that the state class must have a default constructor. It should return the default state of the component (one used if there is nothing persisted in the XML files yet).

Anchor
Storage
Storage

...

In order to specify where exactly the persisted values wiil be stored, you need to add a @State annotation to the PersistentStateComponent class. It has the following fields:

  • Name name (required) - specifies the name of the state (name of the root tag in XML)
  • One or more of @Storage @com.intellij.openapi.components.Storage annotations (required) - specify the storage locations for .ipr and directory-based projects
  • Roaming type (roamingType (com.intellij.openapi.components.RoamingType, optional) - specifies whether the state is synchronized between different IDEA installations when the IDEA Server plugin is used
  • Reloadable reloadable (optional) - if set to false, complete project reload is required when the XML file is changed externally and the state has changed.

...

Older IDEA components use the JDOMExternalizable interface for persisting state. It uses the readExternal() method for reading the state from a JDOM element, and writeExternal() to write the state to it. JDOMExternalizable implementations can store the state in attributes and sub-elements manually, and/or use the DefaultJDOMExternalizer class to store the values of all public fields automatically.

...