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 47474a365a59b83450ca09bc9a5f3954e9b5a40a Author: danhaywood <[email protected]> AuthorDate: Sun Feb 11 11:45:59 2024 +0000 CAUSEWAY-3676: updates docs further --- .../pages/sections/causeway.viewer.graphql.adoc | 10 ++-- .../ROOT/pages/setup-and-configuration.adoc | 56 ------------------ ...up-and-configuration.adoc => spi-services.adoc} | 69 +++------------------- .../adoc/modules/ROOT/partials/module-nav.adoc | 1 + 4 files changed, 15 insertions(+), 121 deletions(-) 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 b78768d44a..40e5d38d61 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 @@ -84,18 +84,20 @@ target-arg-name | -[[causeway.viewer.graphql.type-mapper.local-date-format]] +[[causeway.viewer.graphql.scalar-marshaller.local-date-format]] causeway.viewer.graphql. + -type-mapper.local-date-format +scalar-marshaller. + +local-date-format | yyyy-MM-dd | For both JDK8's ``LocalDate`` and JodaTime's ``LocalDate`` | -[[causeway.viewer.graphql.type-mapper.zoned-date-time-format]] +[[causeway.viewer.graphql.scalar-marshaller.zoned-date-time-format]] causeway.viewer.graphql. + -type-mapper.zoned-date-time-format +scalar-marshaller. + +zoned-date-time-format | yyyy-MM-dd HH:mm:ss z | for JDK8's ``ZonedDateTime`` and JodaTime's ``DateTime`` 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 cd95123f12..680a65deb3 100644 --- a/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc +++ b/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc @@ -46,59 +46,3 @@ The default value for this config property is "_gqlv_meta". The xref:refguide:config:about.adoc[Configuration Guide] includes a xref:refguide:config:sections/causeway.viewer.graphql.adoc[section] for the GraphQL viewer. -== SPI Services - -The GraphQL viewer defines a couple of services that are intended to act as SPI hooks for more sophisticated implementations. -The viewer does provide default implementations. - -=== UserMementoProvider - -The purpose of the xref:refguide:viewer:index/graphql/applib/auth/UserMementoProvider.adoc[] SPI is to obtain the xref:refguide:applib:index/services/user/UserMemento.adoc[] -- in other words the identity -- of the client executing the API. - -In a production app, this would be inferred by hooking into the request execution parameters; these are provided to the service. - -The default (fallback) implementation simply uses a hard-coded value taken from the configuration: - -* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.authentication.fallback.username[causeway.viewer.graphql.authentication.fallback.username] -+ -The username of the client assumed to be making the GraphQL call. - -* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.authentication.fallback.roles[causeway.viewer.graphql.authentication.fallback.roles] -+ -Corresponding roles. -May or may not be used, depending upon the security configuration. -(For example, if xref:security:secman:about.adoc[] is in use, then the roles are defined by SecMan itself and this config property is ignored). - - - -=== ScalarMarshaller - -The purpose of the xref:refguide:viewer:index/graphql/applib/marshallers/ScalarMarshaller.adoc[] SPI is to provide an extension point for the marshalling of scalar values. - -Each marshaller is responsible for marshalling a given scalar between its Java and GraphQL datatype. -The framework provides a number of default implementations; these use a number of configuration properties: - -* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.scalar-marshaller.local-date-format[causeway.viewer.graphql.scalar-marshaller.local-date-format]. -+ -GraphQL does not have a built-in date datatype, and so must be represented as strings. -This configuration property define the format of such a string for a local date. -+ -The default for local dates is "yyyy-MM-dd" - -* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.scalar-marshaller.zoned-date-time-format[causeway.viewer.graphql.scalar-marshaller.zoned-date-time-format] -+ -GraphQL does not have a built-in date/time datatype, and so must be represented as strings. -This configuration property define the format of such a string for a zoned date time. -+ -The default for a zoned date time is "yyyy-MM-dd HH:mm:ss z". - - -The default implementations can be overridden if necessary by providing an equivalent implementation with an earlier `@Priority`. -Additional scalar datatypes can be supporting by providing additional implementations. - - - - -=== SPI - - diff --git a/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc b/viewers/graphql/adoc/modules/ROOT/pages/spi-services.adoc similarity index 55% copy from viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc copy to viewers/graphql/adoc/modules/ROOT/pages/spi-services.adoc index cd95123f12..f16283911a 100644 --- a/viewers/graphql/adoc/modules/ROOT/pages/setup-and-configuration.adoc +++ b/viewers/graphql/adoc/modules/ROOT/pages/spi-services.adoc @@ -1,61 +1,14 @@ -= Setup and Configuration += SPI Services :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 section describes how to include the GraphQL viewer's module and set its configuration properties. - - -include::docs:mavendeps:partial$setup-and-configure-mavendeps-webapp.adoc[leveloffset=+1] - - -== Update AppManifest - -In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import the - -[source,java] -.AppManifest.java ----- -@Configuration -@Import({ - ... - CausewayModuleViewerGraphQlViewer.class, - ... -}) -public class AppManifest { -} ----- - - -== Configuration Properties - -The most important configuration property is: - -* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.api-variant[causeway.viewer.graphql.api-variant] -+ -Whether to support relaxed (but non-spec compliant) queries with mutations, or instead to expose an API that is query only. - -In addition: - -* xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.meta-data.field-name[causeway.viewer.graphql.meta-data.field-name] -+ -Defines the field name of the "meta data" structure used to expose the id, logical type name and (for entities) the version of a domain object. -+ -The default value for this config property is "_gqlv_meta". - -The xref:refguide:config:about.adoc[Configuration Guide] includes a xref:refguide:config:sections/causeway.viewer.graphql.adoc[section] for the GraphQL viewer. - - -== SPI Services - The GraphQL viewer defines a couple of services that are intended to act as SPI hooks for more sophisticated implementations. The viewer does provide default implementations. -=== UserMementoProvider - -The purpose of the xref:refguide:viewer:index/graphql/applib/auth/UserMementoProvider.adoc[] SPI is to obtain the xref:refguide:applib:index/services/user/UserMemento.adoc[] -- in other words the identity -- of the client executing the API. +== UserMementoProvider -In a production app, this would be inferred by hooking into the request execution parameters; these are provided to the service. +The xref:refguide:viewer:index/graphql/applib/auth/UserMementoProvider.adoc[] SPI is used to obtain the xref:refguide:applib:index/services/user/UserMemento.adoc[] -- in other words the identity -- of the client executing the API. The default (fallback) implementation simply uses a hard-coded value taken from the configuration: @@ -69,14 +22,14 @@ Corresponding roles. May or may not be used, depending upon the security configuration. (For example, if xref:security:secman:about.adoc[] is in use, then the roles are defined by SecMan itself and this config property is ignored). +In a production app, you might instead want to infer the client identity by hooking into the HTTP request parameters. +See the Spring documentation on link:https://docs.spring.io/spring-graphql/reference/security.html[securing the GraphQL endpoint] and link:https://docs.spring.io/spring-graphql/reference/request-execution.html#execution.context[Context Propagation] for more details. -=== ScalarMarshaller +== ScalarMarshaller -The purpose of the xref:refguide:viewer:index/graphql/applib/marshallers/ScalarMarshaller.adoc[] SPI is to provide an extension point for the marshalling of scalar values. - -Each marshaller is responsible for marshalling a given scalar between its Java and GraphQL datatype. -The framework provides a number of default implementations; these use a number of configuration properties: +The xref:refguide:viewer:index/graphql/applib/marshallers/ScalarMarshaller.adoc[] SPI provides an extension point for the marshalling of a given scalar value (eg an `int` or a `date`) between its Java and GraphQL datatype. +The framework provides a number of default implementations, and these use a number of configuration properties: * xref:refguide:config:sections/causeway.viewer.graphql.adoc#causeway.viewer.graphql.scalar-marshaller.local-date-format[causeway.viewer.graphql.scalar-marshaller.local-date-format]. + @@ -92,13 +45,7 @@ This configuration property define the format of such a string for a zoned date + The default for a zoned date time is "yyyy-MM-dd HH:mm:ss z". - The default implementations can be overridden if necessary by providing an equivalent implementation with an earlier `@Priority`. Additional scalar datatypes can be supporting by providing additional implementations. - - -=== SPI - - diff --git a/viewers/graphql/adoc/modules/ROOT/partials/module-nav.adoc b/viewers/graphql/adoc/modules/ROOT/partials/module-nav.adoc index 59f7350cc6..2f9db26249 100644 --- a/viewers/graphql/adoc/modules/ROOT/partials/module-nav.adoc +++ b/viewers/graphql/adoc/modules/ROOT/partials/module-nav.adoc @@ -1,3 +1,4 @@ * xref:gqlv:ROOT:setup-and-configuration.adoc[] +* xref:gqlv:ROOT:spi-services.adoc[]
