Setup and Configuration

This section describes how to include the GraphQL viewer’s module and set its configuration properties.

Maven pom.xml

Dependency Management

If your application inherits from the Apache Causeway starter app (org.apache.causeway.app:causeway-app-starter-parent) then that will define the version automatically:

pom.xml
<parent>
    <groupId>org.apache.causeway.app</groupId>
    <artifactId>causeway-app-starter-parent</artifactId>
    <version>3.6.0</version>
    <relativePath/>
</parent>

Alternatively, import the core BOM. This is usually done in the top-level parent pom of your application:

pom.xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.causeway.core</groupId>
            <artifactId>causeway-core</artifactId>
            <version>3.6.0</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

Dependency

In the webapp module of your application, add the following dependency:

pom.xml
<dependencies>
    <dependency>
        <groupId>org.apache.causeway.mavendeps</groupId>
        <artifactId>causeway-mavendeps-webapp</artifactId>
        <type>pom</type>
    </dependency>
</dependencies>

Note that this transitively includes the Wicket viewer module (org.apache.causeway.viewer:causeway-viewer-wicket-viewer in your app).

Update AppManifest

In your application’s AppManifest (top-level Spring @Configuration used to bootstrap the app), import the

AppManifest.java
@Configuration
@Import({
        ...
        CausewayModuleViewerGraphQlViewer.class,
        ...
})
public class AppManifest {
}

Configuration Properties

The configuration properties for the GraphQL viewer fall into a number of categories.

(To make this section easier to read, the causeway.viewer.graphql. prefix of all of these configuration properties is omitted).

API variant and Schema Style

The most important configuration properties are:

  • api-variant

    Whether to support relaxed (but non-spec compliant) queries with mutations, or instead to expose an API that is query only.

  • 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.

  • 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.

These were discussed on the main page for GraphQL viewer.

Customizing the Schema

A number of other configuration properties can customize the schema in various ways. Normally these can be left as their default:

  • schema.simple.top-level-field-name

    If using the SIMPLE_AND_RICH or RICH_AND_SIMPLE schema styles, this configuration defines the name of the top-level field that holds the rest of the simple schema.

    It defaults to “simple”.

  • schema.rich.top-level-field-name

    If using the SIMPLE_AND_RICH or RICH_AND_SIMPLE schema styles, this configuration defines the name of the top-level field that holds the rest of the rich schema.

    It defaults to “rich”.

  • 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 “_meta”.

The schema to look up a domain object can also be customized:

  • lookup.arg-name

    This is the name of the synthetic first argument used to locate the object to be looked up.

    It defaults to “object”.

  • lookup.field-name-prefix

    Whether to prefix the field name of the domain object’s type.

    This defaults to an empty string, in other words no prefix.

  • lookup.field-name-suffix

    Whether to add a suffix to the field name of the domain object’s type.

    This defaults to an empty string, in other words no suffix.

If executing a mutation rather than a query:

  • mutation.target-arg-name

    This is the name of the synthetic first argument used to locate the object to be mutated.

    It defaults to “_target”.

Bounded autocomplete response windows

Every rich property or action parameter that advertises autoComplete(search) also advertises the additive autoCompleteWindow(search, offset, size) field. The window returns items, offset and requested size, returned and total counts, configured maximum, previous and next availability, and APPLICATION ordering. One request invokes the authoritative application autocomplete semantic once, preserves that execution’s encounter order, and returns only the requested response slice. This bounds GraphQL response transfer but does not claim persistence query pushdown, cursor stability, or a cross-request snapshot.

autocomplete.default-window-size defaults to 20 and supplies an omitted size. autocomplete.max-window-size defaults to 100 and rejects larger requests before invoking autocomplete. The default must not exceed the maximum. Existing autoComplete(search) documents remain compatible.

Local rich member metadata

Known rich property, collection, action, and action-parameter wrappers expose one additive non-null metadata object. Targeted introspection of RichMemberMetadata discovers its bounded shared shape without requesting an aggregate member list or metamodel document.

metadata {
  friendlyName
  description
  maxLength
  pattern
  patternFlags
  multiLine
  typicalLength
}

friendlyName is the non-null canonical translated name. description is the independent canonical translated description and is null when absent rather than repeating the friendly name. The resolver uses static canonical facets at request time and does not invoke imperative domain-object naming or description methods.

maxLength, pattern, patternFlags, multiLine, and typicalLength are populated for property and action-parameter wrappers when applicable and otherwise return null. pattern is Java regular-expression text and patternFlags uses Java Pattern flag values, so clients must not assume direct JavaScript-regexp compatibility. GraphQL input nullability remains authoritative for requiredness, and validation operations remain authoritative for candidate acceptance.

Resource fileAccept metadata remains in its established locations beneath Blob or Clob property get wrappers and directly on resource action parameters. Grid resources remain authoritative for rows, columns, tabs, field sets, placement, ordering, icons, CSS, and action positions. Menu resources remain authoritative for bars, menus, sections, entries, labels, and ordering. The metadata object does not expose values, disabled reasons, authorization rules, prompt style, redirects, paging, sorting, or viewer-specific behavior. Existing operation documents that do not select metadata retain their response shape unchanged.

The remaining configuration properties are explained in more detail elsewhere:

Marshalling SPI: