################# Developer's guide ################# This REST API was developed in **Java 17** from scratch, meaning that it is not based on a pre-existing tool. It enables the retrieval of molecule structure/representation files from a custom S3 storage containing data coming from different communities. !!!! Dependencies required ===================== This API relies on several dependencies : * **To build the application :** * `Spring Boot Starter Web`_ ``3.3.3`` : Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container. * `Spring Data JPA`_ ``3.3.3`` : Spring Data module for JPA repositories. * `AWS SDK For Java`_ ``2.28.2`` : Library for communicating with the S3 Storage. * `Lombok`_ ``>=1.18.34`` : Java library that provides annotations to simplify Java development by automating the generation of boilerplate code. Used for the automatic generation of getters and setters methods. * `JSON`_ ``20240303`` : Package that implements JSON encoders/decoders in Java. * `Microservice Core Lib`_ ``1.0.1`` : Custom Java library with factorized code common between microservices from the MetaboCloud project. * `Openapi Generator`_ ``7.8.0`` : OpenAPI Generator allows generation of API client libraries, server stubs, documentation and configuration automatically, given an OpenAPI Specification. * `Jackson Databind Nullable`_ ``0.2.6`` : JsonNullable wrapper class and Jackson module to support fields with meaningful null values. * **To test the application :** * `Spring Boot Starter Test`_ ``3.3.3`` : Starter for testing Spring Boot applications with libraries including JUnit Jupiter, Hamcrest and Mockito. * `Awaitility`_ ``>=4.2.2`` : A Java DSL for synchronizing asynchronous operations * **To build the documentation :** * `Springdoc`_ ``2.6.0`` : Java library that helps to automate the generation of API documentation for spring boot projects. .. _Spring Boot Starter Web: https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-web .. _Spring Data JPA: https://mvnrepository.com/artifact/org.springframework.data/spring-data-jpa .. _AWS SDK For Java: https://mvnrepository.com/artifact/software.amazon.awssdk/aws-sdk-java .. _Lombok: https://mvnrepository.com/artifact/org.projectlombok/lombok .. _JSON: https://mvnrepository.com/artifact/org.json/json .. _Microservice Core Lib: https://unh-pfem-gitlab.ara.inrae.fr/pfem/libs/pfem-microservices-core-lib .. _Openapi Generator: https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin .. _Jackson Databind Nullable: https://mvnrepository.com/artifact/org.openapitools/jackson-databind-nullable .. _Spring Boot Starter Test: https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-test .. _Awaitility: https://mvnrepository.com/artifact/org.awaitility/awaitility .. _Springdoc: https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui .. note:: All theses dependencies, listed in the ``pom.xml`` file, are installed and managed by Maven during the application compilation. !!!! Unit and functional testing =========================== Unit and functional tests are in the ``src/test/java`` directory. To run all tests, use the following command : .. code-block:: console $ mvn test .. note:: You can launch specific tests by using the argument ``-Dtest``. .. code-block:: console $ mvn test -Dtest= Where ```` is the file containing the tests you want to run without its extension (e.g. CompoundsControllerTest) !!!! Documentation generation ======================== To generate the **ReadTheDocs** documentation, the following tool is required : * `Sphinx`_ ``7.4.7`` : Tool to build the **ReadTheDocs** documentation. * `Sphinx-rtd-theme`_ ``2.0.0`` : Sphinx extension to use the "Read the Docs" theme. * `Sphinx Tabs`_ ``3.4.5`` : Sphinx extension to create tabbed content when building HTML. .. _Sphinx: https://www.sphinx-doc.org/en/master/ .. _Sphinx-rtd-theme: https://sphinx-rtd-theme.readthedocs.io/en/stable/ .. _Sphinx Tabs: https://sphinx-tabs.readthedocs.io/en/latest/ .. note:: They can be installed using the following command : .. code-block:: console $ pip install sphinx sphinx-rtd-theme sphinx-tabs Then, once Sphinx and its extensions are installed, the documentation can be generated by using the following command : .. code-block:: console $ sphinx-build -M html doc build The documentation is then generated in HTML and can be accessed from the ``build/html`` folder. !!!! S3 Storage organisation ======================= The InDex REST API is associated with a **S3 Storage** containing all the files than can be retrieved. The S3 Storage is hosted by the `Clermont Auvergne Mesocentre`_. .. _Clermont Auvergne Mesocentre: https://mesocentre.uca.fr/ Currently, this S3 Storage contains files coming only from one community ``chebi``. **Two types of files are available :** * ``PNG images`` of molecules in three different sizes (50 x 50 px corresponding to ``small``, 350 x 350 px corresponding to ``medium`` and 700 X 700 px corresponding to ``large``) * ``MOL files`` of molecules **The architecture of the S3 Storage then contains several layers :** * First layer - **Format of the file** : ``png`` and ``mol`` * Second layer - **Origin of the image** : the community from which the files come (e.g. ``chebi``) * Third layer - **Size of the image** : three categories which are ``small`` (50 x 50 px), ``medium`` (350 x 350 px) and ``large`` (700 x 700 px) => only for ``png`` format * Fourth layer - **File name** : * **PNG image** are named from the ``InChI Key`` of the molecule, the ``image size`` and the ``image format`` *(e.g. AFENDNXGAFYKQO-UHFFFAOYSA-N_50.png, YNPGYMZVNLIZLD-BQFKTQOQSA-N_350.png, KMTDMTZBNYGUNX-UHFFFAOYSA-N_700.png)* * **MOL file** are named from the ``InChI Key`` of the molecule, and the ``file format`` *(e.g. AFENDNXGAFYKQO-UHFFFAOYSA-N.mol, YNPGYMZVNLIZLD-BQFKTQOQSA-N.mol, KMTDMTZBNYGUNX-UHFFFAOYSA-N.mol)* **Structure of the S3 Storage :** *(The list of files is just an example and is of course non-exhaustive)* .. code-block:: console . ├── png │   └── chebi │      ├── large │       │   ├── AFENDNXGAFYKQO-UHFFFAOYSA-N_700.png │       │   ├── KMTDMTZBNYGUNX-UHFFFAOYSA-N_700.png │       │   └── YNPGYMZVNLIZLD-BQFKTQOQSA-N_700.png │       ├── medium │       │   ├── AFENDNXGAFYKQO-UHFFFAOYSA-N_350.png │       │   ├── KMTDMTZBNYGUNX-UHFFFAOYSA-N_350.png │       │   └── YNPGYMZVNLIZLD-BQFKTQOQSA-N_350.png │       └── small │       ├── AFENDNXGAFYKQO-UHFFFAOYSA-N_50.png │       ├── KMTDMTZBNYGUNX-UHFFFAOYSA-N_50.png │       └── YNPGYMZVNLIZLD-BQFKTQOQSA-N_50.png └── mol └── chebi    ├── AFENDNXGAFYKQO-UHFFFAOYSA-N.mol    ├── KMTDMTZBNYGUNX-UHFFFAOYSA-N.mol    └── YNPGYMZVNLIZLD-BQFKTQOQSA-N.mol !!!! Code organisation ================= The structure of the InDex REST API follows the Standard Directory layout created by **Maven**. .. code-block:: console . ├── build_docker_image.sh ├── doc # Folder with the source of the documentation ├── Dockerfile ├── LICENSE ├── Makefile ├── pom.xml ├── README.md └── src # Folder with the code source of the application    ├── main    │   ├── java   │   │   └── fr    │   │   └── metabocloud   │   │   └── index    │   │   ├── Application.java    │   │   ├── config    │   │   │   └── S3Config.java    │   │   ├── controllers    │   │   │   ├── core    │   │   │   │ ├── AboutController.java    │   │   │   │ └── RootController.java    │   │   │   └── tool    │   │   │     └── CompoundsController.java    │   │   ├── exception    │   │   │   ├── FileNotFoundException.java    │   │   │   └── GlobalExceptionHandler.java    │   │   ├── implementation    │   │   │   ├── builders    │   │   │   │   ├── ImagePathBuilder.java    │   │   │   │   ├── MolPathBuilder.java    │   │   │   │   ├── PathBuilder.java    │   │   │   │   └── PngPathBuilder.java    │   │   │   ├── CompoundsImpl.java    │   │   │   ├── directors    │   │   │   │   ├── PathDirector.java    │   │   │   │   └── SimplePathDirector.java    │   │   │   ├── readers    │   │   │   │   ├── MolReader.java    │   │   │   │   ├── PngReader.java    │   │   │   │   └── Reader.java    │   │   │   └── S3Service.java    │   │   └── models    │   │   ├── Community.java    │   │   ├── Headers.java    │   │   ├── ImageSize.java    │   │   ├── IndexErrorMessages.java    │   │   └── OutputType.java    │   └── resources    │   ├── application-mesocentre.properties    │   ├── application-pfem.properties    │   ├── application.properties    │   ├── conf.properties    │   ├── infos.properties    │   ├── s3storage.properties    │   └── static    │   └── metabocloud-index.yaml    └── test    ├── java    │   └── fr    │   └── metabocloud    │   └── index    │   ├── ApplicationTests.java    │   ├── controllers    │   │   ├── core    │   │   │   ├── AboutControllerTest.java    │   │   │   └── RootControllerTest.java    │   │   └── tool    │   │   └── CompoundsControllerTest.java    │   ├── data    │   │   ├── models    │   │   │   └── Constants.java   │   │   ├── providers    │   │   │   └── chebi    │   │   │   ├── MolProvider.java    │   │   │   └── PngProvider.java    │   │   └── stub    │   │   ├── chebi    │   │   │   ├── MolStub.java    │   │   │   └── PngStub.java    │   │   └── InchiKeyStub.java    │   ├── exception    │   │   └── FileNotFoundExceptionTest.java    │   └── implementation    │   ├── builders    │   │   └── PathBuilderTest.java    │   ├── CompoundsImplTest.java    │   ├── directors    │   │   └── PathDirectorTest.java    │   ├── readers    │   │   ├── MolReaderTest.java    │   │   ├── PngReaderTest.java    │   │   └── ReaderTest.java    │   └── S3ServiceTest.java    └── resources    ├── compounds    │   ├── mol    │   │   └── chebi    │   │   ├── Caffeine.mol    │   │   ├── Caffeine_without_metadata.mol    │   │   ├── Cholesterol.mol    │   │   ├── Cholesterol_without_metadata.mol    │   │   ├── D-Glucose.mol    │   │   ├── Sphinganine1Phosphate.mol    │   │   └── VitaminE.mol    │   └── png    │   └── chebi    │   ├── large    │   │   ├── Caffeine.png    │   │   ├── Cholesterol.png    │   │   ├── D-Glucose.png    │   │   ├── Sphinganine1Phosphate.png    │   │   └── VitaminE.png    │   ├── medium    │   │   ├── Caffeine.png    │   │   ├── Cholesterol.png    │   │   ├── D-Glucose.png    │   │   ├── Sphinganine1Phosphate.png    │   │   └── VitaminE.png    │   └── small    │   ├── Caffeine.png    │   ├── Cholesterol.png   │   ├── D-Glucose.png    │   ├── Sphinganine1Phosphate.png    │   └── VitaminE.png └── confTest.properties **build_docker_image.sh** Script to build the Docker image in local ``doc`` Directory containing the source of the documentation **pom.xml** XML File at the root of the repository that contains information about the project, configuration details and dependencies needed, used by Maven to build the project. ``src/main/java`` : Source code of the Application * *fr.metabocloud.index* : * **Application.java** : Enables to run the application using the Web framework SpringBoot. * *fr.metabocloud.index.controllers.config* : Package containing configuration classes * **S3Config** : Configure the S3 Storage. * *fr.metabocloud.index.controllers.core* : Package containing controllers associated to the REST API metadata * **AboutController.java** : Controller for the endpoint "/about" to retrieve the metadata associated to the REST API. * **RootController** : Controller for the root "/" of the REST API. * *fr.metabocloud.index.controllers.tool* : Package containing controllers associated to the tool itself * **CompoundsController.java** : Controller for the endpoint "/compounds/{inchiKey}.{format}" which retrieve molecule structure/representation files from a custom S3 storage containing data coming from different communities. * *fr.metabocloud.index.exception* : Package managing exceptions that can be thrown by the REST API * **FileNotFoundException.java** : Exception thrown when a file is not found in the S3 Storage. * **GlobalExceptionHandler.java** : Global handler which manages exceptions for all controllers. * *fr.metabocloud.index.implementation* : Package containing classes which implement methods to process the received requests * **CompoundsImpl.java** : Implementation for the endpoint "/compounds/{inchiKey}.{format}". * **S3Service.java** : Service to communicate with the S3 Storage. * *fr.metabocloud.index.implementation.builders* : Package regrouping classes builders * **ImagePathBuilder.java** : Abstract sub-class of PathBuilder representing a image path builder which builds the path of an image after checking the validity of the required attributes. * **MolPathBuilder.java** : Sub-class of ImagePathBuilder representing a MOL path builder which builds a path for MOL files. * **PathBuilder.java** : Abstract parent class that enables the construction of a file path after validating the required attributes. * **PngPathBuilder.java** : Sub-class of ImagePathBuilder representing a PNG path builder which builds a path for PNG images. * *fr.metabocloud.index.implementation.directors* : Package regrouping classes directors * **PathDirector.java** : Interface for a director that builds paths for retrieving files. * **SimplePathDirector.java** : Sub-class of PathDirector which implements a director building paths for MOL and PNG files. * *fr.metabocloud.index.implementation.readers* : Package regrouping classes readers * **MolReader.java** : Sub-class of Reader which retrieves a MOL file and extract its metadata. * **PngReader.java** : Sub-class of Reader which retrieves a PNG image and extract its metadata. * **Reader.java** : Abstract parent class which retrieves a file and extract its metadata. * *fr.metabocloud.index.models* : Package containing models * **Community.java** : Enumeration representing the different communities available for retrieving data. * **Headers.java** : Enumeration representing the various HTTP header keys and values used in the application. * **ImageSize.java** : Enumeration representing the available image sizes for the PNG images. * **IndexErrorMessages.java** : Enumeration representing specific error messages that may be returned by the application. * **OutputType.java** : Enumeration representing the types of output that can be requested by the application. ``src/main/resources :`` Resources associated to the application * **application-mesocentre.properties** : Configuration file of the application with the properties required to run it on the MetaboCloud production. * **application-pfem.properties** : Configuration file of the application with the properties required to run it on the PFEM dev server. * **application.properties** : Configuration file of the application with the properties required to run it in local. * **infos.properties** : Configuration file containing the metadata associated to the REST API. * **s3storage.properties** : Configuration file containing the properties required to set up the S3 Storage. * ``static/`` : Folder containing the static files * **metabocloud-index.yaml** : OpenAPI specification file describing the InDex REST API. ``src/test/java`` : Contain the Java sources of the unit tests * *fr.metabocloud.index* : * **ApplicationTests.java** : Test on the main application * *fr.metabocloud.index.controllers.core* : Package containing tests on controllers associated to the REST API metadata * **AboutControllerTest.java** : Tests on the controller for the endpoint "/about" to retrieve the metadata associated to the REST API. * **RootControllerTest** : Tests on the controller for the root "/" of the REST API. * *fr.metabocloud.index.controllers.index* : Package containing tests on controllers associated to the tool itself * **CompoundsControllerTest.java** : Tests on the controller for the endpoint "/compounds/{inchiKey}.{format}". * *fr.metabocloud.index.data.models* : Package containing models used for tests * **Constants.java** : Model with all constants used in the different tests. * *fr.metabocloud.index.data.providers.chebi* : Package containing the providers used to import data coming from ChEBI into tests * **MolProvider.java** : Provider specific for MOL files. * **PngProvider.java** : Provider specific for PNG images. * *fr.metabocloud.index.data.stub* : Package containing classes which store the common input between all communities used in tests * **InchiKeyStub.java** : Store InChI Keys of compounds. * *fr.metabocloud.index.data.stub.chebi* : Package containing classes which store the input coming from ChEBI used in tests * **MolStub.java** : Store data required to test for MOL files retrieval. * **PngStub.java** : Store data required to test for PNG images retrieval. * *fr.metabocloud.index.exception*: Package containing tests on the custom exceptions that can be thrown by the REST API * **FileNotFoundExceptionTest.java** : Tests on the FileNotFound custom exception. * *fr.metabocloud.index.implementation*: Package containing tests on implemented methods to process the received requests * **CompoundsImplTest.java** : Tests on the implementation for the endpoint "/compounds/{inchiKey}.{format}". * **S3ServiceTest.java** : Tests on the service used to communicate with the S3 Storage. * *fr.metabocloud.index.implementation.builders*: Package containing tests on the builder classes * **PathBuilderTest.java** : Tests on all the PathBuilder classes. * *fr.metabocloud.index.implementation.directors*: Package containing tests on the director classes * **PathDirectorTest.java** : Tests on all the PathDirector classes. * *fr.metabocloud.index.implementation.readers*: Package containing tests on the reader classes * **MolReaderTest.java** : Tests on the MolReader class. * **PngReaderTest.java** : Tests on the PngReader class. * **ReaderTest.java** : Tests on all the Reader classes. ``src/test/resources`` : Host the files that are not Java sources but are necessary to run the tests. * ``compounds/`` : Folder containing the expected output files .. note:: A ``Controller`` is a class that implements operations defined by the API. It will receive the request, process it and send back the response. .. note:: The ``highlight`` is a source folder, the *italic* a package, and the **bold** a file. .. image:: uml/InDex_class_diagram.png :alt: UML class diagram of InDex REST API