From f06749c1948f849aff6bf812357aa88234c59275 Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Mon, 18 Dec 2023 10:40:41 +0100 Subject: [PATCH] Inline PlantUML diagrams (#1180) --- buildUML/README.md | 49 ----- buildUML/basics/getting-service.puml | 53 ----- buildUML/messaging/bus.puml | 15 -- buildUML/messaging/connection.puml | 17 -- buildUML/messaging/nested_config.puml | 21 -- .../messaging/parent_child_broadcast.puml | 28 --- buildUML/messaging/publish.puml | 10 - buildUML/messaging/standard_hierarchy.puml | 14 -- buildUML/messaging/subscribe.puml | 13 -- buildUML/messaging/topic.puml | 20 -- buildUML/reference_guide/data_node.puml | 25 --- .../reference_guide/data_node_example.puml | 17 -- .../reference_guide/execution_classes.puml | 35 ---- .../run_configuration_classes.puml | 18 -- .../plugin_structure/img/getting_service.svg | 150 ------------- images/reference_guide/img/data_node.svg | 106 ---------- .../reference_guide/img/data_node_example.svg | 94 --------- .../reference_guide/img/execution_classes.svg | 2 - .../img/run_configuration_classes.svg | 2 - images/reference_guide/messaging/img/bus.svg | 86 -------- .../messaging/img/connection.svg | 83 -------- .../messaging/img/nested_config.svg | 93 -------- .../messaging/img/parent_child_broadcast.svg | 111 ---------- .../reference_guide/messaging/img/publish.svg | 74 ------- .../messaging/img/standard_hierarchy.svg | 81 ------- .../messaging/img/subscribe.svg | 79 ------- .../reference_guide/messaging/img/topic.svg | 1 - project.ihp | 1 + topics/basics/execution/execution.md | 40 +++- topics/basics/execution/run_configurations.md | 25 ++- .../plugin_structure/plugin_services.md | 82 +++++++- .../external_system_integration.md | 57 ++++- .../messaging_infrastructure.md | 198 +++++++++++++++++- 33 files changed, 386 insertions(+), 1314 deletions(-) delete mode 100644 buildUML/README.md delete mode 100644 buildUML/basics/getting-service.puml delete mode 100644 buildUML/messaging/bus.puml delete mode 100644 buildUML/messaging/connection.puml delete mode 100644 buildUML/messaging/nested_config.puml delete mode 100644 buildUML/messaging/parent_child_broadcast.puml delete mode 100644 buildUML/messaging/publish.puml delete mode 100644 buildUML/messaging/standard_hierarchy.puml delete mode 100644 buildUML/messaging/subscribe.puml delete mode 100644 buildUML/messaging/topic.puml delete mode 100644 buildUML/reference_guide/data_node.puml delete mode 100644 buildUML/reference_guide/data_node_example.puml delete mode 100644 buildUML/reference_guide/execution_classes.puml delete mode 100644 buildUML/reference_guide/run_configuration_classes.puml delete mode 100644 images/basics/plugin_structure/img/getting_service.svg delete mode 100644 images/reference_guide/img/data_node.svg delete mode 100644 images/reference_guide/img/data_node_example.svg delete mode 100644 images/reference_guide/img/execution_classes.svg delete mode 100644 images/reference_guide/img/run_configuration_classes.svg delete mode 100644 images/reference_guide/messaging/img/bus.svg delete mode 100644 images/reference_guide/messaging/img/connection.svg delete mode 100644 images/reference_guide/messaging/img/nested_config.svg delete mode 100644 images/reference_guide/messaging/img/parent_child_broadcast.svg delete mode 100644 images/reference_guide/messaging/img/publish.svg delete mode 100644 images/reference_guide/messaging/img/standard_hierarchy.svg delete mode 100644 images/reference_guide/messaging/img/subscribe.svg delete mode 100644 images/reference_guide/messaging/img/topic.svg diff --git a/buildUML/README.md b/buildUML/README.md deleted file mode 100644 index 8f3f6ae02..000000000 --- a/buildUML/README.md +++ /dev/null @@ -1,49 +0,0 @@ -## Working with PlantUML - -If you are unfamiliar with PlantUML, review the [quick start](https://plantuml.com/starting) instructions. - -### Editing - -#### Online - -Use [https://kroki.io/](https://kroki.io/). - -#### IDE - -* Install [Graphviz](https://plantuml.com/graphviz-dot) on your machine. -* Get and install the [PlantUML Integration plugin](https://plugins.jetbrains.com/plugin/7017-plantuml-integration) for IntelliJ IDEA: - * Set the `GRAPHVIZ_DOT` system or environment property to point to the directory containing the Graphviz executable on your machine. - For example, `export GRAPHVIZ_DOT="/usr/local/Cellar/graphviz/2.42.3/bin/dot"` - * In the PlantUML plugin Settings (**Settings \| Other Settings \| PlantUML**) set: - * The "Additional 'plantuml.include.path'" to be the absolute path to the directory containing the `jb-plantuml-theme.puml` file on your machine. - For example, `//buildUML` or, if you have the IntelliJ-Community source code, `//platform/docs/`. - * The "PlantUML config" to `!include jb-plantuml-theme.puml` - -### Generating SVG - -> Temporary workflow until embedding inside Markdown sources is available. - -#### IDE - -When a `*.puml` file is open in the IDE editor, the PlantUML Integration plugin will show a preview. -To save a diagram in SVG format, change the file extension from the default PNG to SVG when saving the diagram from the preview window. - -#### Online - -Use [https://kroki.io/](https://kroki.io/) to generate SVG files by pasting: - -``` -@startuml - -[contents of jb-plantuml-theme.puml] - -[contents of your_diagram.puml (without `@startuml`)] - -@enduml -``` - -and then c/p generated SVG output. - -### Post Process - -In SVG file ``, insert `` tag. diff --git a/buildUML/basics/getting-service.puml b/buildUML/basics/getting-service.puml deleted file mode 100644 index 036a4b2e5..000000000 --- a/buildUML/basics/getting-service.puml +++ /dev/null @@ -1,53 +0,0 @@ -@startuml -:getService; -note right - In any thread. - Get on demand only. - Do not cache result. - Do not request in constructor unless needed. -end note - -if (Is Light Service) then (yes) -else (no) - if (Is Service Declaration Found) then (yes) - else (no) - :Return ""null""; - detach - endif -endif - -if (Is Created and Initialized?) then (yes) -else (no) - if (Is Container Active?) then (active) - partition "synchronized on service class" { - if (Is Created and Initialized?) then (yes) - else (no) - if (Is Initializing?) then (yes) - :Throw ""PluginException"" - Cyclic Service Initialization; - detach - else (no) - partition "non cancelable" { - :Create Instance] - note right - Avoid getting other services to reduce initialization tree. - As less dependencies, as more faster and reliable. - end note - - :Register to be Disposed on Container Dispose - if Implements ""Disposable""] - :Load Persistent State - if Implements ""PersistentStateComponent""] - } - endif - endif - } - else (disposed or dispose in progress) - :Throw ""ProcessCanceledException""; - detach - endif -endif - -:Return Instance; - -@enduml \ No newline at end of file diff --git a/buildUML/messaging/bus.puml b/buildUML/messaging/bus.puml deleted file mode 100644 index 6ff5cb66b..000000000 --- a/buildUML/messaging/bus.puml +++ /dev/null @@ -1,15 +0,0 @@ -@startuml -hide empty members -hide circle -top to bottom direction - -:Subscriber: -(Create connection) as (C) -note top of (C): Necessary for subscribing -Subscriber --> C - -:Publisher: -(Publish) -Publisher --> Publish - -@enduml diff --git a/buildUML/messaging/connection.puml b/buildUML/messaging/connection.puml deleted file mode 100644 index 3f795e7f5..000000000 --- a/buildUML/messaging/connection.puml +++ /dev/null @@ -1,17 +0,0 @@ -@startuml -hide empty members -hide circle -top to bottom direction - - -' Define the objects in the diagram -class MessageBus -class MessageBusConnection -class "Default Handler" as DH -class "(Topic-Handler)" as TH - -' Define the class relationships -MessageBus "1" o-- "*" MessageBusConnection -MessageBusConnection o-- "0..1" DH -MessageBusConnection *-- "*" TH -@enduml diff --git a/buildUML/messaging/nested_config.puml b/buildUML/messaging/nested_config.puml deleted file mode 100644 index b9a14397a..000000000 --- a/buildUML/messaging/nested_config.puml +++ /dev/null @@ -1,21 +0,0 @@ -@startuml -hide empty members -hide circle -top to bottom direction - -' Define the objects in the diagram -class "bus" as B - -class "connection1" as C1 -class "connection2" as C2 - -class "topic-handler1" as TH1 -class "topic-handler2" as TH2 - -' Define the class relationships -B *-- C1 -B *-- C2 - -C1 *-- TH1 -C2 *-- TH2 -@enduml diff --git a/buildUML/messaging/parent_child_broadcast.puml b/buildUML/messaging/parent_child_broadcast.puml deleted file mode 100644 index 7056d59e9..000000000 --- a/buildUML/messaging/parent_child_broadcast.puml +++ /dev/null @@ -1,28 +0,0 @@ -@startuml -hide empty members -hide circle -top to bottom direction - -' Define the objects in the diagram -class "application bus" as AB -class "project bus" as PB -class "connection1" as C1 - -class "connection2" as C2 -class "connection3" as C3 -class "topic1-handler1" as T1H1 - -class "topic1-handler2" as T1H2 -class "topic1-handler3" as T1H3 - -' Define the class relationships -AB o-- PB -AB *-- C1 - -PB *-- C2 -PB *-- C3 -C1 *-- T1H1 - -C2 *-- T1H2 -C3 *-- T1H3 -@enduml diff --git a/buildUML/messaging/publish.puml b/buildUML/messaging/publish.puml deleted file mode 100644 index d88de2fa7..000000000 --- a/buildUML/messaging/publish.puml +++ /dev/null @@ -1,10 +0,0 @@ -@startuml -left to right direction - -' Define the activity -(*) --> "Get message\nbus reference" - --> "Ask the bus\nfor a particular\ntopic's publisher" - --> "Call target\nmethod on\npublisher" - --> "Messaging\ncalls the\nsame method\non target\nhandlers" ---> (*) -@enduml diff --git a/buildUML/messaging/standard_hierarchy.puml b/buildUML/messaging/standard_hierarchy.puml deleted file mode 100644 index 66162baef..000000000 --- a/buildUML/messaging/standard_hierarchy.puml +++ /dev/null @@ -1,14 +0,0 @@ -@startuml -hide empty members -hide circle -left to right direction - -' Define the objects in the diagram -class "application bus" as AB -class "project bus" as PB -class "module bus" as MB - -' Define the class relationships -AB o-- "*" PB -PB o-- "*" MB -@enduml diff --git a/buildUML/messaging/subscribe.puml b/buildUML/messaging/subscribe.puml deleted file mode 100644 index 1802beb44..000000000 --- a/buildUML/messaging/subscribe.puml +++ /dev/null @@ -1,13 +0,0 @@ -@startuml -left to right direction - -' Define the activity -(*) --> if "" then - --> [don't have connection] "Get message\nbus reference" - --> "Create connection\nto the bus" - --> "Subscribe" -else - --> [have connection] "Subscribe" -endif ---> (*) -@enduml diff --git a/buildUML/messaging/topic.puml b/buildUML/messaging/topic.puml deleted file mode 100644 index 94d2f0ae0..000000000 --- a/buildUML/messaging/topic.puml +++ /dev/null @@ -1,20 +0,0 @@ -@startuml -skinparam classAttributeIconSize 0 -hide empty fields -hide empty methods -left to right direction - -' Define the objects in the diagram -class "com.intellij.util.messages.Topic" as Topic { - +getDisplayName() - +getBroadcastDirection() -} -class ListenerClass { - +method1() - {method} ... - +methodN() -} - -' Define the class relationships -Topic o--> "1 " ListenerClass -@enduml diff --git a/buildUML/reference_guide/data_node.puml b/buildUML/reference_guide/data_node.puml deleted file mode 100644 index 51d6bb9db..000000000 --- a/buildUML/reference_guide/data_node.puml +++ /dev/null @@ -1,25 +0,0 @@ -@startuml - -hide empty members -hide circle - -class "parent DataNode" as parent -class DataNode -together { - class "child n DataNode" as child3 - class "..." as child2 - class "child 1 DataNode" as child1 - class Key - class ExternalEntityData -} - -' Define the class relationships -parent -- DataNode - -ExternalEntityData --o DataNode -Key --o DataNode -DataNode -- child1 -DataNode -- child2 -DataNode -- child3 - -@enduml diff --git a/buildUML/reference_guide/data_node_example.puml b/buildUML/reference_guide/data_node_example.puml deleted file mode 100644 index 7ec390302..000000000 --- a/buildUML/reference_guide/data_node_example.puml +++ /dev/null @@ -1,17 +0,0 @@ -@startuml - -rectangle "DataNode" as root -rectangle "DataNode" as child1 -rectangle "DataNode\n(JUnit)" as child2 -rectangle "DataNode" as child11 -rectangle "DataNode\n(JUnit)" as child12 - - -' Define the class relationships -root -- child1 -root -- child2 - -child1 -- child11 -child1 -- child12 - -@enduml diff --git a/buildUML/reference_guide/execution_classes.puml b/buildUML/reference_guide/execution_classes.puml deleted file mode 100644 index ab5d67be6..000000000 --- a/buildUML/reference_guide/execution_classes.puml +++ /dev/null @@ -1,35 +0,0 @@ -@startuml - -hide empty members -hide circle - -package Configuration <> { - interface RunProfile - interface RunConfiguration - interface RunProfileState -} - -package Execution <> { - abstract class Executor - interface ProgramRunner - class ExecutionEnvironment - class RunContentBuilder - abstract class ExecutionResult - interface ExecutionConsole - abstract class ProcessHandler -} - -RunProfile <|.. RunConfiguration -RunProfile --> RunProfileState: creates - -RunProfileState --> ExecutionResult: prepares - -ExecutionResult o-- "1" ExecutionConsole -ExecutionResult o-- "1" ProcessHandler - -ProgramRunner --> RunProfile: executes -ProgramRunner --> Executor -ProgramRunner --> ExecutionEnvironment -ProgramRunner -r-> RunContentBuilder - -@enduml diff --git a/buildUML/reference_guide/run_configuration_classes.puml b/buildUML/reference_guide/run_configuration_classes.puml deleted file mode 100644 index 25d1a48e9..000000000 --- a/buildUML/reference_guide/run_configuration_classes.puml +++ /dev/null @@ -1,18 +0,0 @@ -@startuml - -hide empty members -hide circle - -interface RunProfile -interface ConfigurationType -abstract class ConfigurationFactory -interface RunConfiguration -abstract class SettingsEditor - - -ConfigurationType *-- "*" ConfigurationFactory -ConfigurationFactory --> RunConfiguration: creates -RunConfiguration o-- "0..*" SettingsEditor -RunConfiguration -l|> RunProfile - -@enduml diff --git a/images/basics/plugin_structure/img/getting_service.svg b/images/basics/plugin_structure/img/getting_service.svg deleted file mode 100644 index cb2ffb8cc..000000000 --- a/images/basics/plugin_structure/img/getting_service.svg +++ /dev/null @@ -1,150 +0,0 @@ - - -In any thread.Get on demand only.Do not cache result.Do not request in constructor unless needed.getServiceReturnnullnoIs Service Declaration FoundyesnoIs Light ServiceyesIs Container Active?activedisposed or dispose in progresssynchronized on service classIs Initializing?yesnoThrowPluginExceptionCyclic Service Initializationnon cancelableAvoid getting other services to reduce initialization tree.As less dependencies, as more faster and reliable.Create InstanceRegister to be Disposed on Container Disposeif ImplementsDisposableLoad Persistent Stateif ImplementsPersistentStateComponentnoIs Created and Initialized?yesThrowProcessCanceledExceptionnoIs Created and Initialized?yesReturn Instance \ No newline at end of file diff --git a/images/reference_guide/img/data_node.svg b/images/reference_guide/img/data_node.svg deleted file mode 100644 index a008ed6b1..000000000 --- a/images/reference_guide/img/data_node.svg +++ /dev/null @@ -1,106 +0,0 @@ - - - - - child n DataNode...child 1 DataNodeKeyExternalEntityDataparent DataNodeDataNode diff --git a/images/reference_guide/img/data_node_example.svg b/images/reference_guide/img/data_node_example.svg deleted file mode 100644 index f5adca75a..000000000 --- a/images/reference_guide/img/data_node_example.svg +++ /dev/null @@ -1,94 +0,0 @@ -DataNode<ProjectData>DataNode<ModuleData>DataNode<LibraryData>(JUnit)DataNode<ContentRootData>DataNode<LibraryDependencyData>(JUnit) \ No newline at end of file diff --git a/images/reference_guide/img/execution_classes.svg b/images/reference_guide/img/execution_classes.svg deleted file mode 100644 index 4f9610f65..000000000 --- a/images/reference_guide/img/execution_classes.svg +++ /dev/null @@ -1,2 +0,0 @@ - -ConfigurationExecutionRunProfileRunConfigurationRunProfileStateExecutorProgramRunnerExecutionEnvironmentRunContentBuilderExecutionResultExecutionConsoleProcessHandlercreatesprepares11executes diff --git a/images/reference_guide/img/run_configuration_classes.svg b/images/reference_guide/img/run_configuration_classes.svg deleted file mode 100644 index b3970d2b3..000000000 --- a/images/reference_guide/img/run_configuration_classes.svg +++ /dev/null @@ -1,2 +0,0 @@ - -RunProfileConfigurationTypeConfigurationFactoryRunConfigurationSettingsEditor*creates0..* diff --git a/images/reference_guide/messaging/img/bus.svg b/images/reference_guide/messaging/img/bus.svg deleted file mode 100644 index f08353afc..000000000 --- a/images/reference_guide/messaging/img/bus.svg +++ /dev/null @@ -1,86 +0,0 @@ - - -SubscriberCreate connectionNecessary for subscribingPublisherPublish \ No newline at end of file diff --git a/images/reference_guide/messaging/img/connection.svg b/images/reference_guide/messaging/img/connection.svg deleted file mode 100644 index 4fd587c18..000000000 --- a/images/reference_guide/messaging/img/connection.svg +++ /dev/null @@ -1,83 +0,0 @@ - - -MessageBusMessageBusConnectionDefault Handler(Topic-Handler)1*0..1* \ No newline at end of file diff --git a/images/reference_guide/messaging/img/nested_config.svg b/images/reference_guide/messaging/img/nested_config.svg deleted file mode 100644 index 615a47171..000000000 --- a/images/reference_guide/messaging/img/nested_config.svg +++ /dev/null @@ -1,93 +0,0 @@ - - -busconnection1connection2topic-handler1topic-handler2 \ No newline at end of file diff --git a/images/reference_guide/messaging/img/parent_child_broadcast.svg b/images/reference_guide/messaging/img/parent_child_broadcast.svg deleted file mode 100644 index 0daf37508..000000000 --- a/images/reference_guide/messaging/img/parent_child_broadcast.svg +++ /dev/null @@ -1,111 +0,0 @@ - - -application busproject busconnection1connection2connection3topic1-handler1topic1-handler2topic1-handler3 \ No newline at end of file diff --git a/images/reference_guide/messaging/img/publish.svg b/images/reference_guide/messaging/img/publish.svg deleted file mode 100644 index fcdbb28da..000000000 --- a/images/reference_guide/messaging/img/publish.svg +++ /dev/null @@ -1,74 +0,0 @@ - - -Get messagebus referenceAsk the busfor a particulartopic's publisherCall targetmethod onpublisherMessagingcalls thesame methodon targethandlers \ No newline at end of file diff --git a/images/reference_guide/messaging/img/standard_hierarchy.svg b/images/reference_guide/messaging/img/standard_hierarchy.svg deleted file mode 100644 index 5ce6221bc..000000000 --- a/images/reference_guide/messaging/img/standard_hierarchy.svg +++ /dev/null @@ -1,81 +0,0 @@ - - -application busproject busmodule bus** \ No newline at end of file diff --git a/images/reference_guide/messaging/img/subscribe.svg b/images/reference_guide/messaging/img/subscribe.svg deleted file mode 100644 index 71f33b35d..000000000 --- a/images/reference_guide/messaging/img/subscribe.svg +++ /dev/null @@ -1,79 +0,0 @@ - - -Get messagebus referenceCreate connectionto the busSubscribedon't have connectionhave connection \ No newline at end of file diff --git a/images/reference_guide/messaging/img/topic.svg b/images/reference_guide/messaging/img/topic.svg deleted file mode 100644 index e3dd38417..000000000 --- a/images/reference_guide/messaging/img/topic.svg +++ /dev/null @@ -1 +0,0 @@ -com.intellij.util.messages.Topic+getDisplayName()+getBroadcastDirection()ListenerClass+method1()...+methodN()1 \ No newline at end of file diff --git a/project.ihp b/project.ihp index 39631ee88..c1553b345 100644 --- a/project.ihp +++ b/project.ihp @@ -5,6 +5,7 @@ LOWER_CASE_DASHES_DOT_REMOVE + diff --git a/topics/basics/execution/execution.md b/topics/basics/execution/execution.md index 690ca85bb..b95655f96 100644 --- a/topics/basics/execution/execution.md +++ b/topics/basics/execution/execution.md @@ -17,7 +17,45 @@ The key Execution API classes are divided into two groups: The following diagram shows the relations between the key classes: -![Execution Classes](execution_classes.svg) +```plantuml +@startuml + +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +hide empty members +hide circle + +package Configuration <> { +interface RunProfile +interface RunConfiguration +interface RunProfileState +} + +package Execution <> { +abstract class Executor +interface ProgramRunner +class ExecutionEnvironment +class RunContentBuilder +abstract class ExecutionResult +interface ExecutionConsole +abstract class ProcessHandler +} + +RunProfile <|.. RunConfiguration +RunProfile --> RunProfileState: creates + +RunProfileState --> ExecutionResult: prepares + +ExecutionResult o-- "1" ExecutionConsole +ExecutionResult o-- "1" ProcessHandler + +ProgramRunner --> RunProfile: executes +ProgramRunner --> Executor +ProgramRunner --> ExecutionEnvironment +ProgramRunner -r-> RunContentBuilder + +@enduml +``` ### Configuration Classes diff --git a/topics/basics/execution/run_configurations.md b/topics/basics/execution/run_configurations.md index 666909034..60f6ea5e1 100644 --- a/topics/basics/execution/run_configurations.md +++ b/topics/basics/execution/run_configurations.md @@ -19,7 +19,30 @@ Run configurations can be started from the Run toolbar, the e The following diagram shows the key run configurations classes: -![Run Configuration Classes](run_configuration_classes.svg) +Original: + +```plantuml +@startuml + +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +hide empty members +hide circle + +interface RunProfile +interface ConfigurationType +abstract class ConfigurationFactory +interface RunConfiguration +abstract class SettingsEditor + + +ConfigurationType *-- "*" ConfigurationFactory +ConfigurationFactory --> RunConfiguration: creates +RunConfiguration o-- "0..*" SettingsEditor +RunConfiguration -l|> RunProfile + +@enduml +``` Run Configuration API (except `SettingsEditor` class, which is a class shared by many IntelliJ Platform APIs) is a part of the [Execution API](execution.md). diff --git a/topics/basics/plugin_structure/plugin_services.md b/topics/basics/plugin_structure/plugin_services.md index a99720cb4..c66d6f5dd 100644 --- a/topics/basics/plugin_structure/plugin_services.md +++ b/topics/basics/plugin_structure/plugin_services.md @@ -308,11 +308,87 @@ val projectService = project.service() - + -![Getting Service](getting_service.svg){thumbnail="true" thumbnail-same-file="true"} +```plantuml +@startuml +skinparam monochrome true +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 13 +skinparam DefaultTextAlignment center +skinparam NoteTextAlignment left - +' default 1.5 +skinparam ActivityBorderThickness 1 +' default 2 +skinparam PartitionBorderThickness 1.5 + +:getService; +note right + Allowed in any thread. + Call on demand only. + Never cache the result. + Do not call in constructors + unless needed. +end note + +if (Is Light Service) then (yes) +else (no) + if (Is Service Declaration Found) then (yes) + else (no) + :Return null; + detach + endif +endif + +if (Is Created and Initialized?) then (yes) +else (no) + if (Is Container Active?) then (yes) + partition "synchronized\non service class" { + if (Is Created and Initialized?) then (yes) + else (no) + if (Is Initializing?) then (yes) + :Throw + PluginException + (Cyclic Service + Initialization); + detach + else (no) + partition "non-cancelable" { + :Create Instance] + note right + Avoid getting other + services to reduce + the initialization tree. + The fewer the + dependencies, + the faster and more + reliable initialization. + end note + + :Register to be Disposed + on Container Dispose + (Disposable only)] + :Load Persistent State + (PersistentStateComponent + only)] + } + endif + endif + } + else (disposed or dispose in progress) + :Throw + ProcessCanceledException; + detach + endif +endif + +:Return Instance; + +@enduml +``` + + ## Sample Plugin diff --git a/topics/reference_guide/frameworks_and_external_apis/external_system_integration.md b/topics/reference_guide/frameworks_and_external_apis/external_system_integration.md index f4d595af7..1902ad29f 100644 --- a/topics/reference_guide/frameworks_and_external_apis/external_system_integration.md +++ b/topics/reference_guide/frameworks_and_external_apis/external_system_integration.md @@ -18,6 +18,8 @@ The *External System* sub-system provides a simple API for wrapping external sys ## Project Management +Fonts installed on the build server: + ### Project Data Domain The external system wrapper is required to be able to build project info on the basis of the given external system config. @@ -26,14 +28,65 @@ That information is built with the following base classes: * [`Key`](%gh-ic%/platform/external-system-api/src/com/intellij/openapi/externalSystem/model/Key.java) * [`ExternalEntityData`](%gh-ic%/platform/external-system-api/src/com/intellij/openapi/externalSystem/model/project/ExternalEntityData.java) -![DataNode](data_node.svg) +```plantuml +@startuml + +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +hide empty members +hide circle + +class "parent DataNode" as parent +class DataNode +together { + class "child n DataNode" as child3 + class "..." as child2 + class "child 1 DataNode" as child1 + class Key + class ExternalEntityData +} + +' Define the class relationships +parent -- DataNode + +ExternalEntityData --o DataNode +Key --o DataNode +DataNode -- child1 +DataNode -- child2 +DataNode -- child3 + +@enduml +``` 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 directed graph where every edge identifies parent-child relation. For example, a simple one-module project might look as below: -![DataNode Example](data_node_example.svg) +```plantuml +@startuml + +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +skinparam DefaultTextAlignment center +hide empty members +hide circle + +rectangle "DataNode" as root +rectangle "DataNode" as child1 +rectangle "DataNode\n(JUnit)" as child2 +rectangle "DataNode" as child11 +rectangle "DataNode\n(JUnit)" as child12 + +' Define the class relationships +root -- child1 +root -- child2 + +child1 -- child11 +child1 -- child12 + +@enduml +``` 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`. diff --git a/topics/reference_guide/messaging_infrastructure.md b/topics/reference_guide/messaging_infrastructure.md index c6596c3d1..85ef92315 100644 --- a/topics/reference_guide/messaging_infrastructure.md +++ b/topics/reference_guide/messaging_infrastructure.md @@ -1,7 +1,7 @@ -# Messaging Infrastructure - +# Messaging Infrastructure + Subscribing and publishing messages via message bus. IntelliJ Platform's messaging infrastructure is an implementation of [Publisher Subscriber Pattern](https://w.wiki/5xaV) that provides additional features like _broadcasting on hierarchy_ and special _nested events_ processing (a _nested event_ is an event directly or indirectly fired from the callback of another event). @@ -21,7 +21,33 @@ The [`Topic`](%gh-ic%/platform/extensions/src/com/intellij/util/messages/Topic.j Clients are allowed to subscribe to a specific topic within a bus and send messages to that topic within that particular bus. To clarify the corresponding message bus, a `Topic` field declaration should be annotated with `Topic.@AppLevel` and/or `Topic.@ProjectLevel`. -![Topic](topic.svg) +```plantuml +@startuml + +skinparam monochrome true +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +skinparam classAttributeIconSize 0 +hide empty fields +hide empty methods + +left to right direction + +class "com.intellij.util.messages.Topic" as Topic { + +getDisplayName() + +getBroadcastDirection() +} + +class ListenerClass { + +method1() + {method} ... + +methodN() +} + +Topic o--> "1 " ListenerClass + +@enduml +``` #### Topic Properties @@ -42,13 +68,49 @@ Listener class [`MessageBus`](%gh-ic%/platform/extensions/src/com/intellij/util/messages/MessageBus.kt) is the core of the messaging system. It is used in the following scenarios: -![Bus](bus.svg) +```plantuml +@startuml + +skinparam monochrome true +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 + +:Subscriber: +(Create connection) as (C) +note top of (C): Necessary for subscribing +Subscriber --> C + +:Publisher: +(Publish) +Publisher --> Publish + +@enduml +``` ### Connection Connection is represented by [`MessageBusConnection`](%gh-ic%/platform/extensions/src/com/intellij/util/messages/MessageBusConnection.kt) class and manages all subscriptions for a particular client within a particular bus. -![Connection](connection.svg) +```plantuml +@startuml + +skinparam monochrome true +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +hide empty members +hide circle + +class MessageBus +class MessageBusConnection +class "Default Handler" as DH +class "(Topic-Handler)" as TH + +MessageBus "1" o-- "*" MessageBusConnection +MessageBusConnection o-- "0..1" DH +MessageBusConnection *-- "*" TH + +@enduml +``` Connection stores *topic-handler* mappings - callbacks to invoke when message for the target topic is received (not more than one handler per topic within the same connection is allowed). @@ -80,7 +142,28 @@ public interface ChangeActionNotifier { ### Subscribing to a Topic -![Subscribing](subscribe.svg) +```plantuml +@startuml + +skinparam monochrome true +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +skinparam DefaultTextAlignment center +skinparam ActivityBorderThickness 1 + +left to right direction + +' Define the activity +(*) --> if "" then + --> [no connection] "Get a message\nbus reference" + --> "Create\na connection\nto the bus" + --> "Subscribe" +else + --> [connection exists] "Subscribe" +endif +--> (*) +@enduml +``` > If targeting 2019.3 or later, use [declarative registration](plugin_listeners.md) whenever possible. > @@ -106,7 +189,25 @@ Many standard interfaces implement returning a message bus, e.g., [`Application. ### Publishing Messages -![Publishing](publish.svg) +```plantuml +@startuml + +skinparam monochrome true +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +skinparam DefaultTextAlignment center +skinparam ActivityBorderThickness 1 + +left to right direction + +' Define the activity +(*) --> "Get message\nbus reference" + --> "Ask the bus\nfor a particular\ntopic's publisher" + --> "Call target\nmethod on\npublisher" + --> "Messaging calls\nthe same method\non target handlers" +--> (*) +@enduml +``` ```java public void doChange(Context context) { @@ -126,13 +227,65 @@ public void doChange(Context context) { Message buses can be organised into hierarchies. Moreover, the IntelliJ Platform has them already: -![Standard hierarchy](standard_hierarchy.svg) +```plantuml +@startuml + +skinparam monochrome true +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +hide empty members +hide circle + +left to right direction + +' Define the objects in the diagram +class "application bus" as AB +class "project bus" as PB +class "module bus" as MB + +' Define the class relationships +AB o-- "*" PB +PB o-- "*" MB +@enduml +``` That allows to notify subscribers registered in one message bus on messages sent to another message bus. Example setup: -![Parent-child broadcast](parent_child_broadcast.svg) +```plantuml +@startuml + +skinparam monochrome true +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +hide empty members +hide circle +top to bottom direction + +class "application bus" as AB +class "project bus" as PB +class "connection1" as C1 + +class "connection2" as C2 +class "connection3" as C3 +class "topic1-handler1" as T1H1 + +class "topic1-handler2" as T1H2 +class "topic1-handler3" as T1H3 + +AB o-- PB +AB *-- C1 + +PB *-- C2 +PB *-- C3 +C1 *-- T1H1 + +C2 *-- T1H2 +C3 *-- T1H3 + +@enduml +``` The example setup presents a simple hierarchy (the *application bus* is a parent of the *project bus*) with three subscribers for the same topic. @@ -163,7 +316,32 @@ The IntelliJ Platform's messaging infrastructure guarantees that all messages se Consider the following configuration: -![Nested messages](nested_config.svg) +```plantuml +@startuml + +skinparam DefaultFontName JetBrains Sans +skinparam DefaultFontSize 14 +hide empty members +hide circle + +top to bottom direction + +class "bus" as B + +class "connection1" as C1 +class "connection2" as C2 + +class "topic-handler1" as TH1 +class "topic-handler2" as TH2 + + +B *-- C1 +B *-- C2 + +C1 *-- TH1 +C2 *-- TH2 +@enduml +``` When a message is sent to the target topic, the following happens: