2. How-to guides

2.1. Run the client examples

See the README’s in the respective example directories for information on building and running the example code. The examples assume an EDG server has been configured as described in Example EDG server configuration.

2.2. Build a client library locally

2.2.1. Java

Prerequisites

Build process

lib/java/script/update

Running tests

lib/java/script/test

2.3. Use the client for GraphQL queries and mutations

The EDG server’s GraphQL schemas vary between installations and users of an installation, depending on the installation’s ontologies and what the user has access to.

Out of the box the Java client only includes types for one schema, the platform API, which does not vary between installations.

You can generate types for your server’s/user’s GraphQL endpoints by using the graphql code generation framework. It consists of library and command line interface for working with EDG GraphQL interfaces. Its primary function is to discover the available GraphQL endpoints on an EDG server and generate code for using the endpoints from various languages.

Prerequisites (all languages)

Prerequisites (Java)

Installing dependencies

graphql/script/bootstrap

The script creates a Python virtual environment in the directory graphql/venv/, which is .gitignore’d.

Running the command line

graphql/script/cli -h

The script accepts a subcommand (e.g., generate-java-client) and a variety of global and subcommand-specific options. The options can be used to specify the location of the EDG server or the credentials to access it.

Sample code

The graphql/samples/ directory contains projects for different languages targeted by the code generator. Each project contains:

  • generated code

  • a script/generate-samples script that invokes the CLI to generate the code. The script assumes the default EDG parameters, which correspond to those in the edg-samples Docker image and have the same port and credentials configuration as that required by the client examples.

  • a simple entry point (main) that utilizes the generated code

  • project configuration, such as a Maven pom.xml

See the README’s in each language subdirectory for more information.

2.4. Configure the Java client library using a Java servlet context

The Java client library can be configured via parameters derived from a Java servlet context. This is a common scenario for EDGX.

Set servlet context parameters

Servlet context parameters can be set in several places, but it is usually desirable to separate the code for a web application (packaged in a .war) from its configuration.

In Tomcat you can define servlet context parameters in an XML file. This file is placed in the directory /conf/Catalina/localhost. The file name corresponds to the name of your webapp. For example, if your .war file is named myapp.war or you have a $CATALINA_HOME/webapps/myapp directory, then the file name should be myapp.war. See the Tomcat documentation for more information.

Below is an example context XML file that sets Java client properties.

<Context>
    <Parameter name="edg.client.password" value="password32"
               override="false"/>
    <Parameter name="edg.client.serverBaseUrl" value="http://localhost:8080"
               override="false"/>
    <Parameter name="edg.client.username" value="Admin_user"
               override="false"/>
</Context>

See the Configuration properties reference for more information on known properties.

Configure the client with the servlet context parameters

The ClientConfiguration builder can set properties from a commons-configuration2 Configuration instance. Glue code from commons-configuration is used to adapt servlet context parameters into a Configuration. For example:

ClientConfiguration.builder()
  .setFromConfiguration(new ServletContextConfiguration(getServletContext).subset(ClientConfiguration.KEY_PREFIX))
  .build()

ClientConfiguration.KEY_PREFIX is a constant for edg.client.

The same approach can be used for other Configuration adapters from commons-configuration, such as ServletConfiguration (for servlet init parameter) or PropertiesConfiguration (for .properties files).