Classes documentation --------------------- Here you can found technical documentation about the implementation code of this API. * `Config Package`_ * `Controllers Package`_ * `Exception Package`_ * `Implementation Package`_ * `Implementation.Builders Package`_ * `Implementation.Directors Package`_ * `Implementation.Factories Package`_ * `Implementation.Readers Package`_ * `Implementation.Services Package`_ * `Implementation.Utils Package`_ * `Models Package`_ !!!! Config Package ============== The ``Config`` package contains configuration classes. .. image:: uml/classes/images/Config.png .. dropdown:: S3Config Class :icon: telescope-fill :color: primary The ``S3Config`` class is a configuration class responsible **for setting up the S3 client used to communicate with a custom S3 storage**. It defines a Spring Bean for the S3Client that is configured using properties loaded from an external properties file (``s3storage.properties``). The ``s3storage.properties`` file should include the following properties for configuring the S3 client : .. code-block:: properties aws.access.key= aws.secret.key= aws.region= aws.s3.endpointUrl= aws.s3.bucketName= The class includes **one** public method : .. dropdown:: ``s3Client`` - Configures a Spring Bean for the S3Client :icon: gear The ``s3Client`` method **creates an S3 client bean** configured with credentials and properties retrieved from the ``s3storage.properties`` file. It follows these steps : 1. **Retrieve credentials** such as the S3 access key and secret key from the environment properties. 2. **Build the S3 Client** using the retrieved credentials, region, and endpoint URL to create and configure an S3Client instance. 3. **Return the S3 Client** as a Spring Bean. This method requires **one** parameter : * ``env`` : The ``Environment`` object used to access the properties defined in the ``s3storage.properties`` file. It returns a configured ``S3Client`` instance, ready to communicate with the specified S3 storage. !!!! Controllers Package =================== The ``Controller`` package contains controllers used to handle HTTP request. .. image:: uml/classes/images/Controllers.png .. dropdown:: CompoundsController Class :icon: telescope-fill :color: primary The ``CompoundsController`` class is a SpringBoot Controller responsible for handling HTTP GET requests to the ``/compounds`` endpoint. It **retrieves files** from S3 Storage, based on the parameters provided in the request. This controller delegates the processing of these requests to the ``CompoundsService`` service, and it returns the appropriate response. It has **two** variables : * ``logger`` : The local logger. * ``service`` : An instance of ``CompoundsService`` service, responsible for processing requests to retrieve files from S3 storage. The class contains **one** constructor : .. dropdown:: ``CompoundsController`` - Instantiates the controller with the necessary dependencies :icon: gear The ``CompoundsController`` constructor is used to **instantiate the service** that will process requests to retrieve files from S3 storage. It initialize the ``service`` variable with the provided CompoundsService instance. The constructor requires **one** parameter : * ``service`` : An instance of the ``CompoundsService`` service, which handles the logic for retrieving files. It doesn’t return anything. It also includes **one** public method : .. dropdown:: ``getFile`` - Handle GET requests to retrieve a file based on the specified parameters. :icon: gear The ``getFile`` public method handles HTTP GET requests directed to the ``/compounds`` endpoint. It **retrieves either a MOL file or a PNG image** associated with a chemical compound along with **its metadata**, based on the parameters provided. The retrieved file can be returned either as either a direct resource (the actual file content) or as a URL pointing to the file in S3 storage. It follows these steps : 1. **Initialize Response Headers** : Initializes the necessary HTTP headers for the response. 2. **Retrieve the Requested File** : Depending on the format parameter (``mol`` or ``png``), the method delegates to the appropriate service method (``getMolFile`` or ``getPngImage``). If an invalid format is provided, an ``InvalidFormatException`` is thrown. 3. **Return the Resource** : If the requested file is found, the method returns the *resource along with the generated headers*. If the file is not found, a ``FileNotFoundException`` is thrown. This method requires **five** parameters : * ``inchiKey`` : The InChI Key of the compound. * ``format`` : The format of the file to retrieve (“mol” or “png”). * ``community`` : The community from which to retrieve the file (“chebi”). * ``size`` : The size of the image - “small”, “medium”, or “large” (only applicable for PNG format). * ``outputType`` : The desired output type (“resource” or “url”). It returns an HTTP response containing the requested file as a resource or URL, along with associated metadata formatted in the headers. * The metadata associated with each **MOL file** coming from the ``chebi`` community are : .. code-block:: X-Metadata-Chebi-Id : XXXX # The ChEBI ID X-Metadata-Creation-Date : YYYY-MM-DD # The date on which the MOL file was stored in the S3 X-Metadata-Data-License : Creative Commons License (CC BY 4.0) # The MOL file license X-Metadata-Data-Source : Chemical Entities of Biological Interest (ChEBI) Database # The MOL file provenance * The metadata associated with each **PNG image** coming from the ``chebi`` community are : .. code-block:: X-Metadata-Chebi-Id : XXXX # The ChEBI ID X-Metadata-Creation-Date : YYYY-MM-DD # The date on which the MOL file was stored in the S3 X-Metadata-Data-License : Creative Commons License (CC BY 4.0) # The MOL file license X-Metadata-Data-Source : Chemical Entities of Biological Interest (ChEBI) Database # The MOL file provenance X-Metadata-Image-Size : XXX x XXX px # The image size (in pixels) !!!! Exception Package ================= The ``Exception`` package contains exceptions that can be thrown by the application. .. image:: uml/classes/images/Exception.png .. dropdown:: FileNotFoundException Class :icon: telescope-fill :color: primary The ``FileNotFoundException`` class is a custom exception used to indicate that a requested file was not found in the S3 storage. It is thrown when an attempt to retrieve a file fails because the file does not exist in the storage system. It has **one** variable : * ``serialVersionUID`` : The default serial version UID used for serialization. The class includes **one** constructor : .. dropdown:: ``FileNotFoundException`` - Instantiates the exception with a specified detail message :icon: gear The constructor **initializes** the exception with a detail message explaining the reason for the exception. The constructor requires **one** parameter : * ``errorMessage``: A ``String`` containing the detail message that explains why the exception is thrown. It doesn’t return anything. .. dropdown:: InteractionS3Exception Class :icon: telescope-fill :color: primary The ``InteractionS3Exception`` class is a custom exception used to indicate that an error related to the S3 storage occurred. It is thrown when an error happened during an interaction with the S3 storage. It has **one** variable : * ``serialVersionUID`` : The default serial version UID used for serialization. The class includes **one** constructor : .. dropdown:: ``InteractionS3Exception`` - Instantiates the exception with a specified detail message :icon: gear The constructor **initializes** the exception with a detail message explaining the reason for the exception. The constructor requires **one** parameter : * ``errorMessage``: A ``String`` containing the detail message that explains why the exception is thrown. It doesn’t return anything. .. dropdown:: InvalidCommunityException Class :icon: telescope-fill :color: primary The ``InvalidCommunityException`` class is a custom exception that is thrown when an **invalid community** is requested. It contains **one** variable : * ``serialVersionUID``: The default serial version UID used for serialization. The class defines **one** constructor : .. dropdown:: ``InvalidCommunityException`` - Instantiates the exception with a specified detail message :icon: gear The constructor **initializes** the exception with a detail message explaining the reason for the exception. This constructor requires **one** parameter : * ``errorMessage``: A ``String`` containing the detail message that explains why the exception is thrown. It doesn’t return anything. .. dropdown:: InvalidFormatException Class :icon: telescope-fill :color: primary The ``InvalidFormatException`` class is a custom exception that is thrown when an **invalid format** is requested. It contains **one** variable : * ``serialVersionUID``: The default serial version UID used for serialization. The class defines **one** constructor : .. dropdown:: ``InvalidFormatException`` - Instantiates the exception with a specified detail message :icon: gear The constructor **initializes** the exception with a detail message explaining the reason for the exception. This constructor requires **one** parameter : * ``errorMessage``: A ``String`` containing the detail message that explains why the exception is thrown. It doesn’t return anything. .. dropdown:: InvalidImageSizeException Class :icon: telescope-fill :color: primary The ``InvalidImageSizeException`` class is a custom exception that is thrown when an **invalid image size** is requested. It contains **one** variable : * ``serialVersionUID``: The default serial version UID used for serialization. The class defines **one** constructor : .. dropdown:: ``InvalidImageSizeException`` - Instantiates the exception with a specified detail message :icon: gear The constructor **initializes** the exception with a detail message explaining the reason for the exception. This constructor requires **one** parameter : * ``errorMessage``: A ``String`` containing the detail message that explains why the exception is thrown. It doesn’t return anything. .. dropdown:: InvalidOutputTypeException Class :icon: telescope-fill :color: primary The ``InvalidOutputTypeException`` class is a custom exception that is thrown when an **invalid output type** is requested. It contains **one** variable : * ``serialVersionUID``: The default serial version UID used for serialization. The class defines **one** constructor : .. dropdown:: ``InvalidOutputTypeException`` - Instantiates the exception with a specified detail message :icon: gear The constructor **initializes** the exception with a detail message explaining the reason for the exception. This constructor requires **one** parameter : * ``errorMessage``: A ``String`` containing the detail message that explains why the exception is thrown. It doesn’t return anything. .. dropdown:: GlobalExceptionHandler Class :icon: telescope-fill :color: primary The ``GlobalExceptionHandler`` class is **a global exception handler** for all controllers in the application. It handles specific exceptions that may occur during the execution of controller methods, providing a centralized mechanism for error handling and consistent responses across the application. It has **one** variable : * ``logger`` : The local logger The class includes **three** exception handling methods : .. dropdown:: ``handleInvalidParameterException`` - Handles Invalid*Exception exceptions. :icon: gear This method handles ``InvalidCommunityException``, ``InvalidFormatException``, ``InvalidOutputTypeException`` and ``InvalidOutputTypeException`` exceptions that are thrown by any controller method in the application. It **returns a HTTP 400 Bad Request response status** along with an error message. It logs the exception with a message indicating a 400 - Bad Request status and returns the exception message in the HTTP response. The method requires **one** parameter : * ``ex`` : The exception instance that was thrown. It returns an HTTP 400 Bad Request response status along with an error message. .. dropdown:: ``handleFileNotFoundException`` - Handles FileNotFoundException exceptions. :icon: gear This method handles ``FileNotFoundException`` exceptions that are thrown by any controller method in the application. It **returns a HTTP 404 Not Found response status** along with an error message. It logs the exception with a message indicating a 404 - Not Found status and returns the exception message in the HTTP response. The method requires **one** parameter : * ``ex`` : The ``FileNotFoundException`` instance that was thrown. It returns a HTTP 404 Not Found response status along with an error message. .. dropdown:: ``handleInteractionS3Exception`` - Handles InteractionS3Exception exceptions. :icon: gear This method handles ``InteractionS3Exception`` exceptions that are thrown by any controller method in the application. It **returns a HTTP 500 Internal Error response status** along with an error message. It logs the exception with a message indicating a 500 - Internal Error status and returns the exception message in the HTTP response. The method requires **one** parameter : * ``ex`` : The ``InteractionS3Exception`` instance that was thrown. It returns a HTTP 500 Internal Error response status along with an error message. !!!! Implementation Package ====================== The ``Implementation`` package contains the core of the application. Implementation.Builders Package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``Implementation.Builders`` package contains the builder classes. .. image:: uml/classes/images/ImplementationBuilders.png Implementation.Builders.Path Package ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``Implementation.Builders.Path`` package contains the builders used to build the file path. .. dropdown:: PathBuilder Abstract Class :icon: telescope-fill :color: primary ``PathBuilder`` is an abstract class designed to **build the path** of a file after **validating** the required attributes. It has two direct subclasses, ``ImagePathBuilder`` and ``MolPathBuilder``, and one indirect subclass, ``PngPathBuilder``, derived through ``ImagePathBuilder``. It has **three** variables : * ``logger`` : The local logger. * ``community`` : The community to which the requested object belongs (e.g. chebi), associated with a Getter method. * ``inchiKey`` : The InChI Key associated with the molecule wanted to be retrieved, associated with a Getter method. The class includes **one** public abstract method, implemented in the subclasses : .. dropdown:: ``getResult`` - Builds and returns the path associated to a file :icon: gear The method ``getResult`` **builds the path** which will be associated to a file based on the set attributes. It is implemented in : * `MolPathBuilder Class`_ : To build the path for a MOL file. * `PngPathBuilder Class`_ : To build the path for a PNG image. It also includes **two** public methods : .. dropdown:: ``setCommunity`` - Validates and sets the community to which the requested object belongs :icon: gear The ``setCommunity`` method **sets the ``community`` attribute** after **validating** its value. It follows these steps : 1. Retrieve the list of all possible communities from the ``Community`` enum. 2. Check if the provided community exists in this list. 3. Set the ``community`` attribute with the provided value. This method requires **one** parameter : * ``community`` : The community (e.g., chebi) as a ``String``. It doesn’t return anything. .. dropdown:: ``setInchiKey`` - Validates and sets the InChI Key associated with the desired molecule :icon: gear The ``setInchiKey`` method **sets the ``inchiKey`` attribute** after **validating** its value. It follows these steps : 1. Compile a pattern the ``inchiKey`` attribute must match. 2. Check if the provided InChI Key matches the regular expression. 3. Set the ``inchiKey`` attribute with the provided value. This method requires **one** parameters : * ``inchiKey`` : The InChI Key as a ``String``. It doesn’t return anything. .. dropdown:: ImagePathBuilder Abstract Class (Subclass of PathBuilder Abstract Class) :icon: telescope-fill :color: primary The ``ImagePathBuilder`` abstract class is a subclass of the ``PathBuilder`` abstract class. It is responsible for **building the path for an image** after **validating** the required attributes. It has **two** variables : * ``sizeLabel`` : The label indicating the image size to be retrieved (small, medium or large), associated with a Getter method. * ``sizePixel`` : The image size in pixels corresponding to the label (50, 350 or 700), associated with a Getter method. The class includes **one** public method : .. dropdown:: ``setImageSize`` - Validates and sets the size label and pixel for an image :icon: gear The ``setImageSize`` method **sets the ``sizeLabel`` and ``sizePixel`` attributes** after **validating** their values. It follows these steps : 1. Retrieve the list of all possible image size labels from the ``ImageSize`` enum. 2. Check if the provided size label exists in this list. 3. Set the ``sizeLabel`` and ``sizePixel`` attributes based on the provided value. This method requires **one** parameter : * ``sizeLabel`` : The label indicating the image size to be retrieved (small, medium or large). It doesn’t return anything. .. dropdown:: PngPathBuilder Class (Subclass of ImagePathBuilder Abstract Class) :icon: telescope-fill :color: primary :name: PngPathBuilder Class The ``PngPathBuilder`` class is a subclass of the ``ImagePathBuilder`` abstract class and indirectly of the ``PathBuilder`` class. It is responsible for **building a path for a PNG image** after **validating** the required attributes. The class includes **one** public method, implementing a parent abstract method : .. dropdown:: ``getResult`` - Builds and returns the path associated to a PNG image :icon: gear This implementation of the ``getResult`` abstract method is responsible for **building the path for a PNG image** based on the ``community``, ``sizeLabel``, ``inchiKey``, and ``sizePixel`` attributes inherited from the ``ImagePathBuilder`` and ``PathBuilder`` classes. It follows these steps : 1. Defines the format as **PNG**. 2. Build the path using a formatted string, following the syntax ``png/community/size_label/inchikey_sizePixel.png`` It retrieve the ``community``, ``sizeLabel``, ``inchiKey``, and ``sizePixel`` attributes using their getter methods. **Example :** png/chebi/medium/COFJZDUAVQUGRU-UHFFFAOYSA-N_350.png This method does not require any parameters. It returns **the path of a PNG image**. .. dropdown:: MolPathBuilder Class (Subclass of PathBuilder Abstract Class) :icon: telescope-fill :color: primary :name: MolPathBuilder Class The ``MolPathBuilder`` class is a subclass of the ``PathBuilder`` abstract class. It is responsible for **building a path for a MOL file** after **validating** the required attributes. The class includes **one** public method, implementing a parent abstract method : .. dropdown:: ``getResult`` - Builds and returns the path associated to a MOL file :icon: gear This implementation of the ``getResult`` abstract method is responsible for **building the path for a MOL file** based on the ``community``, and ``inchiKey`` attributes inherited from ``PathBuilder`` classes. It follows these steps : 1. Defines the format as **MOL**. 2. Build the path using a formatted string, following the syntax ``mol/community/inchikey.mol`` It retrieve the ``community``, and ``inchiKey`` attributes using their getter methods. **Example :** mol/chebi/COFJZDUAVQUGRU-UHFFFAOYSA-N.mol This method does not require any parameters. It returns **the path of a MOL file**. !!!! Implementation.Directors Package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``Implementation.Directors`` package contains the director classes. .. image:: uml/classes/images/ImplementationDirectors.png .. dropdown:: PathDirector Interface :icon: telescope-fill :color: primary The ``PathDirector`` interface serves as a director that facilitates **the construction of paths** for retrieving files. It provides methods for creating valid paths to retrieve *MOL* files and *PNG* images from a specified community based on given parameters. The interface defines **two** methods to implement : .. dropdown:: ``buildMolPath`` - Builds a valid path to retrieve a MOL file :icon: gear The method ``buildMolPath`` **builds a valid path to retrieve a MOL file**. It is implemented in : * `SimplePathDirector Class`_ : Single implementation of ``PathDirector`` interface. .. dropdown:: ``buildPngPath`` - Builds a valid path to retrieve a PNG image :icon: gear The method ``buildPngPath`` **builds a valid path to retrieve a PNG image**. It is implemented in : * `SimplePathDirector Class`_ : Single implementation of ``PathDirector`` interface. .. dropdown:: SimplePathDirector Class (Implements PathDirector Interface) :icon: telescope-fill :color: primary :name: SimplePathDirector Class The ``SimplePathDirector`` implements the ``PathDirector`` interface. The class includes **two** public methods, implementing methods from an interface : .. dropdown:: ``buildMolPath`` - Builds a valid path to retrieve a MOL file :icon: gear This implementation of the interface method ``buildMolPath`` is responsible for **building a valid path to retrieve a MOL file** based on ``community`` and ``inchiKey`` parameters. It follows these steps : 1. Instantiates a ``MolPathBuilder``. 2. Sets the ``community`` attribute. 3. Sets the ``inchiKey`` attribute. 4. Build the path using the ``getResult`` method of the builder. This method requires **two** parameters : * ``community`` : The community from which the molecule’s MOL file is to be retrieved. * ``inchiKey`` : The InChI Key associated with the MOL file to retrieved. It returns **the path of the MOL file** .. dropdown:: ``buildPngPath`` - Builds a valid path to retrieve a PNG image :icon: gear This implementation of the interface method ``buildPngPath`` for **building a valid path to retrieve a PNG image** based on ``community``, ``sizeLabel`` and ``inchiKey`` parameters. It follows these steps : 1. Instantiate a ``PngPathBuilder``. 2. Set the ``community`` attribute. 3. Set the ``sizeLabel`` attribute. 4. Set the ``inchiKey`` attribute. 5. Build the path using the ``getResult`` method of the builder. This method requires **three** parameters : * ``community`` : The community from which the molecule’s PNG image is to be retrieved. * ``sizeLabel`` : The label indicating the size of the image to retrieve. * ``inchiKey`` : The InChI Key associated with the PNG image to retrieved. It returns **the path of the PNG file**. !!!! Implementation.Factories Package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``Implementation.Factories`` package contains the factory classes. .. image:: uml/classes/images/ImplementationFactories.png Implementation.Factories.Reader Package ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``Implementation.Factories.Reader`` package contains the factory classes for the readers. .. dropdown:: ReaderFactory Interface :icon: telescope-fill :color: primary The ``ReaderFactory`` is an interface designed to create a ``Reader`` object that corresponds to a particular file format and then use it to **retrieve the file** along with **its metadata** in the requested output type. It has one subclass : ``SimpleReaderFactory``. The interface defines **two** methods to implement : .. dropdown:: ``createReader`` - Provides the appropriate reader for the given file format :icon: gear The method ``createReader`` **creates and provides the appropriate** ``Reader`` to use for a given file format. It is implemented in : * `SimpleReaderFactory Class`_ : Single implementation of ``ReaderFactory`` interface. .. dropdown:: ``retrieveResource`` - Retrieves a resource from S3 storage based on the desired output type :icon: gear The method ``retrieveResource`` **retrieves a resource from S3 Storage** based on the desired output type (either ``resource`` or ``url``) It is implemented in : * `SimpleReaderFactory Class`_ : Single implementation of ``ReaderFactory`` interface. .. dropdown:: SimpleReaderFactory Class (Implements ReaderFactory Interface) :icon: telescope-fill :color: primary :name: SimpleReaderFactory Class The ``SimpleReaderFactory`` implements the ``ReaderFactory`` interface. It contains **two** variables : * ``logger``: The local logger * ``readerMap``: A map containing all available readers, where the key is the file format, and the value is the respective reader. The class defines **two** public methods, implementing methods from an interface : .. dropdown:: ``createReader`` - Provides the appropriate reader for the given file format :icon: gear This implementation of the interface method ``createReader`` is responsible for **creating and providing a reader** based on the specified format. Currently, it supports two formats : MOL files or PNG images It follows these steps : 1. Check the ``readerMap`` for the reader corresponding to the provided format. 2. If a reader is found, return the reader. 3. If no reader is found for the format, log an error and throw an ``InvalidFormatException``. This method requires **one** parameter : * ``format``: The format of the desired file. It returns a ``Reader`` object corresponding to the specified format. .. dropdown:: ``retrieveResource`` - Retrieves a resource from S3 storage based on the desired output type :icon: gear This implementation of the interface method ``retrieveResource`` is responsible for **retrieving a file** from S3 storage either as *content* or as a *URL*, depending on the specified output type. It follows these steps : 1. Use the ``createReader`` method to get the appropriate reader for the file format. 2. Depending on the ``outputType``, either: * Retrieve the file content along with its metadata. * Retrieve the file URL along with its metadata and override the content type in the headers as ``text/plain``. 3. If the ``outputType`` is invalid, log an error and throw an ``InvalidOutputTypeException``. This method requires **four** parameters : * ``format``: The format of the desired file. * ``path``: The path of the file in S3 storage. * ``headers``: The HTTP response headers. * ``outputType``: The type of output requested, either "resource" for file content or "url" for a URL. It returns a ``Resource`` object containing the retrieved file or URL. !!!! Implementation.Readers Package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``Implementation.Readers`` package contains the readers classes. .. image:: uml/classes/images/ImplementationReaders.png .. dropdown:: Reader Abstract Class :icon: telescope-fill :color: primary The ``Reader`` is an abstract class designed to **retrieve a file** and **extract its metadata**. It has two subclasses : ``MolReader`` and ``PngReader``. It contains **two** variables : * ``logger``: The local logger. * ``s3Service``: The service used for communication with S3 storage. The class contains **one** protected constructor : .. dropdown:: ``Reader`` - Instantiates the reader with the necessary dependencies :icon: gear The ``Reader`` constructor is used to **instantiate the service** that will communicate with the S3 Storage. It initialize the ``service`` variable with the provided S3Service instance. The constructor requires **one** parameter : * ``service`` : An instance of the ``S3Service``, which handles the communication with the S3 Storage. It doesn’t return anything. The class defines **one** public abstract method, which is implemented in the subclasses : .. dropdown:: ``extractMetadata`` - Extracts metadata directly from the file's byte array :icon: gear The method ``extractMetadata`` **extracts metadata** from the file represented as byte array. It is implemented in : * `MolReader Class`_ : To extract metadata from MOL files. * `PngReader Class`_ : To extract metadata from PNG images. It also has **two** public methods : .. dropdown:: ``getFileContent`` - Retrieve the file from S3 Storage along with its metadata :icon: gear The ``getFileContent`` method **retrieves the file** from S3 storage as *content*, along with its **extracted metadata formatted in the response HTTP headers**. It follows these steps : 1. Fetch the file from S3 storage as a byte array. 2. Use the ``processMetadataFromFile`` method from ``MetadataProcessor`` class to extract metadata from the file and update the response headers. 3. Return the file as a ``Resource`` object. This method requires **two** parameters : * ``path`` : The path of the desired file. * ``headers`` : The HTTP response headers. It returns a Spring Boot ``Resource`` object containing the content of the retrieved file. .. dropdown:: ``getUrl`` - Retrieve the file URL from S3 Storage along with its metadata :icon: gear The ``getUrl`` method **retrieves the file** from S3 storage as a *URL*, **extracts metadata**, along with its **extracted metadata formatted in the response HTTP headers**. It follows these steps : 1. Retrieve the URL of the file from S3 storage. 2. Use the ``processMetadataFromUrl`` method from ``MetadataProcessor`` class to extract metadata from the URL and update the response headers. 3. Return the file URL as a ``Resource`` object. This method requires two parameters : * ``path`` : The path of the desired file. * ``headers`` : The HTTP response headers. It returns a SpringBoot ``Resource`` object containing the URL of the retrieved file. .. dropdown:: PngReader Class (Subclass of Reader Abstract Class) :icon: telescope-fill :color: primary :name: PngReader Class The ``PngReader`` class is a subclass of the ``Reader`` abstract class. It enables **the retrieval of a PNG image** and **the extraction of its metadata**, either from the *resource* directly or via the *URL*. The class contains **one** constructor : .. dropdown:: ``PngReader`` - Instantiates the PNG reader with the necessary dependencies :icon: gear The ``PngReader`` constructor is used to **instantiate the service** that will communicate with the S3 Storage in the ``Reader`` class for the **PNG** format. The constructor requires **one** parameter : * ``service`` : An instance of the ``S3Service``, which handles the communication with the S3 Storage. It doesn’t return anything. It includes **one** public method, implementing a parent abstract method : .. dropdown:: ``extractMetadata`` - Extracts metadata from the PNG image :icon: gear This implementation of the abstract method ``extractMetadata`` is responsible for **extracting metadata** from a PNG image and **formats it as JSON**. It follows these steps : 1. Read the file bytes as a PNG image. 2. Extract the metadata and returns them formatted in JSON. The method requires **one** parameter : * ``file`` : A byte array representing the PNG image. It returns a Java ``JSONObject`` containing the extracted metadata. It also includes **one** private method : .. dropdown:: ``parseXmlMetadata`` - Parses the PNG metadata from XML format into a JSON object :icon: gear The method ``parseXmlMetadata`` **parses the PNG metadata** from XML format into a JSON object. It identifies the specific XML layer ("tEXtEntry") where custom metadata is stored in the PNG file, extracts each key-value pair, and converts them into a JSON format. It follows these steps : 1. Extracts the relevant metadata from the specific layer where they are stored (``tEXtEntry``). 2. Formats the metadata into a JSON object, associating each key with its corresponding value. 3. Returns the JSON object containing all the custom image metadata. The method requires **one** parameter : * ``imageMetadata`` : The ``IIOMetadata`` instance containing image metadata in XML format. It returns a Java ``JSONObject`` containing the extracted metadata. .. dropdown:: MolReader Class (Subclass of Reader Abstract Class) :icon: telescope-fill :color: primary :name: MolReader Class The ``MolReader`` class is a subclass of the ``Reader`` abstract class. It enables **the retrieval of a MOL file** and **the extraction of its metadata**, either from the *resource* directly or via the *URL*. The class contains **one** constructor : .. dropdown:: ``MolReader`` - Instantiates the MOL reader with the necessary dependencies :icon: gear The ``MolReader`` constructor is used to **instantiate the service** that will communicate with the S3 Storage in the ``Reader`` class for the **MOL** format. The constructor requires **one** parameter : * ``service`` : An instance of the ``S3Service``, which handles the communication with the S3 Storage. It doesn’t return anything. It includes **one** public method, implementing a parent abstract method : .. dropdown:: ``extractMetadata`` - Extracts metadata from the MOL file :icon: gear This implementation of the abstract method ``extractMetadata`` is responsible for **extracting metadata** from a MOL file and **formats it as JSON**. It follows these steps : 1. Read the file bytes as a String. 2. Extract the metadata that are on the first three lines and returns them formatted in JSON. The method requires **one** parameter : * ``file`` : A byte array representing the MOL file. It returns a Java ``JSONObject`` containing the extracted metadata. It also includes **one** private method : .. dropdown:: ``parseMolMetadata`` - Parses metadata from the first three lines of the MOL file content :icon: gear The method ``parseMolMetadata`` **parses the first three lines of a MOL file** to extract metadata. It then converts them into a JSON format. It follows these steps : 1. Parses the first three lines of the MOL file. 2. Extracts the relevant metadata from them and checks if they exist and follow the supported syntax. 3. Formats the metadata into a JSON object, associating each key with its corresponding value. 4. Returns the JSON object containing all the custom file metadata. .. note:: The metadata from the MOL file must use the following syntax (valid only for ``chebi`` community). .. code-block:: YYYY-MM-DD ChEBI ID Source License The method requires **one** parameter : * ``mol`` : The string representation of the MOL file content. It returns a Java ``JSONObject`` containing the extracted metadata. !!!! Implementation.Services Package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``Implementation.Services`` package contains the services used in the application. .. image:: uml/classes/images/ImplementationServices.png .. dropdown:: CompoundsService Class :icon: telescope-fill :color: primary The ``CompoundsService`` class is a service use **for retrieving chemical compound files** from S3 Storage. It provides methods to fetch ``MOL`` and ``PNG`` files associated with chemical compounds and return them in the desired format, either as a direct *resource* or as a *URL*. It has **four** variables : * ``logger`` : The local logger. * ``headers`` : HTTP headers for the response (with associated Getter and Setter methods). * ``pathDirector`` : Director class responsible for building the path of the requested file. * ``readerFactory`` : Factory to retrieve files from S3 Storage based on their format. The class contains **one** constructor : .. dropdown:: ``CompoundsService`` - Instantiates the service with the necessary dependencies :icon: gear The ``CompoundsService`` constructor **instantiates the path director and the reader factories** used to retrieve files. It initialize the ``pathDirector`` and ``readerFactory`` variables. The constructor requires **two** parameters : * ``pathDirector`` : The ``PathDirector`` instance used to build the path of the requested file. * ``readerFactory`` : The ``ReaderFactory`` instance used to retrieve the file from the S3 storage. It doesn’t return anything. It includes **two** public methods : .. dropdown:: ``getMolFile`` - Retrieve a MOL file of a molecule from the S3 Storage :icon: gear The method ``getMolFile`` **retrieves a molecule’s MOL file** and **returns it** as either a direct ``resource`` or a ``URL``, based on the specified output type. It follows these steps : 1. Sets the generic headers : ``Content-Type`` header to ``text/plain`` so that the MOL file is returned as a text, and the ``Access-Control-Allow-Headers`` / ``Access-Control-Expose-Headers`` to enables the exposition of custom headers used to return metadata with the response. 2. Builds the path to the requested MOL file in S3 Storage. The path follow the syntax : ``mol/{community}/{inchiKey}.mol`` (e.g mol/chebi/RYYVLZVUVIJVGH-UHFFFAOYSA-N.mol). 3. Retrieves the MOL file according to the specified ``outputType``. 4. Returns the MOL file either : * as a URL (e.g https://unh-metabocloud-resources.s3.mesocentre.uca.fr/mol/chebi/RYYVLZVUVIJVGH-UHFFFAOYSA-N.mol). * or directly as text content. It also retrieves formats metadata associated with the file in response headers. This method requires **three** parameters : * ``community`` : The community from which to retrieve the molecule’s MOL file (**currently only ``chebi`` is accepted**). * ``inchiKey`` : The InChI key of the molecule whose MOL file is to be retrieved. * ``outputType`` : The desired output type — either ``url`` to return a URL or ``resource`` to return the file’s content directly. It returns a SpringBoot Java ``Resource`` object containing either the URL of the MOL file or the file’s content. .. dropdown:: ``getPngImage`` - Retrieve a PNG image of a molecule from the S3 Storage :icon: gear The method ``getPngImage`` enables **retrieves a molecule’s PNG image** from S3 storage. It **sets appropriate headers** for the response and **returns it** as either a direct ``resource`` or a ``URL``, based on the specified output type. It follows several steps : 1. Sets the generic headers : ``Content-Type`` header to ``image/png`` so that the file is returned as a PNG image, the ``Access-Control-Allow-Headers``/ ``Access-Control-Expose-Headers`` to enables the exposition of custom headers used to return metadata with the response and the custom ``X-Metadata-Image-Size`` header to indicate the size of the PNG image returned. 2. Builds the path to the requested PNG image in the S3 Storage. The path follow the syntax : ``png/{community}/{imageSizeLabel}/{inchiKey}_{imageSizeInt}.png`` (e.g png/chebi/small/RYYVLZVUVIJVGH-UHFFFAOYSA-N_50.png). 3. Retrieves the PNG image according to the specified ``outputType``. 4. Returns the PNG image either : * as a URL (e.g https://unh-metabocloud-resources.s3.mesocentre.uca.fr/png/chebi/medium/RYYVLZVUVIJVGH-UHFFFAOYSA-N_350.png). The ``Content-Type`` header is then overridden by ``text/plain``. * or directly as an image content. It also retrieves formats metadata associated with the image in response headers. This method requires **four** parameters : * ``community`` : The community from which to retrieve the molecule’s MOL file (**currently only ``chebi`` is accepted**). * ``sizeLabel`` : The label indicating the image size to retrieve (either ``small``, ``medium`` or ``large``). * ``inchiKey`` : The InChI key of the molecule whose PNG image is to be retrieved. * ``outputType`` : The desired output type — either ``url``to return a URL or ``resource`` to return the file’s content directly. It returns a SpringBoot Java ``Resource`` object containing either the URL of the PNG image or the image’s content. It also includes **one** private methods : .. dropdown:: ``addHeaders`` - Add generic HTTP headers :icon: gear The method ``addHeaders`` **adds generic HTTP headers** like content type and access control headers. If an image size is provided, it sets a custom image size header as well. It adds the ``Content-Type``, ``Access-Control-Allow-Headers``, and ``Access-Control-Expose-Headers`` headers, and if the file retrieved is a PNG image, it also adds the ``X-Metadata-Image-Size`` custom header. It requires **three** parameters : * ``contentType`` : The content type header for the format (e.g., ``text/plain``, ``image/png``). * ``allowExposeHeaderValue`` : The access control allow/expose header value. * ``sizeLabel`` : An optional image size in pixels, only used for image formats (set to ``null`` for other formats). It doesn’t return anything. .. dropdown:: S3Service Class :icon: telescope-fill :color: primary The ``S3Service`` class is a service use **for communicating with the S3 Storage**. It provides methods to interact with the custom S3 Storage by retrieving objects and generating public URLs for stored files. It has **three** variables : * ``logger`` : The local logger. * ``bucketName`` : Name of the S3 bucket to query (indicate in the ``s3storage.properties`` file) * ``s3Client`` : The configured S3 client (autowired). The class includes **two** public methods : .. dropdown:: ``getObject`` - Retrieves an object from the S3 Storage :icon: gear The ``getObject`` method **retrieves an object** from the S3 storage as a byte array using a path as key. It follows these steps : 1. Builds a request to get the object from the S3 bucket using the provided key. 2. Reads the content of the object as a byte array. This method requires **one** parameter : * ``key`` : The key to retrieve the desired object from the S3 storage (here a path). It returns a byte array containing the S3 object data. .. dropdown:: ``getPublicUrl`` - Retrieves the public URL of an S3 object :icon: gear The method ``getPublicUrl`` **retrieves the public URL of an S3 object** using a path as key. It follows these steps : 1. Checks the existence of the object in the S3 storage by requesting the metadata. 2. Generates and returns the public URL for the specified object. This method requires **one** parameter : * ``key`` : The key to retrieve the public URL of the desired object. It returns the public URL of the requested S3 object. !!!! Implementation.Utils Package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``Implementation.Utils`` package contains the classes containing utils method needed in other classes. .. image:: uml/classes/images/ImplementationUtils.png .. dropdown:: MetadataProcessor Class :icon: telescope-fill :color: primary The ``MetadataProcessor`` class is responsible for **processing metadata** extracted from files or their URLs and **updating HTTP response headers** with the extracted metadata. It contains **one** variable : - ``logger``: The local logger. The class defines **two** public static methods : .. dropdown:: ``processMetadataFromFile`` - Extracts metadata from a file's byte array and updates the response headers with the extracted metadata :icon: gear The ``processMetadataFromFile`` method **extracts metadata** from a file's byte array using the metadata extractor function specific to the format of the file requested. It then **updates the HTTP response headers** with the extracted metadata. It follows these steps : 1. Apply the metadata extractor function to extract metadata from the byte array. 2. If metadata is extracted, call ``updateHeaders`` to add the metadata to the response headers. 3. If no metadata is extracted, log a warning message. This method requires **three** parameters : * ``fileBytes``: The file represented as a byte array. * ``headers``: The HTTP response headers. * ``metadataExtractor``: A function that extracts metadata from the byte array. It doesn’t return anything. .. dropdown:: ``processMetadataFromUrl`` - Extracts metadata from a file located at a URL and updates the response headers with the extracted metadata :icon: gear The ``processMetadataFromUrl`` method **processes metadata** from a file located at a URL using the metadata extractor function specific to the format of the file requested. It then **updates the HTTP response headers** with the extracted metadata. It follows these steps : 1. Open the provided URL and read its content as a byte array. 2. Apply the metadata extractor function to extract metadata from the byte array. 3. If metadata is extracted, call ``updateHeaders`` to add the metadata to the response headers. 4. If an error occurs while reading the URL or no metadata is extracted, log an error or warning message. This method requires **three** parameters : * ``url``: The URL of the file. * ``headers``: The HTTP response headers. * ``metadataExtractor``: A function that extracts metadata from the byte array. It doesn’t return anything. It also includes **one** private method : .. dropdown:: ``updateHeaders`` - Updates the HTTP response headers with metadata :icon: gear The ``updateHeaders`` method **adds metadata** extracted from a file or URL to the HTTP response headers. It follows these steps : 1. Iterate over the metadata's keys and values. 2. Add each key-value pair to the response headers. This method requires **two** parameters : * ``metadata``: A ``JSONObject`` containing the extracted metadata. * ``headers``: The HTTP response headers. It doesn’t return anything. !!!! Models Package ============== The ``Models`` package contains the models used in the application. .. image:: uml/classes/images/Models.png Models.Enums Package ~~~~~~~~~~~~~~~~~~~~ The ``Models.Enums`` package contains the enum models used in the application. .. dropdown:: Community Enum :icon: telescope-fill :color: primary The ``Community`` enumeration **represents the different communities available for retrieving data**. Each community corresponds to a specific data source or database from which chemical compound information can be retrieved. This enum currently includes the following community : * ``CHEBI`` : Represents the Chemical Entities of Biological Interest (ChEBI) database (“chebi”). It includes **one** variable : * ``label`` : A String that holds the label associated with the community. This enum include **one** constructor : .. dropdown:: ``Community`` - Initializes the enum constant with its corresponding label :icon: gear The ``Community`` constructor **initializes the enum constant** with its corresponding community. It requires **one** parameter : * ``label`` : The label associated with the community, passed as a string. It doesn't return anything. .. dropdown:: Headers Enum :icon: telescope-fill :color: primary The ``Headers`` enumeration **represents the various HTTP header keys and values** used in the application. It categorizes headers into two main types : ``Key Headers`` and ``Value Headers``. The ``Headers`` enum is divided into **two** main categories : * **Key Headers** : These are standard and custom header keys used in HTTP responses. * ``CONTENT_TYPE`` : “Content-Type” - Specifies the content type of the response. * ``ALLOW_HEADERS`` : “Access-Control-Allow-Headers” - Specifies which HTTP headers can be used during the actual request. * ``EXPOSE_HEADERS`` : “Access-Control-Expose-Headers” - Specifies which headers are safe to expose to the client. * ``IMAGE_SIZE`` : “X-Metadata-Image-Size” - Custom header to store the image size. * ``CHEBI_ID``: “X-Metadata-Chebi-Id” - Custom header to store the ChEBI ID. * ``CREATION_DATE`` : “X-Metadata-Creation-Date” - Custom header to store the date the files were saved in S3. * ``LICENSE`` : “X-Metadata-Data-License” - Custom header to store the file license. * ``SOURCE`` : “X-Metadata-Data-Source” - Custom header to store the file source. * **Value Headers** : These are predefined values corresponding to the key headers. * ``IMAGE_PNG`` : “image/png” - Value for the “Content-Type” header when the content is a PNG image. * ``PLAIN_TEXT`` : “text/plain” - Value for the “Content-Type” header when the content is plain text. * ``ALLOW_EXPOSE_HEADERS_VALUE_PNG`` : A combination of custom headers that should be exposed when the content is a PNG image. * ``ALLOW_EXPOSE_HEADERS_VALUE_MOL`` : A combination of custom headers that should be exposed when the content is a MOL file. It includes **one** variable : * ``label`` : A ``String`` that holds the label associated with the header key or value. This enum include **one** constructor : .. dropdown:: ``Headers`` - Initializes the enum constant with its corresponding label :icon: gear The ``Headers`` constructor **initializes the enum constant** with its corresponding label. It requires **one** parameter : * ``label`` : The label associated with the header key or value, passed as a string. It doesn't return anything. .. dropdown:: ImageSize Enum :icon: telescope-fill :color: primary The ``ImageSize`` enumeration **represents the available image sizes** within the application. This enum defines three specific sizes available in the S3 storage. This enum defines **three** constants, each representing a specific image size in pixels : * ``SMALL`` : Represents a small image size with dimensions of 50 x 50 pixels. * ``MEDIUM`` : Represents a medium image size with dimensions of 350 x 350 pixels. * ``LARGE`` : Represents a large image size with dimensions of 700 x 700 pixels. It includes **one** variable : * ``label`` : A String that holds the label representing the size of the image in pixels. This enum include **one** constructor : .. dropdown:: ``ImageSize`` - Initializes the enum constant with its corresponding label :icon: gear The ``ImageSize`` constructor **initializes the enum constant** with its corresponding image size. It requires **one** parameter : * ``label`` : The label representing the size in pixels (both width and height), passed as a string. It doesn't return anything. .. dropdown:: IndexErrorMessages Enum :icon: telescope-fill :color: primary The ``IndexErrorMessages`` enumeration **centralizes specific error messages** that the application may return under various error conditions. This enum defines **seven** constants, each representing a specific error scenario along with an associated error message : * ``INVALID_FORMAT`` : Occurs when the ``format`` parameter provided by the user is invalid. The only acceptable values are ``png`` and ``mol``. .. code-block:: “The parameter ‘format’ is invalid. Only ‘png’ and ‘mol’ are accepted. See the documentation for more details.” * ``INVALID_COMMUNITY`` : Occurs when the ``community`` parameter provided by the user is invalid. The only acceptable value is ``chebi``. .. code-block:: “The parameter ‘community’ is invalid. Only ‘chebi’ is accepted. See the documentation for more details.” - * ``INVALID_SIZE`` : Occurs when the ``size`` parameter provided by the user is invalid. The only acceptable values are ``small``, ``medium``, and ``large``. .. code-block:: “The parameter ‘size’ is invalid. Only ‘small’, ‘medium’ and ‘large’ are accepted. See the documentation for more details.” * ``INVALID_INCHI_KEY`` : Occurs when the ``inchiKey`` parameter provided by the user is malformed or invalid. .. code-block:: “The parameter ‘inchiKey’ is invalid. See the documentation for more details.” * ``INVALID_OUTPUT_TYPE`` : Occurs when the ``outputType`` parameter provided by the user is invalid. The only acceptable values are ``resource`` and ``url``. .. code-block:: “The parameter ‘outputType’ is invalid. Only ‘resource’ and ‘url’ are accepted. See the documentation for more details.” * ``FILE_NOT_FOUND`` : Occurs when a requested file cannot be found in the S3 storage. .. code-block:: “The file requested does not exist.” * ``ERROR_INTERACTION_S3`` : Occurs an error occurred during an interaction with the S3 storage. .. code-block:: “An internal error occurred during the interaction with the S3 Storage.” It includes **one** variable : * ``label`` : A String representing the error message thrown by a specific error. This enum include **one** constructor : .. dropdown:: ``IndexErrorMessages`` - Initializes the enum constant with its corresponding label :icon: gear The ``IndexErrorMessages`` constructor **initializes the enum constant** with its corresponding error message. It requires **one** parameter : * ``label`` : The label representing the error message thrown by a specific error. It doesn't return anything.