hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-30 18:27:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

persisting_state_of_components: clarify, wording, cleanup #2

Browse Source
This commit is contained in:
Yann Cébron 2019-01-24 21:12:15 +01:00
parent f13e2d7577
commit 975f9c1bee
1 changed files with 17 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
basics/persisting_state_of_components.md
View File

@ -4,11 +4,11 @@ title: Persisting State of Components
The *IntelliJ Platform* provides an API that allows components or services to persist their state between restarts of the IDE. You can use either a simple API to persist a few values, or persist the state of more complicated components using the [PersistentStateComponent](upsource:///platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java) interface.
> **WARNING** If you need to persist sensitive data like passwords. please see [Credentials Store](https://github.com/JetBrains/intellij-community/blob/master/platform/credential-store/readme.md)
> **WARNING** If you need to persist sensitive data like passwords, please see [Credentials Store](https://github.com/JetBrains/intellij-community/blob/master/platform/credential-store/readme.md)
## Using PropertiesComponent for simple non-roamable persistence
If the only thing that your plugin needs to persist is a few simple values, the easiest way to do so is to use the [`com.intellij.ide.util.PropertiesComponent`](upsource:///platform/core-api/src/com/intellij/ide/util/PropertiesComponent.java) service. It can be used for saving both application-level values and project level values (stored in the workspace file). Roaming is disabled for `PropertiesComponent`, so use it only for temporary, non-roamable properties.
If the only thing that your plugin needs to persist is a few simple values, the easiest way to do so is to use the [`com.intellij.ide.util.PropertiesComponent`](upsource:///platform/core-api/src/com/intellij/ide/util/PropertiesComponent.java) service. It can be used for saving both application-level values and project-level values (stored in the workspace file). Roaming is disabled for `PropertiesComponent`, so use it only for temporary, non-roamable properties.
Use the `PropertiesComponent.getInstance()` method for storing application-level values, and the `PropertiesComponent.getInstance(Project)` method for storing project-level values.
@ -16,7 +16,12 @@ Since all plugins share the same namespace, it is highly recommended to prefix k
## Using PersistentStateComponent
The [`com.intellij.openapi.components.PersistentStateComponent`](upsource:///platform/projectModel-api/src/com/intellij/openapi/components/PersistentStateComponent.java) interface gives you the most flexibility for defining the values to be persisted, their format and storage location. 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 `@com.intellij.openapi.components.State` annotation.
The [`com.intellij.openapi.components.PersistentStateComponent`](upsource:///platform/projectModel-api/src/com/intellij/openapi/components/PersistentStateComponent.java) interface gives you the most flexibility for defining the values to be persisted, their format and storage location.
To use it:
- mark a [service](plugin_structure/plugin_services.md) or a [component](plugin_structure/plugin_components.md) as implementing the `PersistentStateComponent` interface
- define the state class
- specify the storage location using `@com.intellij.openapi.components.State`
Note that instances of extensions cannot persist their state by implementing `PersistentStateComponent`. If your extension needs to have a persistent state, you need to define a separate service responsible for managing that state.
@ -27,9 +32,9 @@ The implementation of `PersistentStateComponent` needs to be parameterized with
In the former case, the instance of the state class is typically stored as a field in the `PersistentStateComponent` class:
```java
@State(...)
class MyService implements PersistentStateComponent<MyService.State> {
@State(...)
static class State {
public String value;
}
@ -75,7 +80,7 @@ The following types of values can be persisted:
* maps
* enums
To exclude a public field or bean property from serialization, you can annotate the field or getter with the `@com.intellij.util.xmlb.annotations.Transient` annotation.
To exclude a public field or bean property from serialization, annotate the field or getter with `@com.intellij.util.xmlb.annotations.Transient`.
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).
@ -96,7 +101,9 @@ The simplest ways of specifying the `@Storage` annotation are as follows (since
* `@Storage(StoragePathMacros.WORKSPACE_FILE)` for values stored in the workspace file.
By specifying a different value for the `value` parameter (`file` before 2016.x), you can cause the state to be persisted in a different file. For application-level components it is strongly recommended to use a custom file, using of `other.xml` is deprecated.
By specifying a different value for the `value` parameter (`file` before 2016.x), the state will be persisted in a different file.
>> **NOTE** For application-level components it is strongly recommended to use a custom file, using of `other.xml` is deprecated.
The `roamingType` parameter of the `@Storage` annotation specifies the roaming type when the Settings Repository plugin is used.
@ -120,9 +127,9 @@ The `getState()` method is called every time the settings are saved (for example
Older components use the [`JDOMExternalizable`](upsource:///platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java) 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, or use the [`DefaultJDOMExternalizer`](upsource:///platform/util/src/com/intellij/openapi/util/DefaultJDOMExternalizer.java) class to store the values of all public fields automatically.
Implementations can store the state in attributes and sub-elements manually, or use the [`DefaultJDOMExternalizer`](upsource:///platform/util/src/com/intellij/openapi/util/DefaultJDOMExternalizer.java) class to store the values of all public fields automatically.
When the component's class implements the `JDOMExternalizable` interface, the components save their state in the following files:
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.
* Project-level: project (`.ipr`) file. However, if the workspace option in the `plugin.xml` file is set to `true`, then workspace (`.iws`) file will be used instead.
* Module-level: module (`.iml`) file.