How-to guides
=============

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 :ref:`example-edg-server-configuration`.


Build a client library locally
------------------------------

Java
++++

**Prerequisites**

* [Maven](https://maven.apache.org/)
* JDK 11+ such as [AdoptOpenJDK](https://adoptopenjdk.net/)

**Build process**

::

    lib/java/script/update

**Running tests**

::

    lib/java/script/test


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)**

* `Python 3 <https://www.python.org/>`_ including ``venv`` support

**Prerequisites (Java)**

* `Ruby 2.1+ <https://www.ruby-lang.org>`_ with ``bundle`` and ``gem``

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


.. _servlet-context-configuration:

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 :ref:`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 <https://commons.apache.org/proper/commons-configuration/>`_ ``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).