This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/isis.git
commit a8cdd0f6b0792599ef7de62a716b4e97edf0365d Author: Dan Haywood <[email protected]> AuthorDate: Sat Aug 20 23:46:43 2022 +0100 ISIS-2965: updates docs --- README.adoc | 1 - .../ROOT/pages/post-release-successful.adoc | 12 +- .../documentation/pages/asciidoc-syntax.adoc | 6 +- .../components/docs/modules/ROOT/pages/about.adoc | 11 +- .../landing-page/{internal.adoc => framework.adoc} | 0 .../modules/ROOT/pages/landing-page/releases.adoc | 16 +- .../ROOT/partials/module-nav/framework.adoc | 12 +- .../modules/resources/pages/eventbus_domain.adoc | 73 -- .../resources/pages/eventbus_persistence.adoc | 55 - .../docs/modules/resources/pages/eventbus_ui.adoc | 59 - .../docs/modules/resources/pages/metamodel.adoc | 106 -- .../resources/pages/metamodel_terminology.adoc | 74 -- .../docs/modules/resources/partials/C4.puml | 1210 ++++++++++++++++++++ .../modules/resources/partials/C4_Container.puml | 111 ++ .../modules/resources/partials/C4_Context.puml | 292 +++++ .../modules/ROOT/pages/2020/2.0.0-M3/relnotes.adoc | 2 +- antora/playbooks/site-core.yml | 3 - .../{site-core.yml => site-regressiontests.yml} | 40 +- antora/playbooks/site.yml | 9 +- antora/supplemental-ui/index.html | 2 +- .../pages/about.adoc => ROOT/pages/_todo.adoc} | 14 +- core/adoc/modules/ROOT/pages/about.adoc | 72 +- core/adoc/modules/ROOT/partials/component-nav.adoc | 4 +- core/adoc/modules/ROOT/partials/module-nav.adoc | 3 + .../attachments/modules-dependencies.pptx | Bin 48379 -> 0 bytes .../archdesign/images/modules-dependencies.png | Bin 59588 -> 0 bytes core/adoc/modules/archdesign/nav.adoc | 4 - .../modules/archdesign/partials/module-nav.adoc | 3 - .../modules/codegen-bytebuddy/pages/about.adoc | 7 +- .../codegen-bytebuddy/partials/module-nav.adoc | 2 +- .../main/adoc/modules/interaction/pages/about.adoc | 7 +- .../modules/internaltestsupport/pages/about.adoc | 2 +- .../main/adoc/modules/metamodel/pages/about.adoc | 289 ++++- .../modules/metamodel/pages/class-diagram.adoc | 2 - .../main/adoc/modules/metamodel/pages/events.adoc | 197 ++++ .../modules/metamodel/partials/module-nav.adoc | 3 +- .../src/main/adoc/modules/runtime/pages/about.adoc | 5 +- .../adoc/modules/runtimeservices/pages/about.adoc | 9 +- .../main/adoc/modules/transaction/pages/about.adoc | 2 +- .../src/main/adoc/modules/webapp/pages/about.adoc | 6 +- .../main/adoc/modules/webapp/pages/webmodules.adoc | 2 +- incubator/adoc/modules/ROOT/pages/about.adoc | 2 +- regressiontests/adoc/antora.yml | 2 +- .../modules/{regressiontests => ROOT}/nav.adoc | 0 .../{regressiontests => ROOT}/pages/about.adoc | 0 .../adoc/modules/ROOT/partials/module-nav.adoc | 4 + .../regressiontests/partials/module-nav.adoc | 4 - .../parent-pom/images/parent-pom.drawio.svg | 5 +- .../adoc/modules/ROOT/partials/component-nav.adoc | 2 +- 49 files changed, 2262 insertions(+), 484 deletions(-) diff --git a/README.adoc b/README.adoc index 0a91b86d50..0e6d196cf0 100644 --- a/README.adoc +++ b/README.adoc @@ -5,7 +5,6 @@ image:https://maven-badges.herokuapp.com/maven-central/org.apache.isis.core/isis-applib/badge.svg[] image:https://github.com/apache/isis/workflows/Build%20and%20Test%20(w/%20Maven)/badge.svg[] -image:https://github.com/apache/isis/workflows/Build%20and%20Test%20(w/%20Gradle)/badge.svg[] image:https://sonarcloud.io/api/project_badges/measure?project=apache_isis&metric=alert_status[link="https://sonarcloud.io/dashboard?id=apache_isis";] image:https://github.com/apache-isis-committers/isis-nightly/workflows/Nightly/badge.svg[link="https://github.com/apache-isis-committers/isis-nightly/actions?query=workflow%3A%22Nightly%22";] diff --git a/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc b/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc index 781d34e236..d8031ffa4d 100644 --- a/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc +++ b/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc @@ -490,8 +490,14 @@ link:https://blogs.apache.org/roller-ui/login.rol[Log onto] the http://blogs.apa Copy-n-paste the above mailing list announcement should suffice. -== Update BASELINE for nightly builds +== Update BASELINE for the (non-ASF) nightly builds -Nightly builds (non-ASF) are generated using CI definitions in the link:https://github.com/apache-isis-committers/isis-nightly[github.com/apache-isis-committers/isis-nightly] repo, published to the link:https://nexus.incode.work/repository/nightly-builds/[nightly-builds] repo of link:https://nexus.incode.work/[nexus.incode.work]: +Nightly builds of the framework's packages are available in two different locations: -* bump the `BASELINE` variable in link:https://github.com/apache-isis-committers/isis-nightly/blob/0fdea0c4e7419b40acc9a03746e4c3cac3f262b2/.github/workflows/apache-isis-ci-nightly.yml#L15[apache-isis-ci-nightly.yml] (workflow file). +* First, they can be found as packages of the main link:https://github.com/apache/isis[github.com/apache/isis] repo; these can be accessed using your github credentials. ++ +Bump the `BASELINE` variable in link:https://github.com/apache/isis/blob/master/.github/workflows/ci-build-artifacts-no-push-maven.yml#L20[ci-build-artifacts-no-push-maven.yml] (workflow file). + +* But they are also to be found as packages within the (non-ASF) link:https://github.com/apache-isis-committers/isis-nightly[github.com/apache-isis-committers/isis-nightly] repo; no credentials are required for these because the git repo is used as a package repository directly. ++ +Bump the `BASELINE` variable in link:https://github.com/apache-isis-committers/isis-nightly/blob/0fdea0c4e7419b40acc9a03746e4c3cac3f262b2/.github/workflows/apache-isis-ci-nightly.yml#L15[apache-isis-ci-nightly.yml] (workflow file). diff --git a/antora/components/conguide/modules/documentation/pages/asciidoc-syntax.adoc b/antora/components/conguide/modules/documentation/pages/asciidoc-syntax.adoc index 229c392924..d4f7afd72b 100644 --- a/antora/components/conguide/modules/documentation/pages/asciidoc-syntax.adoc +++ b/antora/components/conguide/modules/documentation/pages/asciidoc-syntax.adoc @@ -801,9 +801,9 @@ For example: [c4plantuml,c4-demo,svg] ---- @startuml -!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4.puml -!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml -!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml +include::docs:resources:partial$C4.puml[] +include::docs:resources:partial$C4_Context.puml[] +include::docs:resources:partial$C4_Container.puml[] title System Context diagram for Internet Banking System diff --git a/antora/components/docs/modules/ROOT/pages/about.adoc b/antora/components/docs/modules/ROOT/pages/about.adoc index 58726904dc..337ebc97bc 100644 --- a/antora/components/docs/modules/ROOT/pages/about.adoc +++ b/antora/components/docs/modules/ROOT/pages/about.adoc @@ -136,15 +136,12 @@ _Automated Analysis_ * link:https://sonarcloud.io/dashboard?id=apache_isis[SonarCloud.io] * link:https://fisheye.apache.org/browse/~br=master/isis-git/[ASF Fisheye] -_In Development_ - -* xref:incubator:ROOT:about.adoc[Incubator] - +_Development_ -_Other_ +* xref:core:ROOT:about.adoc[] +* xref:regressiontests:ROOT:about.adoc[] +* xref:incubator:ROOT:about.adoc[] -* xref:core:_overview:about.adoc[System Overview] (generated) -* xref:core:ROOT:about.adoc[Design Docs] (out of date) _Thanks_ diff --git a/antora/components/docs/modules/ROOT/pages/landing-page/internal.adoc b/antora/components/docs/modules/ROOT/pages/landing-page/framework.adoc similarity index 100% rename from antora/components/docs/modules/ROOT/pages/landing-page/internal.adoc rename to antora/components/docs/modules/ROOT/pages/landing-page/framework.adoc diff --git a/antora/components/docs/modules/ROOT/pages/landing-page/releases.adoc b/antora/components/docs/modules/ROOT/pages/landing-page/releases.adoc index c0e9e87643..21e895680f 100644 --- a/antora/components/docs/modules/ROOT/pages/landing-page/releases.adoc +++ b/antora/components/docs/modules/ROOT/pages/landing-page/releases.adoc @@ -16,19 +16,25 @@ If your app inherits from the xref:docs:parent-pom:about.adoc[Parent POM], then <parent> <groupId>org.apache.isis.app</groupId> <artifactId>isis-app-starter-parent</artifactId> - <version>2.0.0</version> <!--1--> + <version>2.0.0</version> <!--.--> </parent> ---- -<1> update as required. +<.> update as required. == Nightly Builds If you like to live on the bleeding edge, there are also nightly builds of the framework. -* link:https://github.com/apache-isis-committers/isis-nightly[CI] -* link:https://repo.incode.cloud/[Maven Repo] -* link:https://apache-isis-committers.github.io/isis-nightly[Website preview] +* link:https://github.com/apache/isis[Packages] (ASF hosted) ++ +Requires github credentials to download packages + +* link:https://github.com/apache-isis-committers/isis-nightly[Packages] (not ASF hosted) ++ +Packages can be downloaded without authentication. + +* link:https://apache-isis-committers.github.io/isis-nightly[Website preview] (not ASF hosted) Although these are maintained and used by the framework's committers, do be aware that *these are _not_ official ASF releases*; they are provided as a convenience only. diff --git a/antora/components/docs/modules/ROOT/partials/module-nav/framework.adoc b/antora/components/docs/modules/ROOT/partials/module-nav/framework.adoc index c756fb5ea8..e93d65bb43 100644 --- a/antora/components/docs/modules/ROOT/partials/module-nav/framework.adoc +++ b/antora/components/docs/modules/ROOT/partials/module-nav/framework.adoc @@ -13,12 +13,14 @@ *** link:https://sonarcloud.io/dashboard?id=apache_isis[SonarCloud.io] *** link:https://fisheye.apache.org/browse/~br=master/isis-git/[ASF Fisheye] -** xref:incubator:ROOT:about.adoc[Incubator] -** Other +** Development -*** xref:core:_overview:about.adoc[System Overview] (generated) -*** xref:core:ROOT:about.adoc[Design Docs] (out of date) +*** xref:core:ROOT:about.adoc[] +*** xref:regressiontests:ROOT:about.adoc[] +*** xref:incubator:ROOT:about.adoc[] -** xref:more-thanks/more-thanks.adoc[Acknowledgements] +** Thanks + +*** xref:more-thanks/more-thanks.adoc[Acknowledgements] diff --git a/antora/components/docs/modules/resources/pages/eventbus_domain.adoc b/antora/components/docs/modules/resources/pages/eventbus_domain.adoc deleted file mode 100644 index ef2e90c2f1..0000000000 --- a/antora/components/docs/modules/resources/pages/eventbus_domain.adoc +++ /dev/null @@ -1,73 +0,0 @@ -= eventbus_domain - -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] - -.eventbus_domain -[plantuml,file="eventbus_domain.png"] - --- -@startuml - -skinparam nodesep 20 - -together { - (Domain\nService) as DS - (Domain\nObject) as DO - (<i>Domain\n<i>Event) as DE -} -(<i>Member</i>) as MB -together { - (Property) as P - (Action) as A - (Collection) as C -} -P -u-> MB : is a -A -u-> MB : is a -C -u-> MB : is a - -DO -d-> MB : has -DS -d--> A : has - -DE -d-> MB : can be \n declared \n for - -(Execution) as EX -P "edit \n is an"--> EX -A "invocation \n is an"--> EX - -(Event\nBus) as EB -(Spring) as SPRING -SPRING .l.> EB : provides/\nmanages -EX -> EB : is published as: \n * before event (phase: EXECUTING)\n * after event (phase: EXECUTED) - -(Event\nListener) as EL -EL --> EB : listens \n on -EL -u-> MB : can check/modify: \nvisibility (hide), \nusability (disable), \nvalidity (validate) - -note right of DE -Phases are: -* HIDING -* DISABLING -* VALIDATING -* EXECUTING -* EXECUTED -The framework automatically sends out -events with the phases in the order listed. -end note - -note right of MB -<i>DomainEvent</i> is declared as an -annotation type element in a member annotation, e.g. -<b>@Action( - <b>domainEvent=<i>Custom</i>ActionDomainEvent.class). -end note - -note right of EL -EventListeners can be declared on -any public Spring bean method, e.g. -<b>@EventListener( - <b><i>Custom</i>ActionDomainEvent.class). -Via <i>DomainEvent</i>.getEventPhase(), -further filtering can be applied. -end note -@enduml --- diff --git a/antora/components/docs/modules/resources/pages/eventbus_persistence.adoc b/antora/components/docs/modules/resources/pages/eventbus_persistence.adoc deleted file mode 100644 index 1f2b96dff4..0000000000 --- a/antora/components/docs/modules/resources/pages/eventbus_persistence.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= eventbus_persistence - -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] - -.eventbus_persistence -[plantuml,file="eventbus_persistence.png"] --- -@startuml - -(Event\nBus) as EB -(Spring) as SPRING -SPRING .l.> EB : provides/\nmanages -(Event\nListener) as EL -EL --> EB : listens - -(<i>Object</i>\nLifecyleEvent) as LCE -LCE -> EB : published to -(Created\nEvent) as C -C -u-> LCE : is a -(Loaded\nEvent) as L -L -u-> LCE : is a - -(Persisting\nEvent) as PNG -PNG -u-> LCE : is a -(Persisted\nEvent) as PED -PED -u-> LCE : is a - -(Updating\nEvent) as UNG -UNG -u-> LCE : is a -(Updated\nEvent) as UED -UED -u-> LCE : is a - -(Removing\nEvent) as RNG -RNG -u-> LCE : is a - -(Factory\nService) as FS -FS -u-> C :emits -(Repository\nService) as RS -RS -u-> L :emits -RS -u-> PNG :emits -RS -u-> PED :emits -RS -u-> UNG :emits -RS -u-> UED :emits -RS -u-> RNG :emits - -note top of RNG -JDO/Datanucleus -does not support -something like a -"Removed Event". -Hence not implemented. -end note - -@enduml --- diff --git a/antora/components/docs/modules/resources/pages/eventbus_ui.adoc b/antora/components/docs/modules/resources/pages/eventbus_ui.adoc deleted file mode 100644 index 728e1afa96..0000000000 --- a/antora/components/docs/modules/resources/pages/eventbus_ui.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= eventbus_ui - -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] - -.eventbus_ui -[plantuml,file="eventbus_ui.png"] --- -@startuml - -skinparam nodesep 20 - -(Event\nBus) as EB -(Spring) as SPRING -SPRING .l.> EB : provides/\nmanages -(Event\nListener) as EL -EL --> EB : listens to \n (is subscribed to) - -(UI\nEvent) as UIE -UIE -r-> EB : is \n published \n to - -(Title\nUIEvent) as TUIE -TUIE -u-> UIE : is a -(Icon\nUIEvent) as IUIE -IUIE -u-> UIE : is a - -(CssClass\nUIEvent) as CCUIE -CCUIE -u-> UIE : is a -(Layout\nUIEvent) as LUIE -LUIE -u-> UIE : is a - - -(Domain\nObject) as DO -DO "when \n rendered, \n leads to \n emission \nof"-d-> UIE - -(Presentation) as PST -DO -u-> PST : has -EL -u-> PST : can modify -note right of EL -When DomainObject implements -respective supporting methods itself ( -* title(), -* iconName(), -* cssClass(), -* layout()), -modification is not possible. -end note - -@enduml --- - -DE -d-> MB : can be \n declared \n for - - -EL -u-> MB : can modify/check: \nvisibility (hide), \nusability (disable), \nvalidity (validate) - -DO ->"title \n icon \n cssClass \n layout" PST -(UI\nEvent) as UIE -EL --> PST : modify -UIE --> EL : receive diff --git a/antora/components/docs/modules/resources/pages/metamodel.adoc b/antora/components/docs/modules/resources/pages/metamodel.adoc deleted file mode 100644 index 6b70c8ef15..0000000000 --- a/antora/components/docs/modules/resources/pages/metamodel.adoc +++ /dev/null @@ -1,106 +0,0 @@ -= metamodel - -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] - -.metamodel -[plantuml,file="metamodel.png"] --- -@startuml -!include <logos/java> -!include <tupadr3/font-awesome/at> -!include <tupadr3/font-awesome/envira> -!include <office/Databases/database_cube> -!include <material/xml.puml> - -legend top -|= notation |= explanation | -| ""__underline__"" | DDD Pattern| -endlegend - -together { - rectangle "<$database_cube><$at>\n<<Annotation>>\nORM (JPA/JDO)" as PERS - rectangle "<$envira><$at>\n<<Annotation>>\nSpring" as SPRING - rectangle "<img:https://isis.apache.org/_/img/home/isis-logo-56x64.png><$at>\n<<Annotation>>\nApache Isis" as FW - rectangle "<img:https://isis.apache.org/_/img/home/isis-logo-56x64.png><$java>\n<<Supprting Methods>>\nApache Isis" as SM - rectangle "<$java><$ma_xml><$at>\n<<Annotation>>\nJAXB" as JAXB - - SPRING -[hidden]- PERS - PERS -[hidden]- FW - FW -[hidden]- SM - SM -[hidden]- JAXB - - note left of SPRING - * __Repository__ - * Name (@Named) - * Service (via FW @DomainService) - * Component (via FW @DomainObject) - end note - - note left of PERS - * Cardinality - * TableName - * Column - ** Name - ** Length - ** Type - end note - - note left of FW - * __Entitiy__ - ** Property - ** Collection - ** Action - * __Factory__ - * Layout - ** Property Sequence - (Table and Forms) - ** Action Sequence (Menu) - ** Styles (cssClass) - * ViewModel - * Mixin - end note - - note left of SM - * autoComplete…() - * choices…() - * default…() - * disable…() - * get…() - * hide…() - * iconName() - * set…() - * title() - * validate…() - end note - - note left of JAXB - * @XmlAccessorType - * @XmlJavaTypeAdapter - * @XmlRootElement - end note -} - -rectangle "<img:https://isis.apache.org/_/img/home/isis-logo-56x64.png>\nMetaModel" as MM - -SPRING -> MM -PERS -> MM -FW -> MM -SM -> MM -JAXB -> MM - -(MetaModelValidation) as MMV -MM <- MMV : perform \n consistency \n check - -rectangle "WicketViewer" as UI -database DB -interface "Restful\nObjects" as REST -MM -d-> UI : generate -MM -d-> DB : generate -MM -d-> REST : generate - -@enduml --- -note left of UI -File | Edit | Help -end note - diff --git a/antora/components/docs/modules/resources/pages/metamodel_terminology.adoc b/antora/components/docs/modules/resources/pages/metamodel_terminology.adoc deleted file mode 100644 index 466ec045be..0000000000 --- a/antora/components/docs/modules/resources/pages/metamodel_terminology.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= metamodel_terminology - -== Metamodel Terminology - -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] - -[plantuml,file="metamodel_terminology.png"] -.Metamodel Terminology --- -@startuml - -skinparam nodesep 20 -skinparam ranksep 1 - -together { - (Domain\nObject) as DO - (Entity) as E - (View\nModel) as VM -} -(<i>Apache Isis</i>) as FW -(Persistence\nLayer) as PL -together { - (Mixin) as M - (Mixee) as ME -} -(Service) as S -(Domain\nService) as DS -(<i>Spring</i>) as SPRING -together { - (Member) as MB - (Property) as P - (Collection) as C - (Action) as A -} - -DO <-d-"is a" VM -DO <-d-"is a" E -FW .u.> VM : manages -PL .u.> E : manages - -P "is a"-u-> MB -C "is a"-u-> MB -A "is a"-u-> MB - -DO --> MB : has 1..* - -M "contributes\n a"..> MB -M "contributes\n to"-> ME -DO -> ME : can \n act \n as - -SPRING ..> S : manages -DS "is a"-u-> S -DS --> A : has 1..* -@enduml --- - -*_Viewmodels_* and *_Entities_* are specializations of *_Domain Objects_*. - -_Domain Objects_ have *_Properties_*, *_Collections_* and *_Actions_*, -while _Viewmodels_ are (lifecycle-) managed by _Apache Isis_, -_Entities_ are managed by the configured persistence layer -(either JDO or JPA). - -*_Services_* in general are (lifecycle-) managed by _Spring_. -We distinguish between _Services_ that are *_included_* in the metamodel -and those that are not. Included _Services_ we call *_Domain Services_*, -and their _Actions_ (like _Domain Objects_) are part of the metamodel. - -Those _Actions_ are either visible as _Menu Actions_ in the UI -and/or made available for the _Restful Objects Viewer_. -(As indicated by the so called _Service's_ *_Nature_*.) - -*_Mixins_* do *_contribute_* either a _Property_, a _Collection_ -or an _Action_ to their *_Mixee_* (-type). diff --git a/antora/components/docs/modules/resources/partials/C4.puml b/antora/components/docs/modules/resources/partials/C4.puml new file mode 100644 index 0000000000..5ce387bb77 --- /dev/null +++ b/antora/components/docs/modules/resources/partials/C4.puml @@ -0,0 +1,1210 @@ +' C4-PlantUML + +'Version +' ################################## +!function C4Version() + !return "2.5.0beta1" +!end function + +!procedure C4VersionDetails() +rectangle C4VersionDetailsArea <<legendArea>> [ +| PlantUML | **%version()** | +| C4-PlantUML | **C4Version()** | +] +!end procedure + +' Colors +' ################################## + +!global $ELEMENT_FONT_COLOR = "#FFFFFF" + +!global $ARROW_COLOR = "#666666" + +!global $BOUNDARY_COLOR = "#444444" +!global $BOUNDARY_BG_COLOR = "transparent" + +!global $LEGEND_FONT_COLOR = "#FFFFFF" +!global $LEGEND_TITLE_COLOR = "#000000" +' %darken(darkkhaki,50), #khaki +!global $LEGEND_DARK_COLOR = "#66622E" +!global $LEGEND_LIGHT_COLOR = "#khaki" + +!global $SKETCH_BG_COLOR = "#EEEBDC" +!global $SKETCH_FONT_COLOR = "" +!global $SKETCH_WARNING_COLOR = "red" +!global $SKETCH_FONT_NAME = "Comic Sans MS" + +' Labels +' ################################## + +!global $LEGEND_SHADOW_TEXT = "(shadow) " +!global $LEGEND_NO_SHADOW_TEXT = "(no shadow) " +!global $LEGEND_NO_FONT_BG_TEXT = "(no text, no back color) " +!global $LEGEND_NO_FONT_TEXT = "(no text color) " +!global $LEGEND_NO_BG_TEXT = "(no back color) " +!global $LEGEND_NO_LINE_TEXT = "(no line color) " +!global $LEGEND_ROUNDED_BOX = "(rounded box) " +!global $LEGEND_EIGHT_SIDED = "(eight sided) " +!global $LEGEND_DOTTED_LINE = "(dotted) " +!global $LEGEND_DASHED_LINE = "(dashed) " +!global $LEGEND_BOLD_LINE = "(bold) " + +!global $SKETCH_FOOTER_WARNING = "Warning:" +!global $SKETCH_FOOTER_TEXT = "Created for discussion, needs to be validated" + +' Styling +' ################################## + +!global $TECHN_FONT_SIZE = 12 +!global $ROUNDED_BOX_SIZE = 25 +!global $EIGHT_SIDED_SIZE = 18 + +!global $ROUNDED_BOX = "roundedBox" +!global $EIGHT_SIDED = "eightSided" + +!global $DOTTED_LINE = "dotted" +!global $DASHED_LINE = "dashed" +!global $BOLD_LINE = "bold" + +skinparam defaultTextAlignment center + +skinparam wrapWidth 200 +skinparam maxMessageSize 150 + +skinparam LegendBorderColor transparent +skinparam LegendBackgroundColor transparent +skinparam LegendFontColor $LEGEND_FONT_COLOR + +skinparam shadowing<<legendArea>> false +' #00000000 is transparent +skinparam rectangle<<legendArea>> { + backgroundcolor #00000000 + bordercolor #00000000 +} + +skinparam rectangle { + StereotypeFontSize 12 + shadowing false +} + +skinparam database { + StereotypeFontSize 12 + shadowing false +} + +skinparam queue { + StereotypeFontSize 12 + shadowing false +} + +skinparam arrow { + Color $ARROW_COLOR + FontColor $ARROW_COLOR + FontSize 12 +} + +skinparam actor { + StereotypeFontSize 12 + shadowing false + style awesome +} + +skinparam person { + StereotypeFontSize 12 + shadowing false +} + +' Some boundary skinparams have to be set as package skinparams too (PlantUML uses internal packages) +skinparam package { + StereotypeFontSize 6 + StereotypeFontColor $BOUNDARY_BG_COLOR + FontStyle plain + BackgroundColor $BOUNDARY_BG_COLOR +} + +skinparam rectangle<<boundary>> { + Shadowing false + StereotypeFontSize 6 + StereotypeFontColor $BOUNDARY_BG_COLOR + FontColor $BOUNDARY_COLOR + BorderColor $BOUNDARY_COLOR + BackgroundColor $BOUNDARY_BG_COLOR + BorderStyle dashed +} + +' Legend and Tags +' ################################## +!global $tagDefaultLegend = "" +!global $tagCustomLegend = "" + +' rel specific +!unquoted function $toStereos($tags) + !if (%strlen($tags) == 0) + !return '' + !endif + !$stereos = '' + !$brPos = %strpos($tags, "+") + !while ($brPos >= 0) + !$tag = %substr($tags, 0, $brPos) + !$stereos = $stereos + '<<' + $tag + '>>' +%set_variable_value("$" + $tag + "_LineLegend", %true()) + !$tags = %substr($tags, $brPos+1) + !$brPos = %strpos($tags, "+") + !endwhile + !if (%strlen($tags) > 0) + !$stereos = $stereos + '<<' + $tags + '>>' +%set_variable_value("$" + $tags + "_LineLegend", %true()) + !endif + !return $stereos +!endfunction + +' if $sprite/$techn is an empty argument, try to calculate it via the defined $tag +!unquoted function $toRelArg($arg, $tags, $varPostfix) + !if ($arg > "") + !return $arg + !endif + + !if (%strlen($tags) == 0) + !return $arg + !endif + !$brPos = %strpos($tags, "+") + !while ($brPos >= 0) + !$tag = %substr($tags, 0, $brPos) + !$newArg = %get_variable_value("$" + $tag + $varPostfix) + !if ($newArg > "") + !return $newArg + !endif + !$tags = %substr($tags, $brPos+1) + !$brPos = %strpos($tags, "+") + !endwhile + !if (%strlen($tags) > 0) + !$newArg = %get_variable_value("$" + $tags + $varPostfix) + !if ($newArg > "") + !return $newArg + !endif + !endif + !return $arg +!endfunction + +' element specific (unused are hidden based on mask) +!unquoted function $toStereos($elementType, $tags) + !if (%strlen($tags) == 0) + !$stereos = '<<' + $elementType + '>>' +%set_variable_value("$" + $elementType + "Legend", %true()) + !return $stereos + !endif + !$stereos = '' + !$mask = $resetMask() + !$brPos = %strpos($tags, "+") + !while ($brPos >= 0) + !$tag = %substr($tags, 0, $brPos) + !$stereos = $stereos + '<<' + $tag + '>>' + !$mergedMask = $combineMaskWithTag($mask, $tag) + !if ($mergedMask != $mask) +%set_variable_value("$" + $tag + "Legend", %true()) + !$mask = $mergedMask + !endif + !$tags = %substr($tags, $brPos+1) + !$brPos = %strpos($tags, "+") + !endwhile + !if (%strlen($tags) > 0) + !$stereos = $stereos + '<<' + $tags + '>>' + !$mergedMask = $combineMaskWithTag($mask, $tags) + !if ($mergedMask != $mask) +%set_variable_value("$" + $tags + "Legend", %true()) + !$mask = $mergedMask + !endif + !endif + ' has to be last, otherwise PlantUML overwrites all tag specific skinparams + !$stereos = $stereos + '<<' + $elementType + '>>' + !$mergedMask = $combineMaskWithTag($mask, $elementType) + !if ($mergedMask != $mask) +%set_variable_value("$" + $elementType + "Legend", %true()) + !$mask = $mergedMask + !endif + !return $stereos +!endfunction + +' if $sprite/$techn is an empty argument, try to calculate it via the defined $tag +!unquoted function $toElementArg($arg, $tags, $varPostfix, $elementType) + !if ($arg > "") + !return $arg + !endif + + !if (%strlen($tags) == 0) + !$newArg = %get_variable_value("$" + $elementType + $varPostfix) + !if ($newArg > "") + !return $newArg + !else + !return $arg + !endif + !endif + !$brPos = %strpos($tags, "+") + !while ($brPos >= 0) + !$tag = %substr($tags, 0, $brPos) + !$newArg = %get_variable_value("$" + $tag + $varPostfix) + !if ($newArg > "") + !return $newArg + !endif + !$tags = %substr($tags, $brPos+1) + !$brPos = %strpos($tags, "+") + !endwhile + !if (%strlen($tags) > 0) + !$newArg = %get_variable_value("$" + $tags + $varPostfix) + !if ($newArg > "") + !return $newArg + !endif + !$newArg = %get_variable_value("$" + $elementType + $varPostfix) + !if ($newArg > "") + !return $newArg + !endif + !endif + !return $arg +!endfunction + +!function $elementTagSkinparams($element, $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape) + !$elementSkin = "skinparam " + $element + "<<" + $tagStereo + ">> {" + %newline() + !if ($fontColor != "") + !if ($tagStereo != "boundary") + !$elementSkin = $elementSkin + " StereotypeFontColor " + $fontColor + %newline() + !endif + !$elementSkin = $elementSkin + " FontColor " + $fontColor + %newline() + !endif + !if ($bgColor != "") + !$elementSkin = $elementSkin + " BackgroundColor " + $bgColor + %newline() + !endif + !if ($borderColor != "") + !$elementSkin = $elementSkin + " BorderColor " + $borderColor+ %newline() + !endif + !if ($shadowing == "true") + !$elementSkin = $elementSkin + " Shadowing<<" + $tagStereo + ">> " + "true" + %newline() + !endif + !if ($shadowing == "false") + !$elementSkin = $elementSkin + " Shadowing<<" + $tagStereo + ">> " + "false" + %newline() + !endif + ' only rectangle supports shape(d corners), define both skinparam that overlays are working + !if ($shape != "" && $element == "rectangle") + !if ($shape == $ROUNDED_BOX) + !$elementSkin = $elementSkin + " RoundCorner " + $ROUNDED_BOX_SIZE+ %newline() + !$elementSkin = $elementSkin + " DiagonalCorner " + "0" + %newline() + !elseif ($shape == $EIGHT_SIDED) + !$elementSkin = $elementSkin + " RoundCorner " + "0" + %newline() + !$elementSkin = $elementSkin + " DiagonalCorner " + $EIGHT_SIDED_SIZE+ %newline() + !endif + !endif + !$elementSkin = $elementSkin + "}" + %newline() + !return $elementSkin +!endfunction + +!unquoted procedure $defineSkinparams($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape) + ' only rectangle supports shape(d corners) + !$tagSkin = $elementTagSkinparams("rectangle", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape) + !$tagSkin = $tagSkin + $elementTagSkinparams("database", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, "") + !$tagSkin = $tagSkin + $elementTagSkinparams("queue", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, "") + ' actor has style awesome, therefore $fontColor is ignored and text uses $bgColor too + !$tagSkin = $tagSkin + $elementTagSkinparams("actor", $tagStereo, $bgColor, $bgColor, $borderColor, $shadowing, "") + !$tagSkin = $tagSkin + $elementTagSkinparams("person", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, "") + !if ($tagStereo == "boundary" && $bgColor != "") + !$tagSkin = $tagSkin + "skinparam package<<boundary>>StereotypeFontColor " + $bgColor + %newline() + !$tagSkin = $tagSkin + "skinparam rectangle<<boundary>>StereotypeFontColor " + $bgColor + %newline() + !endif +$tagSkin +!endprocedure + +' arrow colors cannot start with # (legend background has to start with #) +!function $colorWithoutHash($c) + !if (%substr($c, 0, 1) == "#") + !$c = %substr($c,1) + !endif + !return $c +!endfunction + +!unquoted procedure $defineRelSkinparams($tagStereo, $textColor, $lineColor, $lineStyle) + !$elementSkin = "skinparam arrow<<" + $tagStereo + ">> {" + %newline() + !$elementSkin = $elementSkin + " Color " + !if ($lineColor != "") + !$elementSkin = $elementSkin + $colorWithoutHash($lineColor) + !endif + !if ($textColor != "") + !$elementSkin = $elementSkin + ";text:" + $colorWithoutHash($textColor) + !endif + !if ($lineStyle != "") + !$elementSkin = $elementSkin + ";line." + $lineStyle + !endif + !$elementSkin = $elementSkin + %newline() + !$elementSkin = $elementSkin + "}" + %newline() +$elementSkin +!endprocedure + +' %is_dark() requires PlantUML version >= 1.2021.6 +!if (%function_exists("%is_dark")) + !$PlantUMLSupportsDynamicLegendColor = %true() +!else + !$PlantUMLSupportsDynamicLegendColor = %false() + !log "dynamic undefined legend colors" requires PlantUML version >= 1.2021.6, therefore only static assigned colors are used +!endif + +!unquoted function $contrastLegend($color) + !if (%is_dark($color)) + !$value = $LEGEND_LIGHT_COLOR + !else + !$value = $LEGEND_DARK_COLOR + !endif + !return $value +!endfunction + +!unquoted function $flatLegend($color) + !if (%is_dark($color)) + !$value = $LEGEND_DARK_COLOR + !else + !$value = $LEGEND_LIGHT_COLOR + !endif + !return $value +!endfunction + +' legend background has to start with # +!function $colorWithHash($c) + !if (%substr($c, 0, 1) != "#") + !$c = "#" + $c + !endif + !return $c +!endfunction + +!function $addMaskFlag($mask, $attr) + !if ($attr == "") + !$mask = $mask + "0" + !else + !$mask = $mask + "1" + !endif + !return $mask +!endfunction + +!function $orFlags($flag1, $flag2) + !if ($flag1 == "0" && $flag2 == "0") + !return "0" + !endif + !return "1" +!endfunction + +!function $tagLegendMask($bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite) + !$mask = "" + !$mask = $addMaskFlag($mask, $bgColor) + !$mask = $addMaskFlag($mask, $fontColor) + !$mask = $addMaskFlag($mask, $borderColor) + !$mask = $addMaskFlag($mask, $shadowing) + !$mask = $addMaskFlag($mask, $shape) + !$mask = $addMaskFlag($mask, $sprite) + !return $mask +!endfunction + +!function $resetMask() + !return "000000" +!endfunction + +!function $combineMasks($mask1, $mask2) + !$mask = "" + !$mask = $mask + $orFlags(%substr($mask1, 0, 1), %substr($mask2, 0, 1)) + !$mask = $mask + $orFlags(%substr($mask1, 1, 1), %substr($mask2, 1, 1)) + !$mask = $mask + $orFlags(%substr($mask1, 2, 1), %substr($mask2, 2, 1)) + !$mask = $mask + $orFlags(%substr($mask1, 3, 1), %substr($mask2, 3, 1)) + !$mask = $mask + $orFlags(%substr($mask1, 4, 1), %substr($mask2, 4, 1)) + !$mask = $mask + $orFlags(%substr($mask1, 5, 1), %substr($mask2, 5, 1)) + !return $mask +!endfunction + +!function $combineMaskWithTag($mask1, $tag) + !$mask2 = %get_variable_value("$" + $tag+ "LegendMask") + !if ($mask2 == "") + ' !log combineMaskWithTag $mask1, $tag, ... only $mask1 + !return $mask1 + !endif + + ' !log combineMaskWithTag $mask1, $tag, $mask2 ... $combineMasks($mask1, $mask2) + !return $combineMasks($mask1, $mask2) +!endfunction + +' element symbols typically 4 times too big in legend +!function $smallVersionSprite($sprite) + ' ,scale= ... has to be first (...,color=black,scale=0.25... is invalid too) + !if (%strpos($sprite, "=") < 0) + !if (%substr($sprite, 0, 4) == "img:") + !$smallSprite = $sprite + "{scale=0.25}" + !else + !$smallSprite = $sprite + ",scale=0.25" + !endif + !else + !$smallSprite = $sprite + !endif + !return $smallSprite +!endfunction + +' format sprite that it can be used in diagram +!function $getSprite($sprite) + ' if it starts with & it's a OpenIconic, details see https://useiconic.com/open/ + ' if it starts with img: it's an image, details see https://plantuml.com/creole + !if (%substr($sprite, 0, 1) != "&" && %substr($sprite, 0, 4) != "img:") + !$formatted = "<$" + $sprite + ">" + !else + !$formatted = "<" + $sprite + ">" + !endif + !return $formatted +!endfunction + +!function $tagLegendEntry($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $legendText, $legendSprite) + !$bg = $bgColor + !$fo = $fontColor + !$bo = $borderColor + + !if ($fo == "") + !if ($bg != "") +!if ($PlantUMLSupportsDynamicLegendColor) + !$fo = $contrastLegend($bg) +!else + !$fo = $LEGEND_DARK_COLOR +!endif + !else + !if ($bo == "") + !$fo = $LEGEND_DARK_COLOR + !$bg = $LEGEND_LIGHT_COLOR + !else +!if ($PlantUMLSupportsDynamicLegendColor) + !$fo = $flatLegend($bo) + !$bg = $contrastLegend($bo) +!else + !$fo = $LEGEND_DARK_COLOR + !$bg = $LEGEND_LIGHT_COLOR +!endif + !endif + !endif + !else + !if ($bg == "") +!if ($PlantUMLSupportsDynamicLegendColor) + !$bg = $contrastLegend($fo) +!else + !$bg = $LEGEND_LIGHT_COLOR +!endif + !endif + !endif + + !if ($bo == "") + !$bo = $bg + !endif + + !$tagEntry = "|" + !$tagEntry = $tagEntry + "<" + $colorWithHash($bg) +">" + ' <U+25AF> ..white rectangle + !$tagEntry = $tagEntry + "<color:"+$bo+"> <U+25AF></color> " + !$tagEntry = $tagEntry + "<color:"+$fo+">" + !if ($legendSprite != "") + !$tagEntry = $tagEntry + $getSprite($legendSprite) + " " + !endif + !if ($legendText == "") + !$tagEntry = $tagEntry + " " + $tagStereo + " " + !if ($shadowing == "true") + !$tagEntry = $tagEntry + $LEGEND_SHADOW_TEXT + !endif + !if ($shadowing == "false") + !$tagEntry = $tagEntry + $LEGEND_NO_SHADOW_TEXT + !endif + !if ($shape == $ROUNDED_BOX) + !$tagEntry = $tagEntry + $LEGEND_ROUNDED_BOX + !endif + !if ($shape == $EIGHT_SIDED) + !$tagEntry = $tagEntry + $LEGEND_EIGHT_SIDED + !endif + !if ($fontColor == "" && $bgColor == "") + !$tagEntry = $tagEntry + $LEGEND_NO_FONT_BG_TEXT + !else + !if ($fontColor == "") + !$tagEntry = $tagEntry + $LEGEND_NO_FONT_TEXT + !endif + !if ($bgColor == "") + !$tagEntry = $tagEntry + $LEGEND_NO_BG_TEXT + !endif + !endif + !else + !$tagEntry = $tagEntry + " " + $legendText + " " + !endif + + !$tagEntry = $tagEntry + "</color> " + !$tagEntry = $tagEntry + "|" + !return $tagEntry +!endfunction + +!function $tagRelLegendEntry($tagStereo, $textColor, $lineColor, $lineStyle, $legendText, $legendSprite) + !$tc = $textColor + !$lc = $lineColor + + !if ($tc == "") + !if ($PlantUMLSupportsDynamicLegendColor) + !$tc = $flatLegend($ARROW_COLOR) + !else + !$tc = $LEGEND_DARK_COLOR + !endif + !endif + !if ($lc == "") + !if ($PlantUMLSupportsDynamicLegendColor) + !$lc = $flatLegend($ARROW_COLOR) + !else + !$lc = $LEGEND_DARK_COLOR + !endif + !endif + + !$tagEntry = "|" + ' <U+2500> ..white line + !$tagEntry = $tagEntry + "<color:"+$lc+"> <U+2500></color> " + !$tagEntry = $tagEntry + "<color:"+$tc+">" + !if ($legendSprite != "") + !$tagEntry = $tagEntry + $getSprite($legendSprite) + " " + !endif + !if ($legendText == "") + !$tagEntry = $tagEntry + " " + $tagStereo + " " + !if ($textColor == "") + !$tagEntry = $tagEntry + $LEGEND_NO_FONT_TEXT + !endif + !if ($lineColor == "") + !$tagEntry = $tagEntry + $LEGEND_NO_LINE_TEXT + !endif + !if ($lineStyle != "") + !if ($lineStyle == $DOTTED_LINE) + !$tagEntry = $tagEntry + $LEGEND_DOTTED_LINE + !elseif ($lineStyle == $DASHED_LINE) + !$tagEntry = $tagEntry + $LEGEND_DASHED_LINE + !elseif ($lineStyle == $BOLD_LINE) + !$tagEntry = $tagEntry + $LEGEND_BOLD_LINE + !else + !$tagEntry = $tagEntry + "(" + $lineStyle + ") " + !endif + !endif + !else + !$tagEntry = $tagEntry + " " + $legendText + " " + !endif + + !$tagEntry = $tagEntry + "</color> " + !$tagEntry = $tagEntry + "|" + !return $tagEntry +!endfunction + +!global $LEGEND_DOTTED_LINE = "(dotted) " +!global $LEGEND_DASHED_LINE = "(dashed) " +!global $LEGEND_BOLD_LINE = "(bold) " + +!unquoted procedure $addTagToLegend($tagStereo, $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $legendText="", $legendSprite="") +'' if a combined element tag is defined (e.g. "v1.0&v1.1") then it is typically a merged color, +'' like a new $fontColor="#fdae61" therefore it should be added to the legend +'' and the & combined tags will be not removed +' !if (%strpos($tagStereo, "&") < 0) + !$tagEntry = $tagLegendEntry($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $legendText, $legendSprite) +%set_variable_value("$" + $tagStereo + "LegendEntry", $tagEntry) + !$tagCustomLegend = $tagCustomLegend + $tagStereo + "\n" + !$tagMask = $tagLegendMask( $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite) +%set_variable_value("$" + $tagStereo + "LegendMask", $tagMask) +' !endif +!endprocedure + +!unquoted procedure $addRelTagToLegend($tagStereo, $textColor="", $lineColor="", $lineStyle="", $legendText="", $legendSprite="") +'' Arrows have a bug with stereotype/skinparams and cannot combine text colors of one stereotype +'' and the line color of another stereotype. Therefore the text color of one tag and the line color +'' of another tag have to be combined via a "workaround" tag ("v1.0&v1.1"). +'' This workaround tag could be theoretically removed in the legend but after that there would +'' be an inconsistency between the element tags and the rel tags and therefore +'' & combined workaround tags are not removed too (and in unlikely cases the color itself could be changed) +' !if (%strpos($tagStereo, "&") < 0) + !$tagEntry = $tagRelLegendEntry($tagStereo, $textColor, $lineColor, $lineStyle, $legendText, $legendSprite) +%set_variable_value("$" + $tagStereo + "_LineLegendEntry", $tagEntry) + !$tagCustomLegend = $tagCustomLegend + $tagStereo + "_Line\n" +' !endif +!endprocedure + +!procedure $showActiveLegendEntries($allDefined) + !$brPos = %strpos($allDefined, "\n") + !while ($brPos >= 0) + !$tagStereo = %substr($allDefined, 0, $brPos) + !$allDefined = %substr($allDefined, $brPos+2) + !$brPos = %strpos($allDefined, "\n") + !if (%variable_exists("$" + $tagStereo + "Legend")) +%get_variable_value("$" + $tagStereo + "LegendEntry") + !endif + !endwhile + !if (%strlen($allDefined) > 0) + !$tagStereo = $allDefined + !if (%variable_exists("$" + $tagStereo + "Legend")) +%get_variable_value("$" + $tagStereo + "LegendEntry") + !endif + !endif +!endprocedure + +!function RoundedBoxShape() +!return $ROUNDED_BOX +!endfunction + +!function EightSidedShape() +!return $EIGHT_SIDED +!endfunction + +!function DottedLine() +!return $DOTTED_LINE +!endfunction + +!function DashedLine() +!return $DASHED_LINE +!endfunction + +!function BoldLine() +!return $BOLD_LINE +!endfunction + +' used by new defined tags +!unquoted procedure AddElementTag($tagStereo, $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $sprite="", $techn="", $legendText="", $legendSprite="") +$defineSkinparams($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape) + !if ($sprite!="") +%set_variable_value("$" + $tagStereo + "ElementTagSprite", $sprite) + !if ($legendSprite == "") + !$legendSprite = $smallVersionSprite($sprite) + !endif + !endif + !if ($techn != "") +%set_variable_value("$" + $tagStereo + "ElementTagTechn", $techn) + !endif +$addTagToLegend($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $legendText, $legendSprite) +!endprocedure + +' used by new defined rel tags +!unquoted procedure AddRelTag($tagStereo, $textColor="", $lineColor="", $lineStyle = "", $sprite="", $techn="", $legendText="", $legendSprite="") +$defineRelSkinparams($tagStereo, $textColor, $lineColor, $lineStyle) + !if ($sprite != "") +%set_variable_value("$" + $tagStereo + "RelTagSprite", $sprite) + !if ($legendSprite == "") + ' relation symbols typically 1:1 no additional scale required + !$legendSprite = $sprite + !endif + !endif + !if ($techn != "") +%set_variable_value("$" + $tagStereo + "RelTagTechn", $techn) + !endif +$addRelTagToLegend($tagStereo, $textColor, $lineColor, $lineStyle, $legendText, $legendSprite) +!endprocedure + +' update the style of existing elements like person, ... +!unquoted procedure UpdateElementStyle($elementName, $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $sprite="", $techn="", $legendText="", $legendSprite="") +$defineSkinparams($elementName, $bgColor, $fontColor, $borderColor, $shadowing, $shape) + !if ($sprite != "") +%set_variable_value("$" + $elementName + "ElementTagSprite", $sprite) + !if ($legendSprite == "") + !$legendSprite = $smallVersionSprite($sprite) + !endif + !endif + !if ($techn != "") +%set_variable_value("$" + $elementName + "ElementTagTechn", $techn) + !endif + !$tagEntry = $tagLegendEntry($elementName, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $legendText, $legendSprite) +%set_variable_value("$" + $elementName + "LegendEntry", $tagEntry) + ' default tags sets at least bgColor and fontColor + !$tagMask = $tagLegendMask("CHANGED", "CHANGED", $borderColor, $shadowing, $shape, $sprite) +%set_variable_value("$" + $elementName + "LegendMask", $tagMask) +!endprocedure + +/' @deprecated in favor of UpdateElementStyle '/ +!unquoted procedure UpdateSkinparamsAndLegendEntry($elementName, $bgColor="", $fontColor="", $borderColor="", $shadowing="") +UpdateElementStyle($elementName, $bgColor, $fontColor, $borderColor, $shadowing) +!endprocedure + +' update the style of default relation, it has to set both properties (combined statement not working) +!unquoted procedure UpdateRelStyle($textColor, $lineColor) + !$elementSkin = "skinparam arrow {" + %newline() + !$elementSkin = $elementSkin + " Color " + $lineColor + %newline() + !$elementSkin = $elementSkin + " FontColor " + $textColor + %newline() + !$elementSkin = $elementSkin + "}" + %newline() +$elementSkin +!endprocedure + +' tags/stereotypes have to be delimited with \n +!unquoted procedure SetDefaultLegendEntries($tagStereoEntries) + !$tagDefaultLegend = $tagStereoEntries +!endprocedure + +' Links +' ################################## + +!function $getLink($link) + !if ($link != "") + !return "[[" + $link + "]]" + !else + !return "" + !endif +!endfunction + +' Line breaks +' ################################## + +' PlantUML supports no DETERMINISTIC/automatic line breaks of "PlantUML line" (C4 Relashionships) +' therefore Rel...() implements an automatic line break based on spaces (like in all other objects). +' If a $type contains \n then these are used (and no automatic space based line breaks are done) +' $REL_TECHN_MAX_CHAR_WIDTH defines the automatic line break position +!global $REL_TECHN_MAX_CHAR_WIDTH = 35 +!global $REL_DESCR_MAX_CHAR_WIDTH = 32 + +!unquoted function $breakDescr($descr, $widthStr) +!$width = %intval($widthStr) +!$multiLine = "" +!if (%strpos($descr, "\n") >= 0) +!else + !while (%strlen($descr) > $width) + !$brPos = $width + !while ($brPos > 0 && %substr($descr, $brPos, 1) != ' ') + !$brPos = $brPos - 1 + !endwhile + + !if ($brPos < 1) + !$brPos = %strpos($descr, " ") + !else + !endif + + !if ($brPos > 0) + !$multiLine = $multiLine + %substr($descr, 0, $brPos) + "\n" + !$descr = %substr($descr, $brPos + 1) + !else + !$multiLine = $multiLine+ $descr + !$descr = "" + !endif + !endwhile +!endif +!if (%strlen($descr) > 0) + !$multiLine = $multiLine + $descr +!endif +!return $multiLine +!endfunction + +' $breakTechn() supports //...//; $breakNode() in C4_Deployment supports no //....// +!unquoted function $breakTechn($techn, $widthStr) +!$width = %intval($widthStr) +!$multiLine = "" +!if (%strpos($techn, "\n") >= 0) + !while (%strpos($techn, "\n") >= 0) + !$brPos = %strpos($techn, "\n") + !$multiLine = $multiLine + %substr($techn, 0, $brPos) + '</size>//\n//<size:'+$TECHN_FONT_SIZE+'>' + !$techn = %substr($techn, $brPos+2) + !endwhile +!else + !while (%strlen($techn) > $width) + !$brPos = $width + !while ($brPos > 0 && %substr($techn, $brPos, 1) != ' ') + !$brPos = $brPos - 1 + !endwhile + + !if ($brPos < 1) + !$brPos = %strpos($techn, " ") + !else + !endif + + !if ($brPos > 0) + !$multiLine = $multiLine + %substr($techn, 0, $brPos) + '</size>//\n//<size:'+$TECHN_FONT_SIZE+'>' + !$techn = %substr($techn, $brPos + 1) + !else + !$multiLine = $multiLine+ $techn + !$techn = "" + !endif + !endwhile +!endif +!if (%strlen($techn) > 0) + !$multiLine = $multiLine + $techn +!endif +!return $multiLine +!endfunction + +' Element properties +' ################################## + +' collect all defined properties as table rows +!global $propTable = "" +!global $propTableCaption = "" +!global $propColCaption = "=" + +!unquoted function SetPropertyHeader($col1Name, $col2Name, $col3Name = "", $col4Name = "") + !$propColCaption = "" + !$propTableCaption = "|= " + $col1Name + " |= " + $col2Name + " |" + !if ($col3Name != "") + !$propTableCaption = $propTableCaption + "= " + $col3Name + " |" + !endif + !if ($col4Name != "") + !$propTableCaption = $propTableCaption + "= " + $col4Name + " |" + !endif + !return "" +!endfunction + +!unquoted function WithoutPropertyHeader() + !$propTableCaption = "" + !$propColCaption = "=" + !return "" +!endfunction + +!unquoted function AddProperty($col1, $col2, $col3 = "", $col4 = "") + !if ($propTable == "") + !if ($propTableCaption != "") + !$propTable = $propTableCaption + "\n" + !endif + !else + !$propTable = $propTable + "\n" + !endif + !$propTable = $propTable + "| " + $col1 + " |" + $propColCaption + " " + $col2 + " |" + !if ($col3 != "") + !$propTable = $propTable + " " + $col3 + " |" + !endif + !if ($col4 != "") + !$propTable = $propTable + " " + $col4 + " |" + !endif + !return "" +!endfunction + +!unquoted function $getProps($alignedNL = "\n") + !if ($propTable != "") + !$retTable = $alignedNL + $propTable + !$propTable = "" + !return $retTable + !endif + !return "" +!endfunction + +!unquoted function $getProps_L() + !return $getProps("\l") +!endfunction + +!unquoted function $getProps_R() + !return $getProps("\r") +!endfunction + +SetPropertyHeader("Property","Value") + +' Layout +' ################################## + +!procedure $getHideStereotype($hideStereotype) +!if ($hideStereotype == "true") +hide stereotype +!endif +!endprocedure + +!procedure $getLegendTable() +<#00000000,#00000000>|<color:$LEGEND_TITLE_COLOR>**Legend**</color> | +$showActiveLegendEntries($tagDefaultLegend) +$showActiveLegendEntries($tagCustomLegend) +!endprocedure + +!procedure $getLegendArea($areaAlias, $hideStereotype) +$getHideStereotype($hideStereotype) +rectangle $areaAlias<<legendArea>> [ +$getLegendTable() +] +!endprocedure + +!procedure HIDE_STEREOTYPE() +hide stereotype +!endprocedure + +!unquoted procedure SET_SKETCH_STYLE($bgColor="_dont_change_", $fontColor="_dont_change_", $warningColor="_dont_change_", $fontName="_dont_change_", $footerWarning="_dont_change_", $footerText="_dont_change_") +!if $bgColor != "_dont_change_" + !global $SKETCH_BG_COLOR = $bgColor +!endif +!if $fontColor != "_dont_change_" + !global $SKETCH_FONT_COLOR = $fontColor +!endif +!if $warningColor != "_dont_change_" + !global $SKETCH_WARNING_COLOR = $warningColor +!endif +!if $fontName != "_dont_change_" + !global $SKETCH_FONT_NAME = $fontName +!endif +!if $footerWarning != "_dont_change_" + !global $SKETCH_FOOTER_WARNING = $footerWarning +!endif +!if $footerText != "_dont_change_" + !global $SKETCH_FOOTER_TEXT = $footerText +!endif +!endprocedure + +!procedure LAYOUT_AS_SKETCH() + skinparam handwritten true +!if $SKETCH_BG_COLOR > "" + skinparam backgroundColor $SKETCH_BG_COLOR +!endif +!if $SKETCH_FONT_COLOR > "" + skinparam footer { + FontColor $SKETCH_FONT_COLOR + } + !if $ARROW_COLOR == "#666666" + !global $ARROW_COLOR = $SKETCH_FONT_COLOR + skinparam arrow { + Color $ARROW_COLOR + FontColor $ARROW_COLOR + } + !endif + !if $BOUNDARY_COLOR == "#444444" + !global $BOUNDARY_COLOR = $SKETCH_FONT_COLOR + skinparam rectangle<<boundary>> { + FontColor $BOUNDARY_COLOR + BorderColor $BOUNDARY_COLOR + } + !endif +!endif +!if $SKETCH_FONT_NAMES > "" + skinparam defaultFontName $SKETCH_FONT_NAME +!endif +!if $SKETCH_FOOTER_WARNING > "" || $SKETCH_FOOTER_TEXT > "" + !$line = "footer <font color=" + $SKETCH_WARNING_COLOR + ">"+ $SKETCH_FOOTER_WARNING + "</font> " + $SKETCH_FOOTER_TEXT + $line +!endif +!endprocedure + +!global $fix_direction=%false() + +!function $down($start,$end) +!if ($fix_direction) +!return $start+"RIGHT"+$end +!else +!return $start+"DOWN"+$end +!endif +!endfunction + +!function $up($start,$end) +!if ($fix_direction) +!return $start+"LEFT"+$end +!else +!return $start+"UP"+$end +!endif +!endfunction + +!function $left($start,$end) +!if ($fix_direction) +!return $start+"UP"+$end +!else +!return $start+"LEFT"+$end +!endif +!endfunction + +!function $right($start,$end) +!if ($fix_direction) +!return $start+"DOWN"+$end +!else +!return $start+"RIGHT"+$end +!endif +!endfunction + +!procedure LAYOUT_TOP_DOWN() +!global $fix_direction=%false() +top to bottom direction +!endprocedure + +!procedure LAYOUT_LEFT_RIGHT() +!global $fix_direction = %false() +left to right direction +!endprocedure + +!procedure LAYOUT_LANDSCAPE() +!global $fix_direction = %true() +left to right direction +!endprocedure + +' has to be last call in diagram +!unquoted procedure SHOW_LEGEND($hideStereotype="true") +$getHideStereotype($hideStereotype) +legend right +$getLegendTable() +endlegend +!endprocedure + +/' @deprecated in favor of SHOW_LEGEND '/ +!unquoted procedure SHOW_DYNAMIC_LEGEND($hideStereotype="true") +SHOW_LEGEND($hideStereotype) +!endprocedure + +' legend is reserved and cannot be uses as alias of SHOW_FLOATING_LEGEND() therefore +' LEGEND() is introduced. It returns the default name of the floating alias "floating_legend_alias" +' and can be used in the Lay_Distance() calls +!function LEGEND() +!return "floating_legend_alias" +!endfunction + +' enables that legend can be located in drawing area of the diagram. It has to be last call in diagram followed by Lay_Distance() +!unquoted procedure SHOW_FLOATING_LEGEND($alias=LEGEND(), $hideStereotype="true") +$getLegendArea($alias, $hideStereotype) +!endprocedure + +' Boundaries +' ################################## + +!function $getBoundary($label, $type) + !if ($type == "") + !return '==' + $label + !endif + !if (type != "") + !return '==' + $label + '\n<size:' + $TECHN_FONT_SIZE + '>[' + $type + ']</size>' + !endif +!endfunction + +!unquoted procedure Boundary($alias, $label, $type="", $tags="", $link="") +rectangle "$getBoundary($label, $type)" $toStereos("boundary", $tags) as $alias $getLink($link) +!endprocedure + +' Relationship +' ################################## + +!function $getRel($direction, $alias1, $alias2, $label, $techn, $descr, $sprite, $tags, $link) + !$sprite = $toRelArg($sprite, $tags, "RelTagSprite") + !$techn = $toRelArg($techn, $tags, "RelTagTechn") + !$rel = $alias1 + ' ' + $direction + ' ' + $alias2 + !if ($tags != "") + !$rel = $rel + ' ' + $toStereos($tags) + !endif + !$rel = $rel + ' : ' + !if ($sprite != "") + !$rel = $rel + $getSprite($sprite) + ' ' + !endif + !if ($link != "") + !$rel = $rel + '**[[' + $link + ' ' + $label + ']]**' + !else + !$rel = $rel + '**' + $label + '**' + !endif + !if ($techn != "") + ' line break is not deterministic, calculate it + !$rel = $rel + '\n//<size:' + $TECHN_FONT_SIZE + '>[' + $breakTechn($techn, $REL_TECHN_MAX_CHAR_WIDTH) + ']</size>//' + !endif + !if ($descr != "") + ' line break is not deterministic, calculate it + !$rel = $rel + '\n\n' + $breakDescr($descr, $REL_DESCR_MAX_CHAR_WIDTH) + !endif + !$prop = $getProps() + !if ($prop != "") + ' reuse table + !$rel = $rel + $prop + !endif + !return $rel +!endfunction + +!unquoted procedure Rel_($alias1, $alias2, $label, $direction) +$alias1 $direction $alias2 : **$label** +!endprocedure +!unquoted procedure Rel_($alias1, $alias2, $label, $techn, $direction) +$alias1 $direction $alias2 : **$label**\n//<size:$TECHN_FONT_SIZE>[$techn]</size>// +!endprocedure + +!unquoted procedure Rel($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel("-->>", $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure BiRel($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel("<<-->>", $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure Rel_Back($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel("<<--", $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure Rel_Neighbor($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel("->>", $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure BiRel_Neighbor($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel("<<->>", $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure Rel_Back_Neighbor($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel("<<-", $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure Rel_D($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($down("-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure +!unquoted procedure Rel_Down($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($down("-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure BiRel_D($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($down("<<-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure +!unquoted procedure BiRel_Down($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($down("<<-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure Rel_U($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($up("-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure +!unquoted procedure Rel_Up($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($up("-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure BiRel_U($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($up("<<-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure +!unquoted procedure BiRel_Up($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($up("<<-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure Rel_L($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($left("-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure +!unquoted procedure Rel_Left($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($left("-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure BiRel_L($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($left("<<-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure +!unquoted procedure BiRel_Left($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($left("<<-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure Rel_R($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($right("-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure +!unquoted procedure Rel_Right($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($right("-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +!unquoted procedure BiRel_R($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($right("<<-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure +!unquoted procedure BiRel_Right($from, $to, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +$getRel($right("<<-","->>"), $from, $to, $label, $techn, $descr, $sprite, $tags, $link) +!endprocedure + +' Layout Helpers +' ################################## + +!function $getHiddenLine($distance) + !return '-[hidden]' + %substr('------------', 0, %intval($distance) + 1) +!endfunction + +!unquoted procedure Lay_D($from, $to) +$from -[hidden]D- $to +!endprocedure +!unquoted procedure Lay_Down($from, $to) +$from -[hidden]D- $to +!endprocedure + +!unquoted procedure Lay_U($from, $to) +$from -[hidden]U- $to +!endprocedure +!unquoted procedure Lay_Up($from, $to) +$from -[hidden]U- $to +!endprocedure + +!unquoted procedure Lay_R($from, $to) +$from -[hidden]R- $to +!endprocedure +!unquoted procedure Lay_Right($from, $to) +$from -[hidden]R- $to +!endprocedure + +!unquoted procedure Lay_L($from, $to) +$from -[hidden]L- $to +!endprocedure +!unquoted procedure Lay_Left($from, $to) +$from -[hidden]L- $to +!endprocedure + +' PlantUML bug: lines which does "not match" with the orientation/direction of the diagram +' uses the same length therefore the method offers no direction at all. +' If a direction is required the Lay_...() methods can be used +!unquoted procedure Lay_Distance($from, $to, $distance="0") +$from $getHiddenLine($distance) $to +!endprocedure diff --git a/antora/components/docs/modules/resources/partials/C4_Container.puml b/antora/components/docs/modules/resources/partials/C4_Container.puml new file mode 100644 index 0000000000..3126fac943 --- /dev/null +++ b/antora/components/docs/modules/resources/partials/C4_Container.puml @@ -0,0 +1,111 @@ +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +' !if %variable_exists("RELATIVE_INCLUDE") +' !include %get_variable_value("RELATIVE_INCLUDE")/C4_Context.puml +' !else +' !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml +' !endif + +' Scope: A single software system. +' Primary elements: Containers within the software system in scope. +' Supporting elements: People and software systems directly connected to the containers. +' Intended audience: Technical people inside and outside of the software development team; including software architects, developers and operations/support staff. + +' Colors +' ################################## + +!global $CONTAINER_BG_COLOR = "#438DD5" +!global $CONTAINER_BORDER_COLOR = "#3C7FC0" +!global $EXTERNAL_CONTAINER_BG_COLOR = "#B3B3B3" +!global $EXTERNAL_CONTAINER_BORDER_COLOR = "#A6A6A6" + +' Styling +' ################################## +UpdateElementStyle("container", $CONTAINER_BG_COLOR, $ELEMENT_FONT_COLOR, $CONTAINER_BORDER_COLOR) +UpdateElementStyle("external_container", $EXTERNAL_CONTAINER_BG_COLOR, $ELEMENT_FONT_COLOR, $EXTERNAL_CONTAINER_BORDER_COLOR) + +' shortcuts with default colors +!unquoted procedure AddContainerTag($tagStereo, $bgColor=$CONTAINER_BG_COLOR, $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$CONTAINER_BORDER_COLOR, $shadowing="", $shape="", $sprite="", $techn="", $legendText="", $legendSprite="") + AddElementTag($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $techn, $legendText, $legendSprite) +!endprocedure +!unquoted procedure AddExternalContainerTag($tagStereo, $bgColor=$EXTERNAL_CONTAINER_BG_COLOR, $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$EXTERNAL_CONTAINER_BORDER_COLOR, $shadowing="", $shape="", $sprite="", $techn="", $legendText="", $legendSprite="") + AddElementTag($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $techn, $legendText, $legendSprite) +!endprocedure + +' Layout +' ################################## + +SetDefaultLegendEntries("person\nsystem\ncontainer\nexternal_person\nexternal_system\nexternal_container") + +!procedure LAYOUT_WITH_LEGEND() +hide stereotype +legend right +|<color:$LEGEND_TITLE_COLOR>**Legend**</color> | +|<$PERSON_BG_COLOR> person | +|<$SYSTEM_BG_COLOR> system | +|<$CONTAINER_BG_COLOR> container | +|<$EXTERNAL_PERSON_BG_COLOR> external person | +|<$EXTERNAL_SYSTEM_BG_COLOR> external system | +|<$EXTERNAL_CONTAINER_BG_COLOR> external container | +endlegend +!endprocedure + +' Elements +' ################################## + +!function $getContainer($label, $techn, $descr, $sprite) + !$container = "" + !if ($sprite != "") + !$container = $container + $getSprite($sprite) + '\n' + !endif + !$container = $container + '==' + $label + !if ($techn != "") + !$container = $container + '\n//<size:' + $TECHN_FONT_SIZE + '>[' + $techn + ']</size>//' + !endif + !if ($descr != "") + !$container = $container + '\n\n' + $descr + !endif + !return $container +!endfunction + +!unquoted procedure Container($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "container") +!$techn=$toElementArg($techn, $tags, "ElementTagTechn", "container") +rectangle "$getContainer($label, $techn, $descr, $sprite)$getProps()" $toStereos("container", $tags) as $alias $getLink($link) +!endprocedure + +!unquoted procedure ContainerDb($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "container") +!$techn=$toElementArg($techn, $tags, "ElementTagTechn", "container") +database "$getContainer($label, $techn, $descr, $sprite)$getProps()" $toStereos("container", $tags) as $alias $getLink($link) +!endprocedure + +!unquoted procedure ContainerQueue($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "container") +!$techn=$toElementArg($techn, $tags, "ElementTagTechn", "container") +queue "$getContainer($label, $techn, $descr, $sprite)$getProps()" $toStereos("container", $tags) as $alias $getLink($link) +!endprocedure + +!unquoted procedure Container_Ext($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "external_container") +!$techn=$toElementArg($techn, $tags, "ElementTagTechn", "external_container") +rectangle "$getContainer($label, $techn, $descr, $sprite)$getProps()" $toStereos("external_container", $tags) as $alias $getLink($link) +!endprocedure + +!unquoted procedure ContainerDb_Ext($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "external_container") +!$techn=$toElementArg($techn, $tags, "ElementTagTechn", "external_container") +database "$getContainer($label, $techn, $descr, $sprite)$getProps()" $toStereos("external_container", $tags) as $alias $getLink($link) +!endprocedure + +!unquoted procedure ContainerQueue_Ext($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "external_container") +!$techn=$toElementArg($techn, $tags, "ElementTagTechn", "external_container") +queue "$getContainer($label, $techn, $descr, $sprite)$getProps()" $toStereos("external_container", $tags) as $alias $getLink($link) +!endprocedure + +' Boundaries +' ################################## + +!unquoted procedure Container_Boundary($alias, $label, $tags="", $link="") +Boundary($alias, $label, "Container", $tags, $link) +!endprocedure diff --git a/antora/components/docs/modules/resources/partials/C4_Context.puml b/antora/components/docs/modules/resources/partials/C4_Context.puml new file mode 100644 index 0000000000..5d3513d3c2 --- /dev/null +++ b/antora/components/docs/modules/resources/partials/C4_Context.puml @@ -0,0 +1,292 @@ +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +' !if %variable_exists("RELATIVE_INCLUDE") +' !include %get_variable_value("RELATIVE_INCLUDE")/C4.puml +' !else +' !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4.puml +' !endif + +' Scope: A single software system. +' Primary elements: The software system in scope. +' Supporting elements: People and software systems directly connected to the software system in scope. +' Intended audience: Everybody, both technical and non-technical people, inside and outside of the software development team. + +' Colors +' ################################## + +!global $PERSON_BG_COLOR = "#08427B" +!global $PERSON_BORDER_COLOR = "#073B6F" +!global $EXTERNAL_PERSON_BG_COLOR = "#686868" +!global $EXTERNAL_PERSON_BORDER_COLOR = "#8A8A8A" +!global $SYSTEM_BG_COLOR = "#1168BD" +!global $SYSTEM_BORDER_COLOR = "#3C7FC0" +!global $EXTERNAL_SYSTEM_BG_COLOR = "#999999" +!global $EXTERNAL_SYSTEM_BORDER_COLOR = "#8A8A8A" + +' Styling +' ################################## + +UpdateElementStyle("person", $PERSON_BG_COLOR, $ELEMENT_FONT_COLOR, $PERSON_BORDER_COLOR) +UpdateElementStyle("external_person", $EXTERNAL_PERSON_BG_COLOR, $ELEMENT_FONT_COLOR, $EXTERNAL_PERSON_BORDER_COLOR) +UpdateElementStyle("system", $SYSTEM_BG_COLOR, $ELEMENT_FONT_COLOR, $SYSTEM_BORDER_COLOR) +UpdateElementStyle("external_system", $EXTERNAL_SYSTEM_BG_COLOR, $ELEMENT_FONT_COLOR, $EXTERNAL_SYSTEM_BORDER_COLOR) + +' shortcuts with default colors +!unquoted procedure AddPersonTag($tagStereo, $bgColor=$PERSON_BG_COLOR, $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$PERSON_BORDER_COLOR, $shadowing="", $shape="", $sprite="", $legendText="", $legendSprite="") + AddElementTag($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, "", $legendText, $legendSprite) +!endprocedure +!unquoted procedure AddExternalPersonTag($tagStereo, $bgColor=$EXTERNAL_PERSON_BG_COLOR, $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$EXTERNAL_PERSON_BORDER_COLOR, $shadowing="", $shape="", $sprite="", $legendText="", $legendSprite="") + AddElementTag($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, "", $legendText, $legendSprite) +!endprocedure +!unquoted procedure AddSystemTag($tagStereo, $bgColor=$SYSTEM_BG_COLOR, $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$SYSTEM_BORDER_COLOR, $shadowing="", $shape="", $sprite="", $legendText="", $legendSprite="") + AddElementTag($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, "", $legendText, $legendSprite) +!endprocedure +!unquoted procedure AddExternalSystemTag($tagStereo, $bgColor=$EXTERNAL_SYSTEM_BG_COLOR, $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$EXTERNAL_SYSTEM_BORDER_COLOR, $shadowing="", $shape="", $sprite="", $legendText="", $legendSprite="") + AddElementTag($tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, "", $legendText, $legendSprite) +!endprocedure + +' Sprites +' ################################## + +sprite $person [48x48/16] { +000000000000000000000000000000000000000000000000 +000000000000000000000000000000000000000000000000 +0000000000000000000049BCCA7200000000000000000000 +0000000000000000006EFFFFFFFFB3000000000000000000 +00000000000000001CFFFFFFFFFFFF700000000000000000 +0000000000000001EFFFFFFFFFFFFFF80000000000000000 +000000000000000CFFFFFFFFFFFFFFFF6000000000000000 +000000000000007FFFFFFFFFFFFFFFFFF100000000000000 +00000000000001FFFFFFFFFFFFFFFFFFF900000000000000 +00000000000006FFFFFFFFFFFFFFFFFFFF00000000000000 +0000000000000BFFFFFFFFFFFFFFFFFFFF40000000000000 +0000000000000EFFFFFFFFFFFFFFFFFFFF70000000000000 +0000000000000FFFFFFFFFFFFFFFFFFFFF80000000000000 +0000000000000FFFFFFFFFFFFFFFFFFFFF80000000000000 +0000000000000DFFFFFFFFFFFFFFFFFFFF60000000000000 +0000000000000AFFFFFFFFFFFFFFFFFFFF40000000000000 +00000000000006FFFFFFFFFFFFFFFFFFFE00000000000000 +00000000000000EFFFFFFFFFFFFFFFFFF800000000000000 +000000000000007FFFFFFFFFFFFFFFFFF100000000000000 +000000000000000BFFFFFFFFFFFFFFFF5000000000000000 +0000000000000001DFFFFFFFFFFFFFF70000000000000000 +00000000000000000BFFFFFFFFFFFF500000000000000000 +0000000000000000005DFFFFFFFFA1000000000000000000 +0000000000000000000037ABB96100000000000000000000 +000000000000000000000000000000000000000000000000 +000000000000000000000000000000000000000000000000 +000000000000025788300000000005886410000000000000 +000000000007DFFFFFFD9643347BFFFFFFFB400000000000 +0000000004EFFFFFFFFFFFFFFFFFFFFFFFFFFB1000000000 +000000007FFFFFFFFFFFFFFFFFFFFFFFFFFFFFD200000000 +00000006FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFE10000000 +0000003FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB0000000 +000000BFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5000000 +000003FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD000000 +000009FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF200000 +00000DFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF600000 +00000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF800000 +00001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA00000 +00001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB00000 +00001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB00000 +00001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB00000 +00001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA00000 +00000EFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF700000 +000006FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFE100000 +0000008FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD3000000 +000000014555555555555555555555555555555300000000 +000000000000000000000000000000000000000000000000 +000000000000000000000000000000000000000000000000 +} + +sprite $person2 [48x48/16] { +0000000000000000000049BCCA7200000000000000000000 +0000000000000000006EFFFFFFFFB3000000000000000000 +00000000000000001CFFFFFFFFFFFF700000000000000000 +0000000000000001EFFFFFFFFFFFFFF80000000000000000 +000000000000000CFFFFFFFFFFFFFFFF6000000000000000 +000000000000007FFFFFFFFFFFFFFFFFF100000000000000 +00000000000001FFFFFFFFFFFFFFFFFFF900000000000000 +00000000000006FFFFFFFFFFFFFFFFFFFF00000000000000 +0000000000000BFFFFFFFFFFFFFFFFFFFF40000000000000 +0000000000000EFFFFFFFFFFFFFFFFFFFF70000000000000 +0000000000000FFFFFFFFFFFFFFFFFFFFF80000000000000 +0000000000000FFFFFFFFFFFFFFFFFFFFF80000000000000 +0000000000000DFFFFFFFFFFFFFFFFFFFF60000000000000 +0000000000000AFFFFFFFFFFFFFFFFFFFF40000000000000 +00000000000006FFFFFFFFFFFFFFFFFFFE00000000000000 +00000000000000EFFFFFFFFFFFFFFFFFF800000000000000 +000000000000007FFFFFFFFFFFFFFFFFF100000000000000 +000000000000000BFFFFFFFFFFFFFFFF5000000000000000 +0000000000000001DFFFFFFFFFFFFFF70000000000000000 +00000000000000000BFFFFFFFFFFFF500000000000000000 +0000000000000000005DFFFFFFFFA1000000000000000000 +0000000000000000000037ABB96100000000000000000000 +000000000002578888300000000005888864100000000000 +0000000007DFFFFFFFFD9643347BFFFFFFFFFB4000000000 +00000004EFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB10000000 +0000007FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD2000000 +000006FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFE100000 +00003FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB00000 +0000BFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF50000 +0003FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD0000 +0009FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF2000 +000DFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF6000 +000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF8000 +001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB000 +001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB000 +001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFB000 +001FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFA000 +000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF8000 +000DFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF6000 +0009FFFFFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFFFFF2000 +0003FFFFFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFFFFD0000 +0000BFFFFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFFFF50000 +00003FFFFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFFFB00000 +000006FFFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFFE100000 +0000007FFFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFFD2000000 +00000004EFFF8FFFFFFFFFFFFFFFFFFFFFF8FFFB10000000 +0000000007DF8FFFFFFFFFFFFFFFFFFFFFF8FB4000000000 +000000000002578888888888888888888864100000000000 +} + +' Layout +' ################################## + +SetDefaultLegendEntries("person\nsystem\nexternal_person\nexternal_system") + +!procedure LAYOUT_WITH_LEGEND() +hide stereotype +legend right +|<color:$LEGEND_TITLE_COLOR>**Legend**</color> | +|<$PERSON_BG_COLOR> person | +|<$SYSTEM_BG_COLOR> system| +|<$EXTERNAL_PERSON_BG_COLOR> external person | +|<$EXTERNAL_SYSTEM_BG_COLOR> external system | +endlegend +!endprocedure + +!global $defaultPersonSprite = "person" +!global $portraitPerson = "false" + +!procedure HIDE_PERSON_SPRITE() + !$defaultPersonSprite = "" + !$portraitPerson = "false" +!endprocedure + +!unquoted procedure SHOW_PERSON_SPRITE($sprite="") + !if ($sprite == "") + !$defaultPersonSprite = "person" + !else + !$defaultPersonSprite = $sprite + !endif + !$portraitPerson = "false" +!endprocedure + +!unquoted procedure SHOW_PERSON_PORTRAIT() + !$defaultPersonSprite = "" + !$portraitPerson = "portrait" +!endprocedure + +!unquoted procedure SHOW_PERSON_OUTLINE() + !$defaultPersonSprite = "" + !$portraitPerson = "outline" +!endprocedure + +' Elements +' ################################## + +!function $getPerson($label, $descr, $sprite) +!if ($sprite == "") && ($defaultPersonSprite != "") + !$sprite = $defaultPersonSprite +!endif +!if ($descr == "") && ($sprite == "") + !return '=='+$label +!endif +!if ($descr == "") && ($sprite != "") + !return $getSprite($sprite)+'\n=='+$label +!endif +!if ($descr != "") && ($sprite == "") + !return '=='+$label+'\n\n '+$descr +!endif +!if ($descr != "") && ($sprite != "") + !return $getSprite($sprite)+'\n=='+$label+'\n\n '+$descr +!endif +!endfunction + +!function $getSystem($label, $descr, $sprite) +!if ($descr == "") && ($sprite == "") +!return '=='+$label +!endif +!if ($descr == "") && ($sprite != "") +!return $getSprite($sprite)+'\n=='+$label +!endif +!if ($descr != "") && ($sprite == "") +!return '=='+$label+'\n\n '+$descr +!endif +!if ($descr != "") && ($sprite != "") +!return $getSprite($sprite)+'\n=='+$label+'\n\n '+$descr +!endif +!endfunction + +!unquoted procedure Person($alias, $label, $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "person") +!if ($portraitPerson == "portrait") && ($sprite == "") +actor "$getPerson($label, $descr, $sprite)$getProps()" $toStereos("person", $tags) as $alias $getLink($link) +!elseif ($portraitPerson == "outline") && ($sprite == "") +person "$getPerson($label, $descr, $sprite)$getProps()" $toStereos("person", $tags) as $alias $getLink($link) +!else +rectangle "$getPerson($label, $descr, $sprite)$getProps()" $toStereos("person", $tags) as $alias $getLink($link) +!endif +!endprocedure + +!unquoted procedure Person_Ext($alias, $label, $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "external_person") +!if ($portraitPerson == "portrait") && ($sprite == "") +actor "$getPerson($label, $descr, $sprite)$getProps()" $toStereos("external_person", $tags) as $alias $getLink($link) +!elseif ($portraitPerson == "outline") && ($sprite == "") +person "$getPerson($label, $descr, $sprite)$getProps()" $toStereos("external_person", $tags) as $alias $getLink($link) +!else +rectangle "$getPerson($label, $descr, $sprite)$getProps()" $toStereos("external_person", $tags) as $alias $getLink($link) +!endif +!endprocedure + +!unquoted procedure System($alias, $label, $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "system") +rectangle "$getSystem($label, $descr, $sprite)$getProps()" $toStereos("system", $tags) as $alias $getLink($link) +!endprocedure + +!unquoted procedure System_Ext($alias, $label, $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "external_system") +rectangle "$getSystem($label, $descr, $sprite)$getProps()" $toStereos("external_system", $tags) as $alias $getLink($link) +!endprocedure + +!unquoted procedure SystemDb($alias, $label, $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "system") +database "$getSystem($label, $descr, $sprite)$getProps()" $toStereos("system", $tags) as $alias $getLink($link) +!endprocedure + +!unquoted procedure SystemQueue($alias, $label, $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "system") +queue "$getSystem($label, $descr, $sprite)$getProps()" $toStereos("system", $tags) as $alias $getLink($link) +!endprocedure + +!unquoted procedure SystemDb_Ext($alias, $label, $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "external_system") +database "$getSystem($label, $descr, $sprite)$getProps()" $toStereos("external_system", $tags) as $alias $getLink($link) +!endprocedure + +!unquoted procedure SystemQueue_Ext($alias, $label, $descr="", $sprite="", $tags="", $link="") +!$sprite=$toElementArg($sprite, $tags, "ElementTagSprite", "external_system") +queue "$getSystem($label, $descr, $sprite)$getProps()" $toStereos("external_system", $tags) as $alias $getLink($link) +!endprocedure + +' Boundaries +' ################################## + +!unquoted procedure Enterprise_Boundary($alias, $label, $tags="", $link="") +Boundary($alias, $label, "Enterprise", $tags, $link) +!endprocedure + +!unquoted procedure System_Boundary($alias, $label, $tags="", $link="") +Boundary($alias, $label, "System", $tags, $link) +!endprocedure diff --git a/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M3/relnotes.adoc b/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M3/relnotes.adoc index 8492ffb095..2dd4a0f542 100644 --- a/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M3/relnotes.adoc +++ b/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M3/relnotes.adoc @@ -21,7 +21,7 @@ This milestone also introduces a number of new features: * security integration with xref:security:keycloak:about.adoc[Keycloak] * New value types: -** text-based value type with simple xref:valuetypes:sse:about.adoc[SSE support] +** text-based value type with simple xref:vw:sse:about.adoc[SSE support] ** xref:valuetypes:asciidoc:about.adoc[Asciidoc] value type ** xref:valuetypes:markdown:about.adoc[Markdown] value type diff --git a/antora/playbooks/site-core.yml b/antora/playbooks/site-core.yml index 95493944c9..e3421d9954 100644 --- a/antora/playbooks/site-core.yml +++ b/antora/playbooks/site-core.yml @@ -63,9 +63,6 @@ content: - url: . start_path: examples/demo/domain/src/main/adoc # docs branches: HEAD - - url: . - start_path: regressiontests/adoc # core - branches: HEAD # mavendeps - url: . diff --git a/antora/playbooks/site-core.yml b/antora/playbooks/site-regressiontests.yml similarity index 70% copy from antora/playbooks/site-core.yml copy to antora/playbooks/site-regressiontests.yml index 95493944c9..535ee5d70a 100644 --- a/antora/playbooks/site-core.yml +++ b/antora/playbooks/site-regressiontests.yml @@ -27,57 +27,29 @@ content: - url: . start_path: antora/components/docs # docs branches: HEAD -# core - - url: . - start_path: core/adoc # core (design docs) - branches: HEAD - - url: . - start_path: core/codegen-bytebuddy/src/main/adoc # core - branches: HEAD - - url: . - start_path: commons/src/main/adoc # core - branches: HEAD - - url: . - start_path: core/interaction/src/main/adoc # core - branches: HEAD - - url: . - start_path: core/internaltestsupport/src/main/adoc # core - branches: HEAD - - url: . - start_path: core/metamodel/src/main/adoc # core - branches: HEAD - - url: . - start_path: core/runtime/src/main/adoc # core - branches: HEAD - - url: . - start_path: core/runtimeservices/src/main/adoc # core - branches: HEAD - - url: . - start_path: core/transaction/src/main/adoc # core - branches: HEAD - - url: . - start_path: core/webapp/src/main/adoc # core - branches: HEAD # examples - url: . start_path: examples/demo/domain/src/main/adoc # docs branches: HEAD - - url: . - start_path: regressiontests/adoc # core - branches: HEAD # mavendeps - url: . start_path: mavendeps/adoc # docs branches: HEAD +# regression tests + - url: . + start_path: regressiontests/adoc # regressiontests + branches: HEAD + # starters - url: . start_path: starters/adoc # docs branches: HEAD + ui: bundle: url: ../isis-antora/build/ui-bundle.zip diff --git a/antora/playbooks/site.yml b/antora/playbooks/site.yml index 12743c3ce5..cd0da7c93e 100644 --- a/antora/playbooks/site.yml +++ b/antora/playbooks/site.yml @@ -99,16 +99,12 @@ content: - url: . start_path: antora/components/tutorials # tutorials branches: HEAD - - url: . - start_path: regressiontests/adoc # core - branches: HEAD # extensions - url: . start_path: extensions/adoc # extensions branches: HEAD - - url: . start_path: extensions/core/commandlog/adoc # userguide branches: HEAD @@ -200,6 +196,11 @@ content: start_path: persistence/jdo/adoc # pjdo branches: HEAD +# regression tests + - url: . + start_path: regressiontests/adoc # regressiontests + branches: HEAD + # security - url: . start_path: security/adoc # security diff --git a/antora/supplemental-ui/index.html b/antora/supplemental-ui/index.html index 8eb2ffcfd6..cb6e981eae 100644 --- a/antora/supplemental-ui/index.html +++ b/antora/supplemental-ui/index.html @@ -882,7 +882,7 @@ mvn -pl webapp jetty:run</pre> <div class="col-md-8"> <div class="copyright"> - Copyright © 2010~2021 The Apache Software Foundation, licensed under the Apache License, v2.0. + Copyright © 2010~2022 The Apache Software Foundation, licensed under the Apache License, v2.0. Apache, the Apache feather logo, Apache Isis™, and the Apache Isis project logo are all trademarks of The Apache Software Foundation. </div> </div> diff --git a/core/adoc/modules/archdesign/pages/about.adoc b/core/adoc/modules/ROOT/pages/_todo.adoc similarity index 80% rename from core/adoc/modules/archdesign/pages/about.adoc rename to core/adoc/modules/ROOT/pages/_todo.adoc index 01730eb422..5067c5c34b 100644 --- a/core/adoc/modules/archdesign/pages/about.adoc +++ b/core/adoc/modules/ROOT/pages/_todo.adoc @@ -1,22 +1,12 @@ -= Architecture & Design += TODO :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] -This guide describes the internal architecture and design of the framework. +TODO: discuss some of these topics: -[CAUTION] -==== -This material is out-of-date. -==== - - -to discuss: - -* our plugin architecture (using ServiceLoader) * webmodule architecture (programmatic web.xml) * use of Spring Boot & our modules for classpath scanning * configuration * extensions * log4j2 -* plugins diff --git a/core/adoc/modules/ROOT/pages/about.adoc b/core/adoc/modules/ROOT/pages/about.adoc index e6c0129bd7..2596c084c5 100644 --- a/core/adoc/modules/ROOT/pages/about.adoc +++ b/core/adoc/modules/ROOT/pages/about.adoc @@ -1,14 +1,72 @@ -= Core Framework += Internal Design Docs :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] :page-partial: -This section documents the design and implementation of the core framework. +This section documents the internal design and implementation of the core framework. +It will primarily be of interest to committers and contributors to the framework. -We also include some design documentation - where it provides useful context - in the end-user documentation set: +We also include some design documentation - where it provides useful context - in the end-user documentation set (the xref:userguide:ROOT:about.adoc[user guide], xref:refguide:ROOT:about.adoc[reference guide], xref:security:ROOT:about.adoc[security guide] and xref:testing:ROOT:about.adoc[testing guide]). -* xref:userguide:ROOT:about.adoc[user guide] -* xref:refguide:ROOT:about.adoc[reference guide] -* xref:security:ROOT:about.adoc[security guide] -* xref:testing:ROOT:about.adoc[testing guide]. +== Modules + +There is a section for most of the `core` modules: + +* xref:core:codegen-bytebuddy:about.adoc[] - utliity service to create dynamic proxy objects + +* xref:core:commons:about.adoc[] - an extensive library of common utilities (though not intended as an end-user API) ++ +Note that this module does not reside in `core/` directory, instead it is to be found in `../commons` directory instead + +* xref:core:interaction:about.adoc[] - declares the `@InteractionScope` to Spring. +Also defines the internal data structures that keep track of the action invocations and property edits performed within the interaction. ++ +An "interaction" is normally the same duration as a web request, whereby a short-lived persistence session is created using a connection from a database connection pool. + +* xref:core:internaltestsupport:about.adoc[] - utility classes for unit testing the framework's own classes. + +* xref:core:metamodel:about.adoc[] - classes that are used to build the internal metamodel by introspecting the domain classes. ++ +Many of the services defined (as interfaces) in the applib have implementations defined in this module (the rest are defined in xref:core:runtimeservices:about.adoc[], below). ++ +The documentation in this module explains (with diagrams) the concepts at both a high and more detailed level. ++ +As you might have guessed, this is the largest module within the framework. + +* xref:core:runtime:about.adoc[] - a very small module providing a set of classes to handle the runtime context. +It also has classes that trigger events for when the metamodel is fully built (after bootstrapping), and to emit events for transaction boundaries. + +* xref:core:runtimeservices:about.adoc[] - provides an extensive set of domain services. ++ +Many of the services defined (as interfaces) in the applib are actually implemented in this module (the rest are defined in xref:core:metamodel:about.adoc[], above). + +* xref:core:transaction:about.adoc[] - a small module providing a set of classes primarily concerned with for tracking changes to entities during transactions. + +* xref:core:webapp:about.adoc[] - classes used to bootstrap the app itself, also providing hooks for other components to contribute their own +filters and servlets into the web request pipeline. + + +As a simplification, the xref:core:metamodel:about.adoc[] module handles domain types (cf `java.lang.Class`) while the xref:core:runtime:about.adoc[] and xref:core:runtimeservices:about.adoc[] modules handle domain object instances (cf `java.lang.Object`). +That said, Spring Boot is responsible for instantiating domain service instances, while the persistence mechanisms (xref:pjpa:ROOT:about.adoc[JPA] and xref:pjdo:ROOT:about.adoc[JDO]) -- which are not part of the `core` modules -- handle the lifecycle of entity instances. + + +There are also two `core` modules not listed above, because their documentation are both part of the end-user docs: + +* the docs for the `core/config` module consistitute the xref:refguide:config:about.adoc[] +* the docs for the `core/security` module consistitute the xref:security:ROOT:about.adoc[Security Guide] + + +== Generated Index + +This is probably a good place as any to mention that the documentation/website procedures include tooling to automatically create Asciidoc reference documentation for _any_ Java class in the codebase. + +This is used extensively for the classes in the applib; these can be referenced using the form `\xref:refguide:applib:index/xxx.adoc[]`. + +* For example `\xref:refguide:applib:index/annotation/DomainObject.adoc[]` resolves to xref:refguide:applib:index/annotation/DomainObject.adoc[]. + +But the index is also available for internal classes, such as those in core/security, which can be found under `\xref:refguide:core:index/security/xxx.adoc[]` + +* For example, `\xref:refguide:core:index/security/authentication/Authenticator.adoc[]` resolves to xref:refguide:core:index/security/authentication/Authenticator.adoc[]. + +Not every class is generated into the index, but all that is required is to include `{@index}` in the class-level javadoc. diff --git a/core/adoc/modules/ROOT/partials/component-nav.adoc b/core/adoc/modules/ROOT/partials/component-nav.adoc index 9e671bc5cc..3e1e24c4b4 100644 --- a/core/adoc/modules/ROOT/partials/component-nav.adoc +++ b/core/adoc/modules/ROOT/partials/component-nav.adoc @@ -1,10 +1,12 @@ include::core:ROOT:partial$module-nav.adoc[] -include::core:archdesign:partial$module-nav.adoc[] include::core:commons:partial$module-nav.adoc[] include::core:codegen-bytebuddy:partial$module-nav.adoc[] +include::core:interaction:partial$module-nav.adoc[] +include::core:internaltestsupport:partial$module-nav.adoc[] include::core:metamodel:partial$module-nav.adoc[] include::core:runtime:partial$module-nav.adoc[] include::core:runtimeservices:partial$module-nav.adoc[] +include::core:transaction:partial$module-nav.adoc[] include::core:webapp:partial$module-nav.adoc[] include::core:regressiontests:partial$module-nav.adoc[] diff --git a/core/adoc/modules/ROOT/partials/module-nav.adoc b/core/adoc/modules/ROOT/partials/module-nav.adoc index 139597f9cb..ad29d84a83 100644 --- a/core/adoc/modules/ROOT/partials/module-nav.adoc +++ b/core/adoc/modules/ROOT/partials/module-nav.adoc @@ -1,2 +1,5 @@ +* xref:core:ROOT:about.adoc[Overview] +** xref:core:_overview:about.adoc[Maven modules] +//** xref:core:ROOT:_todo.adoc[] diff --git a/core/adoc/modules/archdesign/attachments/modules-dependencies.pptx b/core/adoc/modules/archdesign/attachments/modules-dependencies.pptx deleted file mode 100644 index 02ad2625f0..0000000000 Binary files a/core/adoc/modules/archdesign/attachments/modules-dependencies.pptx and /dev/null differ diff --git a/core/adoc/modules/archdesign/images/modules-dependencies.png b/core/adoc/modules/archdesign/images/modules-dependencies.png deleted file mode 100644 index baa01c434d..0000000000 Binary files a/core/adoc/modules/archdesign/images/modules-dependencies.png and /dev/null differ diff --git a/core/adoc/modules/archdesign/nav.adoc b/core/adoc/modules/archdesign/nav.adoc deleted file mode 100644 index 798e16ada2..0000000000 --- a/core/adoc/modules/archdesign/nav.adoc +++ /dev/null @@ -1,4 +0,0 @@ - -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] - -include::core:ROOT:partial$component-nav.adoc[] diff --git a/core/adoc/modules/archdesign/partials/module-nav.adoc b/core/adoc/modules/archdesign/partials/module-nav.adoc deleted file mode 100644 index 9045967ad2..0000000000 --- a/core/adoc/modules/archdesign/partials/module-nav.adoc +++ /dev/null @@ -1,3 +0,0 @@ -* xref:core:archdesign:about.adoc[Architecture & Design] - - diff --git a/core/codegen-bytebuddy/src/main/adoc/modules/codegen-bytebuddy/pages/about.adoc b/core/codegen-bytebuddy/src/main/adoc/modules/codegen-bytebuddy/pages/about.adoc index 23feb893c5..39dae43093 100644 --- a/core/codegen-bytebuddy/src/main/adoc/modules/codegen-bytebuddy/pages/about.adoc +++ b/core/codegen-bytebuddy/src/main/adoc/modules/codegen-bytebuddy/pages/about.adoc @@ -1,6 +1,9 @@ -= Byte Buddy Proxy Factory += CodeGen (Proxy Factory) using Byte Buddy :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] -WARNING: TODO +This module provides an implementation of the internal `_ProxyFactoryService` domain service, used to synthesise object proxies dynamically. +Under the covers the link:https://bytebuddy.net/#/[Byte Buddy] library is used. + +The main user of this functionality is the xref:refguide:applib:index/services/wrapper/WrapperFactory.adoc[] domain service, which creates a proxy in order to intercept calls to a wrapped domain object. diff --git a/core/codegen-bytebuddy/src/main/adoc/modules/codegen-bytebuddy/partials/module-nav.adoc b/core/codegen-bytebuddy/src/main/adoc/modules/codegen-bytebuddy/partials/module-nav.adoc index f40c0894a7..efc40e6ebb 100644 --- a/core/codegen-bytebuddy/src/main/adoc/modules/codegen-bytebuddy/partials/module-nav.adoc +++ b/core/codegen-bytebuddy/src/main/adoc/modules/codegen-bytebuddy/partials/module-nav.adoc @@ -1,4 +1,4 @@ -* xref:core:codegen-bytebuddy:about.adoc[Byte Buddy Proxy Factory] +* xref:core:codegen-bytebuddy:about.adoc[Code Gen] (Proxy Factory) diff --git a/core/interaction/src/main/adoc/modules/interaction/pages/about.adoc b/core/interaction/src/main/adoc/modules/interaction/pages/about.adoc index a0a0249169..8a438833c4 100644 --- a/core/interaction/src/main/adoc/modules/interaction/pages/about.adoc +++ b/core/interaction/src/main/adoc/modules/interaction/pages/about.adoc @@ -2,4 +2,9 @@ :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] -WARNING: TODO +An "interaction" is normally the same duration as a web request, whereby a short-lived persistence session is created using a connection from a database connection pool. + +This module provides the classes that define the support for xref:refguide:applib:index/annotation/InteractionScope.adoc[] to Spring. + +This module also defines the internal data structures that keep track of the action invocations and property edits performed within the interaction. + diff --git a/core/internaltestsupport/src/main/adoc/modules/internaltestsupport/pages/about.adoc b/core/internaltestsupport/src/main/adoc/modules/internaltestsupport/pages/about.adoc index b1f23d2877..305c4270cd 100644 --- a/core/internaltestsupport/src/main/adoc/modules/internaltestsupport/pages/about.adoc +++ b/core/internaltestsupport/src/main/adoc/modules/internaltestsupport/pages/about.adoc @@ -2,4 +2,4 @@ :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] -WARNING: TODO +This module provides a number of utility classes to help with unit testing framework's own classes. diff --git a/core/metamodel/src/main/adoc/modules/metamodel/pages/about.adoc b/core/metamodel/src/main/adoc/modules/metamodel/pages/about.adoc index 9af05c8412..746011899d 100644 --- a/core/metamodel/src/main/adoc/modules/metamodel/pages/about.adoc +++ b/core/metamodel/src/main/adoc/modules/metamodel/pages/about.adoc @@ -2,6 +2,293 @@ :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] +This module contains the classes that are used to build the internal metamodel by introspecting the domain classes. -WARNING: TODO +Many of the services defined (as interfaces) in the applib have implementations defined in this module (the rest are defined in xref:core:runtimeservices:about.adoc[]). +== What makes up the metamodel + +The classes in this module are used to build up the metamodel from a variety of inputs sources: + +[plantuml,file="metamodel.png"] +.metamodel inputs +---- +@startuml +!include <logos/java> +!include <tupadr3/font-awesome/at> +!include <tupadr3/font-awesome/envira> +!include <office/Databases/database_cube> +!include <material/xml.puml> + +legend top +|= notation |= explanation | +| ""__underline__"" | DDD Pattern| +endlegend + +together { + rectangle "<$database_cube><$at>\n<<Annotation>>\nORM (JPA/JDO)" as PERS + rectangle "<$envira><$at>\n<<Annotation>>\nSpring" as SPRING + rectangle "<img:https://isis.apache.org/_/img/home/isis-logo-56x64.png><$at>\n<<Annotation>>\nApache Isis" as FW + rectangle "<img:https://isis.apache.org/_/img/home/isis-logo-56x64.png><$java>\n<<Supporting Methods>>\nApache Isis" as SM + rectangle "<$java><$ma_xml><$at>\n<<Annotation>>\nJAXB" as JAXB + + SPRING -[hidden]- PERS + PERS -[hidden]- FW + FW -[hidden]- SM + SM -[hidden]- JAXB + + note left of SPRING + * __Repository__ + * Name (@Named) + * Service (via FW @DomainService) + * Component (via FW @DomainObject) + end note + + note left of PERS + * Cardinality + * TableName + * Column + ** Name + ** Length + ** Type + end note + + note left of FW + * __Entitiy__ + ** Property + ** Collection + ** Action + * __Factory__ + * Layout + ** Property Sequence + (Table and Forms) + ** Action Sequence (Menu) + ** Styles (cssClass) + * ViewModel + * Mixin + end note + + note left of SM + * autoComplete…() + * choices…() + * default…() + * disable…() + * get…() + * hide…() + * iconName() + * set…() + * title() + * validate…() + end note + + note left of JAXB + * @XmlAccessorType + * @XmlJavaTypeAdapter + * @XmlRootElement + end note +} + +rectangle "<img:https://isis.apache.org/_/img/home/isis-logo-56x64.png>\nMetaModel" as MM + +SPRING -> MM +PERS -> MM +FW -> MM +SM -> MM +JAXB -> MM + +(MetaModelValidation) as MMV +MM <- MMV : perform \n consistency \n check + +rectangle "WicketViewer" as UI +database DB +interface "Restful\nObjects" as REST +MM -d-> UI : generate +MM -d-> DB : generate +MM -d-> REST : generate + +@enduml +---- +//note left of UI +//File | Edit | Help +//end note + + +== Metamodel Concepts + +The metamodel itself consists of the following parts: + +[plantuml,file="metamodel_concepts.png"] +.Metamodel Terminology +---- +@startuml + +skinparam nodesep 20 +skinparam ranksep 1 + +together { + (Domain\nObject) as DO + (Entity) as E + (View\nModel) as VM +} +(<i>Apache Isis</i>) as FW +(Persistence\nLayer) as PL +together { + (Mixin) as M + (Mixee) as ME +} +(Service) as S +(Domain\nService) as DS +(<i>Spring</i>) as SPRING +together { + (Member) as MB + (Property) as P + (Collection) as C + (Action) as A +} + +DO <-d-"is a" VM +DO <-d-"is a" E +FW .u.> VM : manages +PL .u.> E : manages + +P "is a"-u-> MB +C "is a"-u-> MB +A "is a"-u-> MB + +DO --> MB : has 1..* + +M "contributes\n a"..> MB +M "contributes\n to"-> ME +DO -> ME : can \n act \n as + +SPRING ..> S : manages +DS "is a"-u-> S +DS --> A : has 1..* +@enduml +---- + +Thus: + +* _Domain Objects_ have *_Properties_*, *_Collections_* + +* *_Viewmodels_* and *_Entities_* are specializations of *_Domain Objects_*. + +** _View Models_ are (lifecycle-) managed by _Apache Isis_ +** _Entities_ are managed by the configured persistence layer +(either JDO or JPA). + +* *_Services_* in general are (lifecycle-) managed by _Spring_. ++ +Some _Services_ are also *_included_* in the metamodel; we call these *_Domain Services_* (annotated with xref:refguide:applib:index/annotation/DomainService.adoc[]). +Their _Actions_ (like _Domain Objects_') will be visible either _Menu Actions_ in the xref:vw:ROOT:about.adoc[Wicket UI] and/or through the xref:vro:ROOT:about.adoc[REST API]. + +* *_Mixins_* _contribute_ either a _Property_, a _Collection_ +or an _Action_ to their *_Mixee_* (-type). + + +[#class-diagram] +== Class Diagram + +The diagram below shows a simplified version of Apache Isis' internal metamodel. + + +[plantuml] +---- +include::docs:resources:partial$plantuml-stereotypes.puml[] + +package metamodel { + + class Object\nSpecId<<value>> { + +type + } + + class Object\nSpecification<<desc>> { + +objectSpecId + .... + -fullyQualifiedClassName + } + + class Object\nMember<<desc>> { + + } + + class Object\nAction<<desc>> { + + } + + class Object\nAssociation<<desc>> { + + } + + class OneToOne\nAssociation<<desc>> { + + } + + class OneToMany\nAssociation<<desc>> { + + } + + interface FacetHolder<<desc>> { + } + + class Object\nActionParameter<<desc>> { + } + + class OneToOne\nActionParameter<<desc>> { + } + + interface Facet<<desc>> { + } + + class OneToMany\nActionParameter<<desc>> { + } +} + +package runtime { + class Object\nAdapter<<ppt>> { + +getSpecification() + } + class Oid<<value>> { + + } +} + + + +Object\nSpecification -up-> Object\nSpecId +Object\nSpecification -down-> "*" Object\nMember +Object\nMember ^-down- Object\nAssociation +Object\nMember ^-down- Object\nAction +Object\nAssociation ^-down- OneToOne\nAssociation +Object\nAssociation ^-down- OneToMany\nAssociation +Object\nActionParameter ^-down- OneToOne\nActionParameter +Object\nActionParameter ^-down- OneToMany\nActionParameter +Object\nAction -left-> "*" Object\nActionParameter + +FacetHolder ^-.left- Object\nSpecification +FacetHolder ^-.down- Object\nMember +FacetHolder ^-.down- Object\nActionParameter +FacetHolder -right-> "*" Facet + + +Object\nAdapter -up-> Oid + +Oid -right-> Object\nSpecId + +---- + +where in the `metamodel` package: + +`ObjectSpecification`:: is equivalent to `java.lang.Class` +`ObjectSpecId`:: is a value object equivalent to the `@DomainObject#logicalTypeName` or `@DomainService#logicalTypeName` attribute +`OneToOneAssociation`:: represents a scalar property +`OneToManyAssociation`:: represents a collection +`ObjectAction`:: represents an action (with multiple parameters, either scalar or list) + +and in the `runtime` package: + +`Oid`:: is equivalent to the applib `Bookmark` ++ +and appears in URLs in the Wicket and Restful Objects viewers + +`ObjectAdapter`:: is equivalent to `java.lang.Object` diff --git a/core/metamodel/src/main/adoc/modules/metamodel/pages/class-diagram.adoc b/core/metamodel/src/main/adoc/modules/metamodel/pages/class-diagram.adoc index ecf7d55628..66c67cf53e 100644 --- a/core/metamodel/src/main/adoc/modules/metamodel/pages/class-diagram.adoc +++ b/core/metamodel/src/main/adoc/modules/metamodel/pages/class-diagram.adoc @@ -1,10 +1,8 @@ -[#class-diagram] = Class Diagram :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] - The diagram below shows a simplified version of Apache Isis' internal metamodel. diff --git a/core/metamodel/src/main/adoc/modules/metamodel/pages/events.adoc b/core/metamodel/src/main/adoc/modules/metamodel/pages/events.adoc new file mode 100644 index 0000000000..141fcd58c0 --- /dev/null +++ b/core/metamodel/src/main/adoc/modules/metamodel/pages/events.adoc @@ -0,0 +1,197 @@ += Events + +:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] + +The framework emits events when it interacts with domain objects; the domain application can listen to these events and use them to influence the interaction (including veto'ing it). + +These events fall into three broad categories: UI hints, domain and persistence lifecycles. + + +== UI Events + +As specified using xref:refguide:applib:index/annotation/DomainObjectLayout.adoc[@DomainObjectLayout#xxxUiEvent()]. + +.UI Events +[plantuml,file="eventbus_ui.png"] +---- +@startuml + +skinparam nodesep 20 + +(Event\nBus) as EB +(Spring) as SPRING +SPRING .l.> EB : provides/\nmanages +(Event\nListener) as EL +EL --> EB : listens to \n (is subscribed to) + +(UI\nEvent) as UIE +UIE -r-> EB : is \n published \n to + +(Title\nUIEvent) as TUIE +TUIE -u-> UIE : is a +(Icon\nUIEvent) as IUIE +IUIE -u-> UIE : is a + +(CssClass\nUIEvent) as CCUIE +CCUIE -u-> UIE : is a +(Layout\nUIEvent) as LUIE +LUIE -u-> UIE : is a + + +(Domain\nObject) as DO +DO "when \n rendered, \n leads to \n emission \nof"-d-> UIE + +(Presentation) as PST +DO -u-> PST : has +EL -u-> PST : can modify +note right of EL +When DomainObject implements +respective supporting methods itself ( +* title(), +* iconName(), +* cssClass(), +* layout()), +modification is not possible. +end note + +@enduml +---- + +//DE -d-> MB : can be \n declared \n for +// +//EL -u-> MB : can modify/check: \nvisibility (hide), \nusability (disable), \nvalidity (validate) +// +//DO ->"title \n icon \n cssClass \n layout" PST +//(UI\nEvent) as UIE +//EL --> PST : modify +//UIE --> EL : receive + + +== Domain Events + +As specified using xref:refguide:applib:index/annotation/Action.adoc[@Action#domainEvent()], xref:refguide:applib:index/annotation/Property.adoc[@Property#domainEvent()] and xref:refguide:applib:index/annotation/Collection.adoc[@Collection#domainEvent()]: + +.Domain Events +[plantuml,file="eventbus_domain.png"] +---- +@startuml + +skinparam nodesep 20 + +together { + (Domain\nService) as DS + (Domain\nObject) as DO + (<i>Domain\n<i>Event) as DE +} +(<i>Member</i>) as MB +together { + (Property) as P + (Action) as A + (Collection) as C +} +P -u-> MB : is a +A -u-> MB : is a +C -u-> MB : is a + +DO -d-> MB : has +DS -d--> A : has + +DE -d-> MB : can be \n declared \n for + +(Execution) as EX +P "edit \n is an"--> EX +A "invocation \n is an"--> EX + +(Event\nBus) as EB +(Spring) as SPRING +SPRING .l.> EB : provides/\nmanages +EX -> EB : is published as: \n * before event (phase: EXECUTING)\n * after event (phase: EXECUTED) + +(Event\nListener) as EL +EL --> EB : listens \n on +EL -u-> MB : can check/modify: \nvisibility (hide), \nusability (disable), \nvalidity (validate) + +note right of DE +Phases are: +* HIDING +* DISABLING +* VALIDATING +* EXECUTING +* EXECUTED +The framework automatically sends out +events with the phases in the order listed. +end note + +note right of MB +<i>DomainEvent</i> is declared as an +annotation type element in a member annotation, e.g. +<b>@Action( + <b>domainEvent=<i>Custom</i>ActionDomainEvent.class). +end note + +note right of EL +EventListeners can be declared on +any public Spring bean method, e.g. +<b>@EventListener( + <b><i>Custom</i>ActionDomainEvent.class). +Via <i>DomainEvent</i>.getEventPhase(), +further filtering can be applied. +end note +@enduml +---- + +== Persistence Events + +As specified using xref:refguide:applib:index/annotation/DomainObject.adoc[@DomainObject#xxxLifecycleEvent()]: + +.Persistence Events +[plantuml,file="eventbus_persistence.png"] +---- +@startuml + +(Event\nBus) as EB +(Spring) as SPRING +SPRING .l.> EB : provides/\nmanages +(Event\nListener) as EL +EL --> EB : listens + +(<i>Object</i>\nLifecyleEvent) as LCE +LCE -> EB : published to +(Created\nEvent) as C +C -u-> LCE : is a +(Loaded\nEvent) as L +L -u-> LCE : is a + +(Persisting\nEvent) as PNG +PNG -u-> LCE : is a +(Persisted\nEvent) as PED +PED -u-> LCE : is a + +(Updating\nEvent) as UNG +UNG -u-> LCE : is a +(Updated\nEvent) as UED +UED -u-> LCE : is a + +(Removing\nEvent) as RNG +RNG -u-> LCE : is a + +(Factory\nService) as FS +FS -u-> C :emits +(Repository\nService) as RS +RS -u-> L :emits +RS -u-> PNG :emits +RS -u-> PED :emits +RS -u-> UNG :emits +RS -u-> UED :emits +RS -u-> RNG :emits + +note top of RNG +JDO/Datanucleus +does not support +something like a +"Removed Event". +Hence not implemented. +end note + +@enduml +---- diff --git a/core/metamodel/src/main/adoc/modules/metamodel/partials/module-nav.adoc b/core/metamodel/src/main/adoc/modules/metamodel/partials/module-nav.adoc index 7dd2416567..c34b9343ba 100644 --- a/core/metamodel/src/main/adoc/modules/metamodel/partials/module-nav.adoc +++ b/core/metamodel/src/main/adoc/modules/metamodel/partials/module-nav.adoc @@ -1,3 +1,4 @@ * xref:core:metamodel:about.adoc[MetaModel] -** xref:core:metamodel:class-diagram.adoc[Class Diagram] +** xref:core:metamodel:class-diagram.adoc[] +** xref:core:metamodel:events.adoc[] diff --git a/core/runtime/src/main/adoc/modules/runtime/pages/about.adoc b/core/runtime/src/main/adoc/modules/runtime/pages/about.adoc index cd1987ad09..5d35c7fc40 100644 --- a/core/runtime/src/main/adoc/modules/runtime/pages/about.adoc +++ b/core/runtime/src/main/adoc/modules/runtime/pages/about.adoc @@ -2,4 +2,7 @@ :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] -WARNING: TODO + +This is a very small module providing a set of classes to handle the runtime context. + +It also has classes that trigger events for when the metamodel is fully built (after bootstrapping), and to emit events for transaction boundaries. diff --git a/core/runtimeservices/src/main/adoc/modules/runtimeservices/pages/about.adoc b/core/runtimeservices/src/main/adoc/modules/runtimeservices/pages/about.adoc index 262b3aceb5..cc06376049 100644 --- a/core/runtimeservices/src/main/adoc/modules/runtimeservices/pages/about.adoc +++ b/core/runtimeservices/src/main/adoc/modules/runtimeservices/pages/about.adoc @@ -2,4 +2,11 @@ :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] -WARNING: TODO +this module provides an extensive set of domain services. + +Many of the services defined (as interfaces) in the applib are actually implemented in this module (the rest are defined in xref:core:metamodel:about.adoc[]). + + +Although it's a simplification, you can think of the xref:core:metamodel:about.adoc[] module as handling domain types (cf `java.lang.Class`), while the xref:core:runtime:about.adoc[], xref:core:runtimeservices:about.adoc[] and xref:transaction:about.adoc[] modules handle domain object instances (cf `java.lang.Object`). + +That said, Spring Boot is responsible for instantiating domain service instances, while the persistence mechanisms (xref:pjpa:ROOT:about.adoc[JPA] and xref:pjdo:ROOT:about.adoc[JDO]) -- which are not part of the `core` modules -- handle the lifecycle of entity instances. diff --git a/core/transaction/src/main/adoc/modules/transaction/pages/about.adoc b/core/transaction/src/main/adoc/modules/transaction/pages/about.adoc index c30fbd93ce..7ac3d9a3ef 100644 --- a/core/transaction/src/main/adoc/modules/transaction/pages/about.adoc +++ b/core/transaction/src/main/adoc/modules/transaction/pages/about.adoc @@ -2,4 +2,4 @@ :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] -WARNING: TODO +This is a small module prociding a set of classes primarily concerned with for tracking changes to entities during transactions. diff --git a/core/webapp/src/main/adoc/modules/webapp/pages/about.adoc b/core/webapp/src/main/adoc/modules/webapp/pages/about.adoc index 275366a3c2..db5b483b57 100644 --- a/core/webapp/src/main/adoc/modules/webapp/pages/about.adoc +++ b/core/webapp/src/main/adoc/modules/webapp/pages/about.adoc @@ -1,5 +1,7 @@ -= Runtime Web += Webapp :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] -WARNING: TODO +This module provides classes used to bootstrap the app itself. + +Through the xref:webmodules.adoc[WebModule] interface, it also provides a hook for other components to contribute their own filters and servlets into the web request pipeline. diff --git a/core/webapp/src/main/adoc/modules/webapp/pages/webmodules.adoc b/core/webapp/src/main/adoc/modules/webapp/pages/webmodules.adoc index b8d161418a..68a5e47317 100644 --- a/core/webapp/src/main/adoc/modules/webapp/pages/webmodules.adoc +++ b/core/webapp/src/main/adoc/modules/webapp/pages/webmodules.adoc @@ -1,5 +1,5 @@ [#webmodule-interface] -= ``WebModule`` interface += `WebModule` interface :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] diff --git a/incubator/adoc/modules/ROOT/pages/about.adoc b/incubator/adoc/modules/ROOT/pages/about.adoc index b2b545b670..7ee16d67fa 100644 --- a/incubator/adoc/modules/ROOT/pages/about.adoc +++ b/incubator/adoc/modules/ROOT/pages/about.adoc @@ -1,4 +1,4 @@ -= Incubator Catalog += Incubator :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...] :page-partial: diff --git a/regressiontests/adoc/antora.yml b/regressiontests/adoc/antora.yml index 1a59920126..ad7fd33bfb 100644 --- a/regressiontests/adoc/antora.yml +++ b/regressiontests/adoc/antora.yml @@ -15,5 +15,5 @@ # specific language governing permissions and limitations # under the License. -name: core +name: regressiontests version: latest diff --git a/regressiontests/adoc/modules/regressiontests/nav.adoc b/regressiontests/adoc/modules/ROOT/nav.adoc similarity index 100% rename from regressiontests/adoc/modules/regressiontests/nav.adoc rename to regressiontests/adoc/modules/ROOT/nav.adoc diff --git a/regressiontests/adoc/modules/regressiontests/pages/about.adoc b/regressiontests/adoc/modules/ROOT/pages/about.adoc similarity index 100% rename from regressiontests/adoc/modules/regressiontests/pages/about.adoc rename to regressiontests/adoc/modules/ROOT/pages/about.adoc diff --git a/regressiontests/adoc/modules/ROOT/partials/module-nav.adoc b/regressiontests/adoc/modules/ROOT/partials/module-nav.adoc new file mode 100644 index 0000000000..33091056b2 --- /dev/null +++ b/regressiontests/adoc/modules/ROOT/partials/module-nav.adoc @@ -0,0 +1,4 @@ + +* xref:regressiontests:ROOT:about.adoc[Regression Tests] + + diff --git a/regressiontests/adoc/modules/regressiontests/partials/module-nav.adoc b/regressiontests/adoc/modules/regressiontests/partials/module-nav.adoc deleted file mode 100644 index 2d1ef6f190..0000000000 --- a/regressiontests/adoc/modules/regressiontests/partials/module-nav.adoc +++ /dev/null @@ -1,4 +0,0 @@ - -* xref:regressiontests:about.adoc[Regression Tests] - - diff --git a/starters/adoc/modules/parent-pom/images/parent-pom.drawio.svg b/starters/adoc/modules/parent-pom/images/parent-pom.drawio.svg index b4ff6b46c3..b6780d8d52 100644 --- a/starters/adoc/modules/parent-pom/images/parent-pom.drawio.svg +++ b/starters/adoc/modules/parent-pom/images/parent-pom.drawio.svg @@ -1 +1,4 @@ -<svg xmlns="http://www.w3.org/2000/svg"; xmlns:xlink="http://www.w3.org/1999/xlink"; version="1.1" width="969px" height="587px" viewBox="-0.5 -0.5 969 587" content="<mxfile host="drawio-plugin" modified="2021-03-20T18:50:08.414Z" agent="5.0 (Windows NT 6.2; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.105 Safari/537.36" etag="UsPSK2NaPMQWWJsnPGkd" version="13.7.9" type="embed"><diagram id="zLki [...] \ No newline at end of file +<?xml version="1.0" encoding="UTF-8"?> +<!-- Do not edit this file with editors other than diagrams.net --> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd";> +<svg xmlns="http://www.w3.org/2000/svg"; xmlns:xlink="http://www.w3.org/1999/xlink"; version="1.1" width="948px" height="537px" viewBox="-0.5 -0.5 948 537" content="<mxfile host="drawio-plugin" modified="2022-08-20T17:31:33.191Z" agent="5.0 (Windows NT 6.2; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.102 Safari/537.36" etag="yrIjiW0jVsrb64JQAW_C" version="15.5.4" type="embed"><diagram id="zLki [...] \ No newline at end of file diff --git a/valuetypes/adoc/modules/ROOT/partials/component-nav.adoc b/valuetypes/adoc/modules/ROOT/partials/component-nav.adoc index 773df960fd..7c1f3b5a06 100644 --- a/valuetypes/adoc/modules/ROOT/partials/component-nav.adoc +++ b/valuetypes/adoc/modules/ROOT/partials/component-nav.adoc @@ -6,4 +6,4 @@ include::valuetypes:ROOT:partial$module-nav.adoc[] include::valuetypes:asciidoc:partial$module-nav.adoc[] include::valuetypes:markdown:partial$module-nav.adoc[] -include::valuetypes:sse:partial$module-nav.adoc[] +
![https://github.com/apache-isis-committers/isis-nightly/workflows/Nightly/badge.svg[link="https://github.com/apache-isis-committers/isis-nightly/actions?query=workflow%3A%22Nightly%22"](https://github.com/apache-isis-committers/isis-nightly/workflows/Nightly/badge.svg[link="https://github.com/apache-isis-committers/isis-nightly/actions?query=workflow%3A%22Nightly%22"){kind=link}
