.. raw:: html

    <style>
        pre { min-width: 80em; }
    </style>

.. _tutorials:

Tutorials
=========

Developing an EDG-AF app with Java servlets
-------------------------------------------

In this tutorial you will:

#. Create an EDG importer in Java using the EDG App Framework
#. Integrate the importer into the EDG user interface

The code is based on the Java servlet example in ``examples/java/servlet``.

The tutorial assumes you are familiar with Java, Java servlet programming, and Maven projects.

**Create a Maven project for the EDG-AF app**

Create a new Maven project with the usual structure (src/main/java, et al.) and a pom.xml. The example pom.xml can be used as a guide.

.. literalinclude:: ../../example/java/servlet/pom.xml
   :language: xml

The example uses the EDG-AF :ref:`maven-artifacts`.

**Implement the servlet**

The following section contains the complete example from ``example/java/servlet``, with inline explanatory comments. 
This file would be put in the appropriate directory of your project's ``src/main/java``.

.. literalinclude:: ../../example/java/servlet/src/main/java/org/topbraidlive/app/example/java/servlet/ExampleAppServlet.java
   :language: java

**Set up the servlet in web.xml**

A ``web.xml`` in ``src/main/webapp/WEB-INF`` maps URL paths to the servlet.

.. literalinclude:: ../../example/java/servlet/src/main/webapp/WEB-INF/web.xml
   :language: xml

**Run the web application**

During development you can run the web application using Maven::

    mvn org.eclipse.jetty:jetty-maven-plugin:run

To deploy the web application in production you will build a ``.war`` file with::

    mvn package

and copy it to your servlet container's ``webapps`` directory.

With the web application running you should be able to access its configuration at `http://localhost:8081/app-example/configuration <http://localhost:8081/app-example/configuration>`_.

**Install the app into EDG**

The EDG App Framework provides a command line interface (CLI) to install apps into EDG-AF. The simplest way to run this command is by executing::

    framework/script/cli

from the root of the ``EDG-AF`` repository. This will build the framework Maven projects, including an assembly .jar for the CLI.

The example app directories contain ``script/install`` scripts that invoke the framework CLI using a command line like::

    framework/script/cli upload-zip --app-base-url http://localhost:8081/app-example --edg-base-url http://localhost:8080/ --edg-password password32 --edg-username Admin_user

See the :ref:`glossary` for definitions of the command line options, such as *app base URL*.

The installation process creates an EDG project that defines a new importer for Data Graphs. This appears as a new section under the Import tab of a Data Graph asset collection.

**Create a new Data Graph project for testing**

In your web browser, navigate to the Data Graphs asset collection type. (You can click to enlarge the image.)

.. thumbnail:: images/tutorials-java-servlet-data-graphs.png

Then create a new Data Graph named ``test``.

.. thumbnail:: images/tutorials-java-servlet-create-data-graph.png

After creating the ``test`` Data Graph you will be redirected to the Import tab, as shown in the image below.

.. thumbnail:: images/tutorials-java-servlet-import-tab.png

You will see the "Example importer" defined by the app as the first section in the tab.

**Initiate the import**

Click on the "Example importer" link under the Import tab. This opens up a new page which contains an ``<iframe>`` to the EDG-AF app's URL ``http://localhost:8081/app-example/importer/example``.

.. thumbnail:: images/tutorials-java-servlet-importer-form.png

In a real importer this page would include an HTML form or similar mechanism for accepting inputs to the import process. The example has no visible inputs, only a submit button to initiate the import.

As noted in the servlet Java, the form contains hidden inputs such as the current ``projectGraph``, which will be the target of the import.

Click on the submit button to initiate the import.

**View the importer results**

The example HTML form POSTs to an action URL on the EDG-AF app. The EDG App Framework dictates that the importer page ``/app-example/importer/example`` must be answered by the EDG-AF app. Beyond that there are no constraints on how the app works. Within the confines of the ``<iframe>`` the app can submit a form to any URL, use JavaScript, or communicate between the browser and the app using WebSockets. The latter is the standard approach to displaying progress indicators.

The results of the form POST are shown in the image.

.. thumbnail:: images/tutorials-java-servlet-importer-result.png