Graph QL

bom/pom.xml

@@ -182,6 +182,17 @@
                 <artifactId>helidon-microprofile-cors</artifactId>
                 <version>${helidon.version}</version>
             </dependency>
+            <!-- graphQL -->
+            <dependency>
+                <groupId>io.helidon.graphql</groupId>
+                <artifactId>helidon-graphql-server</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.helidon.microprofile.graphql</groupId>
+                <artifactId>helidon-microprofile-graphql-server</artifactId>
+                <version>${helidon.version}</version>
+            </dependency>
             <!-- media -->
             <dependency>
                 <groupId>io.helidon.media</groupId>

common/common/src/main/java/io/helidon/common/FeatureCatalog.java

@@ -152,6 +152,14 @@ final class FeatureCatalog {
                     .path("WebServer", "Websocket")
                     .nativeSupported(true)
                     .nativeDescription("Server only"));
+        add("io.helidon.graphql.server",
+            FeatureDescriptor.builder()
+                    .name("GraphQL")
+                    .description("GraphQL support")
+                    .path("GraphQL")
+                    .nativeDescription("Experimental support, tested on limited use cases")
+                    .flavor(HelidonFlavor.SE)
+                    .experimental(true));
 
         /*
          * MP Modules
@@ -203,6 +211,14 @@ final class FeatureCatalog {
               "Fault Tolerance",
               "MicroProfile Fault Tolerance spec implementation",
               "FT");
+        add("io.helidon.microprofile.graphql.server",
+            FeatureDescriptor.builder()
+                    .name("GraphQL")
+                    .description("MicroProfile GraphQL spec implementation")
+                    .path("GraphQL")
+                    .nativeDescription("Experimental support, tested on limited use cases")
+                    .flavor(HelidonFlavor.MP)
+                    .experimental(true));
         add("io.helidon.microprofile.grpc.server",
             FeatureDescriptor.builder()
                     .name("gRPC Server")

dependencies/pom.xml

@@ -52,6 +52,8 @@
         <version.lib.google-api-client>1.30.11</version.lib.google-api-client>
         <version.lib.google-error-prone>2.3.3</version.lib.google-error-prone>
         <version.lib.graalvm>20.1.0</version.lib.graalvm>
+        <version.lib.graphql-java>15.0</version.lib.graphql-java>
+        <version.lib.graphql-java.extended.scalars>1.0.1</version.lib.graphql-java.extended.scalars>
         <version.lib.grpc>1.32.1</version.lib.grpc>
         <version.lib.guava>28.1-jre</version.lib.guava>
         <version.lib.h2>1.4.199</version.lib.h2>
@@ -82,6 +84,7 @@
         <version.lib.mariadb-java-client>2.6.2</version.lib.mariadb-java-client>
         <version.lib.maven-wagon>2.10</version.lib.maven-wagon>
         <version.lib.microprofile-config>1.4</version.lib.microprofile-config>
+        <version.lib.microprofile-graphql>1.0.3</version.lib.microprofile-graphql>
         <version.lib.microprofile-health>2.2</version.lib.microprofile-health>
         <version.lib.microprofile-jwt>1.1.1</version.lib.microprofile-jwt>
         <version.lib.microprofile-metrics-api>2.3.2</version.lib.microprofile-metrics-api>
@@ -579,6 +582,22 @@
                     </exclusion>
                 </exclusions>
             </dependency>
+            <dependency>
+                <groupId>org.eclipse.microprofile.graphql</groupId>
+                <artifactId>microprofile-graphql-api</artifactId>
+                <version>${version.lib.microprofile-graphql}</version>
+                <exclusions>
+                    <exclusion>
+                        <groupId>org.osgi</groupId>
+                        <artifactId>org.osgi.annotation.versioning</artifactId>
+                    </exclusion>
+                </exclusions>
+            </dependency>
+            <dependency>
+                <groupId>org.eclipse.microprofile.graphql</groupId>
+                <artifactId>microprofile-graphql-tck</artifactId>
+                <version>${version.lib.microprofile-graphql}</version>
+            </dependency>
             <dependency>
                 <groupId>org.eclipse.microprofile.jwt</groupId>
                 <artifactId>microprofile-jwt-auth-api</artifactId>
@@ -953,6 +972,16 @@
                 <artifactId>graal-sdk</artifactId>
                 <version>${version.lib.graalvm}</version>
             </dependency>
+            <dependency>
+                <groupId>com.graphql-java</groupId>
+                <artifactId>graphql-java</artifactId>
+                <version>${version.lib.graphql-java}</version>
+            </dependency>
+            <dependency>
+                <groupId>com.graphql-java</groupId>
+                <artifactId>graphql-java-extended-scalars</artifactId>
+                <version>${version.lib.graphql-java.extended.scalars}</version>
+            </dependency>
             <dependency>
                 <groupId>org.graalvm.nativeimage</groupId>
                 <artifactId>svm</artifactId>

docs/mp/graphql/01_mp_graphql.adoc

@@ -0,0 +1,223 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2019, 2020 Oracle and/or its affiliates.
+
+    Licensed 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 agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+///////////////////////////////////////////////////////////////////////////////
+
+= MicroProfile GraphQL
+:h1Prefix: MP
+:pagename: microprofile-graphql
+:description: Helidon GraphQL MicroProfile
+:keywords: helidon, graphql, microprofile, micro-profile
+
+
+The Microprofile GraphQL APIs are an extension to <<microprofile/01_introduction.adoc, Helidon MP>>
+to allow building of applications that can expose a GraphQL endpoint and optionally a link:https://github.com/graphql/graphiql[GraphiQL] API.
+
+== About the MicroProfile GraphQL Specification
+Helidon MP implements the MicroProfile GraphQL
+link:https://github.com/eclipse/microprofile-graphql[spec] version 1.0.3.
+The spec prescribes how applications can be built to expose an endpoint for GraphQL.
+GraphQL is an open-source data query and manipulation language for APIs,
+and a runtime for fulfilling queries with existing data.
+It provides an alternative, though not necessarily a replacement for REST.
+
+For more information on GraphQL see https://graphql.org/.
+
+== Maven Coordinates
+
+The <<about/04_managing-dependencies.adoc, Managing Dependencies>> page describes how you
+should declare dependency management for Helidon applications. Then declare the following dependency in your project:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.helidon.microprofile.graphql</groupId>
+    <artifactId>helidon-microprofile-graphql-server</artifactId>
+</dependency>
+----
+
+== Getting Started
+
+=== Defining your API
+
+The MicroProfile GraphQL specification defines a number of key annotations to be used when writing a GraphQL endpoint:
+
+* `@GraphQLApi` - identifies a CDI Bean as a GraphQL Endpoint
+* `@Query` - identifies a method as returning specified fields for an object or collection of entities
+* `@Mutation` - identifies a method which creates, deletes or updates entities
+
+NOTE: Please see the link:https://github.com/eclipse/microprofile-graphql[Microprofile GraphQL spec] for the full list of available annotations.
+
+For example, the following defines a GraphQL endpoint with a number of queries and mutations that work
+against a fictional `CustomerService` service and `Customer` class.
+
+[source,java]
+.Simple ContactGraphQLApi
+----
+@ApplicationScoped
+@org.eclipse.microprofile.graphql.GraphQLApi
+public class ContactGraphQLApi {
+
+    @Inject
+    private CustomerService customerService;
+
+    @org.eclipse.microprofile.graphql.Query
+    public Collection<Customer> findAllCustomers() {  <1>
+        return customerService.getAllCustomers();
+    }
+
+    @org.eclipse.microprofile.graphql.Query
+    public Customer findCustomer(@Name("customerId") int id) {  <2>
+        return customerService.getCustomer(id);
+    }
+
+    @org.eclipse.microprofile.graphql.Query
+    public Collection<Customer> findCustomersByName(@Name("name") String name) {  <3>
+        return customerService.getAllCustomers(name);
+    }
+
+    @org.eclipse.microprofile.graphql.Mutation
+    public Contact createCustomer(@Name("customerId") int id,  <4>
+                                  @Name("name") String name,
+                                  @Name("balance") float balance) {
+        return customerService.createCustomer(id, name, balance);
+    }
+}
+
+public class customer {
+    private int id;
+    @NonNull
+    private String name;
+    private float balance;
+
+    // getters and setters omitted for brevity
+}
+----
+
+<1> a query with no-arguments that will return all Customers
+<2> a query that takes an argument to return a specific Customer
+<3> a query that optionally takes a name and returns a collection of Customers
+<4> a mutation that creates a Customer and returns the newly created Customer
+
+The above would generate a GraphQL schema as shown below:
+[source,graphql]
+.Sample GraphQL Schema
+----
+type Query {
+   findAllCustomers: [Customer]
+   findCustomer(customerId: Int!): Customer
+   findCustomersByName(name: String): [Customers]
+}
+
+type Mutation {
+   createCustomer(customerId: Int!, name: String!, balance: Float!): Customer
+}
+
+type Customer {
+   id: Int!
+   name: String!
+   balance: Float
+}
+----
+
+After application startup, a GraphQL schema will be generated from your annotated API classes
+and POJO's and you will be able to access these via the URL's described below.
+
+=== Creating your entry-point
+
+As per the instructions <<mp/introduction/02_microprofile.adoc, here>> ensure you have added a
+`src/main/resources/META-INF/beans.xml` file, so the CDI implementation can pick up your classes.
+
+A `Main` class is not needed, you can configure `io.helidon.microprofile.cdi.Main` as the entry point.
+
+Optionally, you can configure a custom entry point (such as when you need custom configuration setup).
+
+[source,java]
+.Sample Entry-point
+----
+public class MyMain {
+    public static void main(String[] args) {
+        io.helidon.microprofile.cdi.Main.main(args);
+    }
+}
+----
+
+=== Building your application
+
+As part of building your application, you must create a Jandex index
+using the `jandex-maven-plugin` for all API and POJO classes that are used.
+
+[source,xml]
+.Generate Jandex index
+----
+<plugin>
+<groupId>org.jboss.jandex</groupId>
+<artifactId>jandex-maven-plugin</artifactId>
+<version>1.0.8</version>
+<executions>
+  <execution>
+    <id>make-index</id>
+  </execution>
+</executions>
+</plugin>
+----
+
+== Accessing the GraphQL end-points
+
+After starting your application you should see a message similar to the following
+indicating the GraphQL application has be started:
+
+[source,bash]
+.Sample Startup output
+----
+[Mon. Nov. 02 14:54:11 AWST 2020] INFO: io.helidon.microprofile.server.ServerCdiExtension addApplication
+     - Registering JAX-RS Application: GraphQLApplication
+----
+
+Once you access the built-in GraphiQL endpoint at `http://host:port/ui` or
+using your GraphQL client via the `http://host:port/graphql` end-point a message indicating the
+GraphQL Schema has been generated will be displayed as shown if your log level is set to `FINE`:
+
+[source,bash]
+.Sample Schema Message
+----
+[Mon. Nov. 02 14:54:16 AWST 2020] FINE: io.helidon.microprofile.graphql.server.ExecutionContext <init> - Generated schema:
+... Schema displayed here
+----
+
+.GraphQL UI
+image::mp/graphql_01_introduction_graphiql.png[GraphiQL]
+
+== Configuration Options
+
+=== MicroProfile GraphQL
+The specification defines the following configuration options:
+
+[cols="2,2,5"]
+
+|===
+|key |default value |description
+
+|`mp.graphql.defaultErrorMessage` |`Server Error` |Error message to send to caller in case of error
+|`mp.graphql.exceptionsBlackList` |{nbsp} |Array of checked exception classes that should return default error message
+|`mp.graphql.exceptionsWhiteList` |{nbsp} |Array of unchecked exception classes that should return message to caller (instead of default error message)
+
+|===
+
+These configuration options are more significant that the configuration options
+ that can be used to configure GraphQL invocation (see below).
+
+include::../../shared/graphql/configuration.adoc[]

docs/mp/introduction/01_introduction.adoc

@@ -85,17 +85,26 @@ Add support for CORS to your application using a Helidon module.
 Defines annotations that improve applications by providing support to handle error conditions (faults). 
 --
 
+//GraphQL
+[CARD]
+.GraphQL
+[icon=graphic_eq,link=mp/graphql/01_mp_graphql.adoc]
+--
+Expose GraphQL API using Microprofile GraphQL.
+--
+
 //gRPC
 [CARD]
 .gRPC
 [icon=swap_horiz,link=mp/grpc/01_mp_server_side_services.adoc]
 --
 Build gRPC servers and clients.
 --
+
 //Health Checks
 [CARD]
 .Health Checks
-[icon=favorite_outline,link=mp/health/01_introduction.adoc]
+[icon=graphic_eq,link=mp/health/01_introduction.adoc]
 --
 Expose health statuses of your applications.
 --