This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch CAUSEWAY-3676 in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 75c7b80b37916326ce39b890dbf3975e64d21755 Author: danhaywood <[email protected]> AuthorDate: Thu Mar 14 11:47:36 2024 +0000 CAUSEWAY-3676: updates docs --- .../pages/index/annotation/NatureOfService.adoc | 86 ++++++++++++---------- .../pages/index/services/swagger/Visibility.adoc | 4 +- ...sewayConfiguration_Viewer_Graphql_ApiScope.adoc | 42 +++++++++++ ...ayConfiguration_Viewer_Graphql_SchemaStyle.adoc | 72 ++++++++++++++++++ core/adoc/modules/_overview/pages/about.adoc | 46 +++++++++++- .../pages/sections/causeway.viewer.graphql.adoc | 4 +- .../core/config/CausewayConfiguration.java | 16 +++- .../ROOT/pages/setup-and-configuration.adoc | 5 ++ 8 files changed, 229 insertions(+), 46 deletions(-) diff --git a/antora/components/refguide-index/modules/applib/pages/index/annotation/NatureOfService.adoc b/antora/components/refguide-index/modules/applib/pages/index/annotation/NatureOfService.adoc index 8b7ce76a5a..1603af19a9 100644 --- a/antora/components/refguide-index/modules/applib/pages/index/annotation/NatureOfService.adoc +++ b/antora/components/refguide-index/modules/applib/pages/index/annotation/NatureOfService.adoc @@ -9,41 +9,48 @@ The different sorts of domain services recognized by Causeway, as specified in _ .NatureOfService.java ---- enum NatureOfService { - WEB_UI // <.> - WEB_API // <.> - BOTH // <.> - boolean isBoth() // <.> - boolean isWebUi() // <.> - boolean isWebApi() // <.> + WEB_UI + WEB_API + BOTH + VIEW // <.> + REST // <.> + boolean isEnabledEverywhere() // <.> + boolean isEnabledForUi() // <.> + boolean isEnabledForWebApi() // <.> } ---- -<.> xref:#WEB_UI[WEB_UI] +<.> xref:#VIEW[VIEW] + -- -The service's actions appear only in the menu bar human-usable Web UIs (such as Wicket viewer). They do _not_ appear in any REST or GraphQL APIs. --- -<.> xref:#WEB_API[WEB_API] -+ --- -The service's actions should only be visible in the Web API exposed by the Restful Objects viewer and the GraphQL viewer. They do _not_ appear in any human-usable Web UIs (such as Wicket viewer) +[WARNING] +==== +[red]#_deprecated:_# + +use _#BOTH_ instead +==== -- -<.> xref:#BOTH[BOTH] +<.> xref:#REST[REST] + -- -The service's actions appear in the menu bar of Web UIs (such as Wicket viewer), and also appear in the Web APIs (Restful Objects viewer and GraphQL viewer). +[WARNING] +==== +[red]#_deprecated:_# + +use _#WEB_API_ instead +==== -- -<.> xref:#isBoth_[isBoth()] +<.> xref:#isEnabledEverywhere_[isEnabledEverywhere()] + -- -Whether a service contributes its actions to both human-usable Web UIs and the Web APIs. +Whether a service contributes its actions to both human-usable UIs and the Web APIs. -- -<.> xref:#isWebUi_[isWebUi()] +<.> xref:#isEnabledForUi_[isEnabledForUi()] + -- -Whether a service contributes its actions exclusively to human-usable Web UIs. +Whether a service contributes its actions to human-usable UIs. -- -<.> xref:#isWebApi_[isWebApi()] +<.> xref:#isEnabledForWebApi_[isEnabledForWebApi()] + -- Whether a service contributes its actions to Web APIs (REST and GraphQL) @@ -51,32 +58,37 @@ Whether a service contributes its actions to Web APIs (REST and GraphQL) == Members -[#WEB_UI] -=== WEB_UI +[#VIEW] +=== VIEW -The service's actions appear only in the menu bar human-usable Web UIs (such as Wicket viewer). They do _not_ appear in any REST or GraphQL APIs. +[WARNING] +==== +[red]#_deprecated:_# -[#WEB_API] -=== WEB_API +use _#BOTH_ instead +==== -The service's actions should only be visible in the Web API exposed by the Restful Objects viewer and the GraphQL viewer. They do _not_ appear in any human-usable Web UIs (such as Wicket viewer) +[#REST] +=== REST -[#BOTH] -=== BOTH +[WARNING] +==== +[red]#_deprecated:_# -The service's actions appear in the menu bar of Web UIs (such as Wicket viewer), and also appear in the Web APIs (Restful Objects viewer and GraphQL viewer). +use _#WEB_API_ instead +==== -[#isBoth_] -=== isBoth() +[#isEnabledEverywhere_] +=== isEnabledEverywhere() -Whether a service contributes its actions to both human-usable Web UIs and the Web APIs. +Whether a service contributes its actions to both human-usable UIs and the Web APIs. -[#isWebUi_] -=== isWebUi() +[#isEnabledForUi_] +=== isEnabledForUi() -Whether a service contributes its actions exclusively to human-usable Web UIs. +Whether a service contributes its actions to human-usable UIs. -[#isWebApi_] -=== isWebApi() +[#isEnabledForWebApi_] +=== isEnabledForWebApi() Whether a service contributes its actions to Web APIs (REST and GraphQL) diff --git a/antora/components/refguide-index/modules/applib/pages/index/services/swagger/Visibility.adoc b/antora/components/refguide-index/modules/applib/pages/index/services/swagger/Visibility.adoc index 95803de4f0..6934194482 100644 --- a/antora/components/refguide-index/modules/applib/pages/index/services/swagger/Visibility.adoc +++ b/antora/components/refguide-index/modules/applib/pages/index/services/swagger/Visibility.adoc @@ -41,14 +41,14 @@ As _#PRIVATE_ , also including any prototype actions (where _Action#restrictTo() Specification for use by third-party clients, ie public use and not under the control of the authors of the backend Apache Causeway application. -The generated swagger spec is therefore restricted only to include only view models ( _DomainObject#nature()_ of _org.apache.causeway.applib.annotation.Nature#VIEW_MODEL_ ) and to REST domain services ( _DomainService#nature()_ of _NatureOfService#WEB_API_ ). Exposing entities also would couple the REST client too deeply to the backend implementation. +The generated swagger spec is therefore restricted only to include only view models ( _DomainObject#nature()_ of _org.apache.causeway.applib.annotation.Nature#VIEW_MODEL_ ) and to Web API domain services ( _DomainService#nature()_ of _NatureOfService#WEB_API_ ). Exposing entities also would couple the REST client too deeply to the backend implementation. [#PRIVATE] === PRIVATE Specification for use only by internally-managed clients, ie private internal use. -This visibility level removes all constraints and so includes the specifications of domain entities as well as view models. This is perfectly acceptable where the team developing the REST client is the same as the team developing the backend service ... the use of the REST API between the client and server is a private implementation detail of the application. +This visibility level removes all constraints and so includes the specifications of domain entities as well as view models. This is perfectly acceptable where the team developing the REST client is the same as the team developing the backend service ... the use of the Web API between the client and server is a private implementation detail of the application. [#PRIVATE_WITH_PROTOTYPING] === PRIVATE_WITH_PROTOTYPING diff --git a/antora/components/refguide-index/modules/core/pages/index/config/CausewayConfiguration_Viewer_Graphql_ApiScope.adoc b/antora/components/refguide-index/modules/core/pages/index/config/CausewayConfiguration_Viewer_Graphql_ApiScope.adoc new file mode 100644 index 0000000000..ff5daec1a5 --- /dev/null +++ b/antora/components/refguide-index/modules/core/pages/index/config/CausewayConfiguration_Viewer_Graphql_ApiScope.adoc @@ -0,0 +1,42 @@ += CausewayConfiguration.Viewer.Graphql.ApiScope _(enum)_ +: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 [...] + +Specifies which elements of the metamodel are included within the generated GraphQL spec. + +== API + +[source,java] +.CausewayConfiguration_Viewer_Graphql_ApiScope.java +---- +enum ApiScope { + VIEW_MODELS // <.> + ALL // <.> +} +---- + +<.> xref:#VIEW_MODELS[VIEW_MODELS] ++ +-- +The generated GraphQL spec is restricted only to include only _org.apache.causeway.applib.annotation.Nature#VIEW_MODEL view model_ s. +-- +<.> xref:#ALL[ALL] ++ +-- +The generated GraphQL spec is not restricted, includes both _org.apache.causeway.applib.annotation.Nature#ENTITY domain entities_ as well as _org.apache.causeway.applib.annotation.Nature#VIEW_MODEL view model_ s. +-- + +== Members + +[#VIEW_MODELS] +=== VIEW_MODELS + +The generated GraphQL spec is restricted only to include only _org.apache.causeway.applib.annotation.Nature#VIEW_MODEL view model_ s. + +Applicable when the GraphQL API is in use by third-party clients, ie public use and not under the control of the authors of the backend Apache Causeway application. Exposing entities also would couple the GraphQL client too deeply to the backend implementation. + +[#ALL] +=== ALL + +The generated GraphQL spec is not restricted, includes both _org.apache.causeway.applib.annotation.Nature#ENTITY domain entities_ as well as _org.apache.causeway.applib.annotation.Nature#VIEW_MODEL view model_ s. + +This is perfectly acceptable where the team developing the GraphQL client is the same as the team developing the backend service ... the use of the Web API between the client and server is a private implementation detail of the application. diff --git a/antora/components/refguide-index/modules/core/pages/index/config/CausewayConfiguration_Viewer_Graphql_SchemaStyle.adoc b/antora/components/refguide-index/modules/core/pages/index/config/CausewayConfiguration_Viewer_Graphql_SchemaStyle.adoc new file mode 100644 index 0000000000..d02bfa50c6 --- /dev/null +++ b/antora/components/refguide-index/modules/core/pages/index/config/CausewayConfiguration_Viewer_Graphql_SchemaStyle.adoc @@ -0,0 +1,72 @@ += CausewayConfiguration.Viewer.Graphql.SchemaStyle _(enum)_ +: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 [...] + +Which style of schema to expose: "simple", "rich" or some combination of both. + +== API + +[source,java] +.CausewayConfiguration_Viewer_Graphql_SchemaStyle.java +---- +enum SchemaStyle { + SIMPLE_ONLY // <.> + RICH_ONLY // <.> + SIMPLE_AND_RICH // <.> + RICH_AND_SIMPLE // <.> + boolean isRich() + boolean isSimple() +} +---- + +<.> xref:#SIMPLE_ONLY[SIMPLE_ONLY] ++ +-- +Expose only the "simple" schema, defining only fields that return the state of the domain objects but with no fields to represent additional facets of state (such as whether an action is hidden or disabled). +-- +<.> xref:#RICH_ONLY[RICH_ONLY] ++ +-- +Expose only the "rich" schema, exposing not only fields that return the state of the domain objects but _also_ with fields to represent additional facets of state (such as whether an action is hidden or disabled). +-- +<.> xref:#SIMPLE_AND_RICH[SIMPLE_AND_RICH] ++ +-- +Exposes both the simple and rich schemas, for the query have each under a field as defined by _Schema.Simple#getTopLevelFieldName()_ (by default "simple") and _Schema.Rich#getTopLevelFieldName()_ (by default "rich"). +-- +<.> xref:#RICH_AND_SIMPLE[RICH_AND_SIMPLE] ++ +-- +Exposes both the simple and rich schemas, for the query have each under a field as defined by _Schema.Simple#getTopLevelFieldName()_ (by default "simple") and _Schema.Rich#getTopLevelFieldName()_ (by default "rich"). +-- + +== Members + +[#SIMPLE_ONLY] +=== SIMPLE_ONLY + +Expose only the "simple" schema, defining only fields that return the state of the domain objects but with no fields to represent additional facets of state (such as whether an action is hidden or disabled). + +Suitable for clients where the application logic and state is the responsibility of the client. + +[#RICH_ONLY] +=== RICH_ONLY + +Expose only the "rich" schema, exposing not only fields that return the state of the domain objects but _also_ with fields to represent additional facets of state (such as whether an action is hidden or disabled). + +Optionally, fields for Scenario (given/when/then) testing may also be added if the _Schema.Rich#isEnableScenarioTesting()_ config property is set. + +Suitable for clients where the application logic and state remains in the backend, within the domain model hosted by Causeway. + +[#SIMPLE_AND_RICH] +=== SIMPLE_AND_RICH + +Exposes both the simple and rich schemas, for the query have each under a field as defined by _Schema.Simple#getTopLevelFieldName()_ (by default "simple") and _Schema.Rich#getTopLevelFieldName()_ (by default "rich"). + +For mutations, use the _simple_ schema types. + +[#RICH_AND_SIMPLE] +=== RICH_AND_SIMPLE + +Exposes both the simple and rich schemas, for the query have each under a field as defined by _Schema.Simple#getTopLevelFieldName()_ (by default "simple") and _Schema.Rich#getTopLevelFieldName()_ (by default "rich"). + +For mutations, use the _rich_ schema types. diff --git a/core/adoc/modules/_overview/pages/about.adoc b/core/adoc/modules/_overview/pages/about.adoc index 4413114ad4..aa8ff9ccbe 100644 --- a/core/adoc/modules/_overview/pages/about.adoc +++ b/core/adoc/modules/_overview/pages/about.adoc @@ -1132,7 +1132,7 @@ org.springframework.boot:spring-boot-configuration-processor:jar:<managed> + .Document Index Entries **** -xref:refguide:core:index/config/datasources/DataSourceIntrospectionService.adoc[DataSourceIntrospectionService] +xref:refguide:core:index/config/CausewayConfiguration_Viewer_Graphql_ApiScope.adoc[CausewayConfiguration.Viewer.Graphql.ApiScope], xref:refguide:core:index/config/CausewayConfiguration_Viewer_Graphql_SchemaStyle.adoc[CausewayConfiguration.Viewer.Graphql.SchemaStyle], xref:refguide:core:index/config/datasources/DataSourceIntrospectionService.adoc[DataSourceIntrospectionService] **** |Apache Causeway Core - Interaction @@ -2518,6 +2518,12 @@ skinparam rectangle<<GraphQL.ApacheCausewayViewerGraphQLModel>> { BorderColor #2e6295 shadowing false } +skinparam rectangle<<GraphQL.ApacheCausewayViewerGraphQLTest2>> { + BackgroundColor #438dd5 + FontColor #fffffe + BorderColor #2e6295 + shadowing false +} skinparam rectangle<<GraphQL.ApacheCausewayViewerGraphQLTestSupport>> { BackgroundColor #438dd5 FontColor #fffffe @@ -2547,15 +2553,17 @@ rectangle "GraphQL\n<size:10>[Software System]</size>" <<GraphQL>> { rectangle "==Apache Causeway Viewer - GraphQL (Applib)\n<size:10>[Container: packaging: jar]</size>" <<GraphQL.ApacheCausewayViewerGraphQLApplib>> as GraphQL.ApacheCausewayViewerGraphQLApplib rectangle "==Apache Causeway Viewer - GraphQL (Model)\n<size:10>[Container: packaging: jar]</size>" <<GraphQL.ApacheCausewayViewerGraphQLModel>> as GraphQL.ApacheCausewayViewerGraphQLModel rectangle "==Apache Causeway Viewer - GraphQL (Test)\n<size:10>[Container: packaging: jar]</size>" <<GraphQL.ApacheCausewayViewerGraphQLTest>> as GraphQL.ApacheCausewayViewerGraphQLTest + rectangle "==Apache Causeway Viewer - GraphQL (Test 2)\n<size:10>[Container: packaging: jar]</size>" <<GraphQL.ApacheCausewayViewerGraphQLTest2>> as GraphQL.ApacheCausewayViewerGraphQLTest2 rectangle "==Apache Causeway Viewer - GraphQL (Test Support)\n<size:10>[Container: packaging: jar]</size>" <<GraphQL.ApacheCausewayViewerGraphQLTestSupport>> as GraphQL.ApacheCausewayViewerGraphQLTestSupport rectangle "==Apache Causeway Viewer - GraphQL (Viewer)\n<size:10>[Container: packaging: jar]</size>" <<GraphQL.ApacheCausewayViewerGraphQLViewer>> as GraphQL.ApacheCausewayViewerGraphQLViewer } +GraphQL.ApacheCausewayViewerGraphQL .[#707070,thickness=2].> GraphQL.ApacheCausewayViewerGraphQLModel : "<color:#707070>" GraphQL.ApacheCausewayViewerGraphQL .[#707070,thickness=2].> GraphQL.ApacheCausewayViewerGraphQLTest : "<color:#707070>" +GraphQL.ApacheCausewayViewerGraphQL .[#707070,thickness=2].> GraphQL.ApacheCausewayViewerGraphQLTest2 : "<color:#707070>" GraphQL.ApacheCausewayViewerGraphQL .[#707070,thickness=2].> GraphQL.ApacheCausewayViewerGraphQLTestSupport : "<color:#707070>" GraphQL.ApacheCausewayViewerGraphQL .[#707070,thickness=2].> GraphQL.ApacheCausewayViewerGraphQLViewer : "<color:#707070>" GraphQL.ApacheCausewayViewerGraphQL .[#707070,thickness=2].> GraphQL.ApacheCausewayViewerGraphQLApplib : "<color:#707070>" -GraphQL.ApacheCausewayViewerGraphQL .[#707070,thickness=2].> GraphQL.ApacheCausewayViewerGraphQLModel : "<color:#707070>" @enduml ---- @@ -2671,6 +2679,24 @@ org.apache.causeway.viewer:causeway-viewer-graphql-testsupport:jar:<managed> + org.springframework.boot:spring-boot-test-autoconfigure:jar:<managed> + **** +|Apache Causeway Viewer - GraphQL (Test 2) +[source,yaml] +---- +Group: org.apache.causeway.viewer +Artifact: causeway-viewer-graphql-test2 +Type: jar +Directory: /viewers/graphql/test2 +---- +|.Dependencies +**** +com.github.gavlyukovskiy:datasource-proxy-spring-boot-starter:jar:<managed> + +com.github.vertical-blank:sql-formatter:jar:<managed> + +com.h2database:h2:jar:<managed> + +org.apache.causeway.persistence:causeway-persistence-jpa-eclipselink:jar:<managed> + +org.apache.causeway.viewer:causeway-viewer-graphql-testsupport:jar:<managed> + +org.springframework.boot:spring-boot-test-autoconfigure:jar:<managed> + +**** + |Apache Causeway Viewer - GraphQL (Test Support) [source,yaml] ---- @@ -7323,6 +7349,12 @@ Directory: /incubator/extensions/core/commandreplay/primary ---- |A module for obtaining commands from a primary +.Components +**** +o.a.i.extensions.commandreplay.primary.config.PrimaryConfig + +o.a.i.extensions.commandreplay.primary.spiimpl.CaptureResultOfCommand + +**** + .Dependencies **** org.apache.causeway.core:causeway-core-config:jar:<managed> + @@ -7348,6 +7380,16 @@ Directory: /incubator/extensions/core/commandreplay/secondary |A module providing a Quartz Job to run on a secondary system, for obtaining commands from a primary and saving them so that they are replayed. +.Components +**** +o.a.i.extensions.commandreplay.secondary.analyser.CommandReplayAnalyserException + +o.a.i.extensions.commandreplay.secondary.analyser.CommandReplayAnalyserResult + +o.a.i.extensions.commandreplay.secondary.analysis.CommandReplayAnalysisService + +o.a.i.extensions.commandreplay.secondary.config.SecondaryConfig + +o.a.i.extensions.commandreplay.secondary.fetch.CommandFetcher + +o.a.i.extensions.commandreplay.secondary.job.ReplicateAndReplayJob + +**** + .Dependencies **** org.apache.causeway.core:causeway-core-config:jar:<managed> + diff --git a/core/config/src/main/adoc/modules/config/pages/sections/causeway.viewer.graphql.adoc b/core/config/src/main/adoc/modules/config/pages/sections/causeway.viewer.graphql.adoc index 0c57594ecc..5708adc19e 100644 --- a/core/config/src/main/adoc/modules/config/pages/sections/causeway.viewer.graphql.adoc +++ b/core/config/src/main/adoc/modules/config/pages/sections/causeway.viewer.graphql.adoc @@ -16,7 +16,7 @@ include::../section-hooks/causeway.viewer.graphql~pre.adoc[] causeway.viewer.graphql.api-scope | -| Which domain objects to include the GraphQL schema. +| Which domain objects to include the GraphQL schema. By default, all domain objects are exposed (entities and view models). | @@ -138,7 +138,7 @@ causeway.viewer.graphql. + schema-style | -| Which ``SchemaStyle`` to expose. +| Which ``SchemaStyle`` to expose, "simple" or "rich". By default both are exposed under top-level field names. @see Schema.Rich#getTopLevelFieldName() @see Schema.Simple#getTopLevelFieldName() | diff --git a/core/config/src/main/java/org/apache/causeway/core/config/CausewayConfiguration.java b/core/config/src/main/java/org/apache/causeway/core/config/CausewayConfiguration.java index 629157f69f..1c18236d7e 100644 --- a/core/config/src/main/java/org/apache/causeway/core/config/CausewayConfiguration.java +++ b/core/config/src/main/java/org/apache/causeway/core/config/CausewayConfiguration.java @@ -2348,6 +2348,11 @@ public class CausewayConfiguration { @Data public static class Graphql { + /** + * Which style of schema to expose: "simple", "rich" or some combination of both. + * + * @since 2.0 {@index} + */ public enum SchemaStyle { /** * Expose only the "simple" schema, defining only fields that return the state of the domain @@ -2405,7 +2410,11 @@ public class CausewayConfiguration { } /** - * Which {@link SchemaStyle} to expose. + * Which {@link SchemaStyle} to expose, "simple" or "rich". By default both are + * exposed under top-level field names. + * + * @see Schema.Rich#getTopLevelFieldName() + * @see Schema.Simple#getTopLevelFieldName() */ private SchemaStyle schemaStyle = SchemaStyle.RICH_AND_SIMPLE; @@ -2496,7 +2505,7 @@ public class CausewayConfiguration { * Specifies which elements of the metamodel are included within the generated * GraphQL spec. * - * @since 1.x {@index} + * @since 2.x {@index} */ public enum ApiScope { @@ -2528,7 +2537,8 @@ public class CausewayConfiguration { } /** - * Which domain objects to include the GraphQL schema. + * Which domain objects to include the GraphQL schema. By default, all domain objects are exposed + * (entities and view models). */ private ApiScope apiScope = ApiScope.ALL; diff --git a/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc b/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc index 67ec965f0d..cdadfeeca4 100644 --- a/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc +++ b/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc @@ -41,6 +41,11 @@ The most important configuration properties are: + Whether to support relaxed (but non-spec compliant) queries with mutations, or instead to expose an API that is query only. +* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.api-scope[api-scope] ++ +Whether to include all domain classes in the GraphQL schema (entities and view models), or whether only to include view models. +Which to use depends upon whether the GraphQL client is owned by the same team the owns the backend application. + * xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.schema-style[schema-style] + Whether to use the "simple" schema style (data only, client-driven), the "rich" schema style (includes supporting facets, server-driven) or both schema styles.
