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.

S3Config Class

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 :

aws.access.key=<The S3 access key for authentication>
aws.secret.key=<The S3 secret key for authentication>
aws.region=<The region where the S3 bucket is located>
aws.s3.endpointUrl=<The endpoint URL of the S3 service>
aws.s3.bucketName=<The name of the bucket to query>

The class includes one public method :

s3Client - Configures a Spring Bean for the S3Client

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.

CompoundsController Class

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 :

CompoundsController - Instantiates the controller with the necessary dependencies

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 :

getFile - Handle GET requests to retrieve a file based on the specified parameters.

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 :

  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 :

  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.

FileNotFoundException Class

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 :

FileNotFoundException - Instantiates the exception with a specified detail message

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.

InteractionS3Exception Class

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 :

InteractionS3Exception - Instantiates the exception with a specified detail message

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.

InvalidCommunityException Class

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 :

InvalidCommunityException - Instantiates the exception with a specified detail message

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.

InvalidFormatException Class

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 :

InvalidFormatException - Instantiates the exception with a specified detail message

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.

InvalidImageSizeException Class

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 :

InvalidImageSizeException - Instantiates the exception with a specified detail message

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.

InvalidOutputTypeException Class

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 :

InvalidOutputTypeException - Instantiates the exception with a specified detail message

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.

GlobalExceptionHandler Class

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 :

handleInvalidParameterException - Handles Invalid*Exception exceptions.

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.

handleFileNotFoundException - Handles FileNotFoundException exceptions.

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.

handleInteractionS3Exception - Handles InteractionS3Exception exceptions.

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.

Implementation.Builders.Path Package

The Implementation.Builders.Path package contains the builders used to build the file path.

PathBuilder Abstract Class

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 :

getResult - Builds and returns the path associated to a file

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 :

setCommunity - Validates and sets the community to which the requested object belongs

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.

setInchiKey - Validates and sets the InChI Key associated with the desired molecule

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.

ImagePathBuilder Abstract Class (Subclass of PathBuilder Abstract Class)

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 :

setImageSize - Validates and sets the size label and pixel for an image

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.

PngPathBuilder Class (Subclass of ImagePathBuilder Abstract 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 :

getResult - Builds and returns the path associated to a PNG image

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.

MolPathBuilder Class (Subclass of PathBuilder Abstract 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 :

getResult - Builds and returns the path associated to a MOL file

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.

PathDirector Interface

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 :

buildMolPath - Builds a valid path to retrieve a MOL file

The method buildMolPath builds a valid path to retrieve a MOL file.

It is implemented in :

• SimplePathDirector Class : Single implementation of PathDirector interface.

buildPngPath - Builds a valid path to retrieve a PNG image

The method buildPngPath builds a valid path to retrieve a PNG image.

It is implemented in :

• SimplePathDirector Class : Single implementation of PathDirector interface.

SimplePathDirector Class (Implements PathDirector Interface)

The SimplePathDirector implements the PathDirector interface.

The class includes two public methods, implementing methods from an interface :

buildMolPath - Builds a valid path to retrieve a MOL file

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

buildPngPath - Builds a valid path to retrieve a PNG image

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.

Implementation.Factories.Reader Package

The Implementation.Factories.Reader package contains the factory classes for the readers.

ReaderFactory Interface

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 :

createReader - Provides the appropriate reader for the given file format

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.

retrieveResource - Retrieves a resource from S3 storage based on the desired output type

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.

SimpleReaderFactory Class (Implements ReaderFactory Interface)

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 :

createReader - Provides the appropriate reader for the given file format

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.

retrieveResource - Retrieves a resource from S3 storage based on the desired output type

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.

Reader Abstract Class

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 :

Reader - Instantiates the reader with the necessary dependencies

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 :

extractMetadata - Extracts metadata directly from the file’s byte array

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 :

getFileContent - Retrieve the file from S3 Storage along with its metadata

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.

getUrl - Retrieve the file URL from S3 Storage along with its metadata

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.

PngReader Class (Subclass of Reader Abstract 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 :

PngReader - Instantiates the PNG reader with the necessary dependencies

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 :

extractMetadata - Extracts metadata from the PNG image

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 :

parseXmlMetadata - Parses the PNG metadata from XML format into a JSON object

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.

MolReader Class (Subclass of Reader Abstract 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 :

MolReader - Instantiates the MOL reader with the necessary dependencies

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 :

extractMetadata - Extracts metadata from the MOL file

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 :

parseMolMetadata - Parses metadata from the first three lines of the MOL file content

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

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.

CompoundsService Class

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 :

CompoundsService - Instantiates the service with the necessary dependencies

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 :

getMolFile - Retrieve a MOL file of a molecule from the S3 Storage

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.

getPngImage - Retrieve a PNG image of a molecule from the S3 Storage

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 :

addHeaders - Add generic HTTP headers

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.

S3Service Class

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 :

getObject - Retrieves an object from the S3 Storage

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.

getPublicUrl - Retrieves the public URL of an S3 object

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.

MetadataProcessor Class

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 :

processMetadataFromFile - Extracts metadata from a file’s byte array and updates the response headers with the extracted metadata

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.

processMetadataFromUrl - Extracts metadata from a file located at a URL and updates the response headers with the extracted metadata

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 :

updateHeaders - Updates the HTTP response headers with metadata

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.

Models.Enums Package

The Models.Enums package contains the enum models used in the application.

Community Enum

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 :

Community - Initializes the enum constant with its corresponding label

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.

Headers Enum

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 :

Headers - Initializes the enum constant with its corresponding label

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.

ImageSize Enum

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 :

ImageSize - Initializes the enum constant with its corresponding label

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.

IndexErrorMessages Enum

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.

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

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

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

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

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

  “The file requested does not exist.”
  

• ERROR_INTERACTION_S3 : Occurs an error occurred during an interaction with the S3 storage.

  “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 :

IndexErrorMessages - Initializes the enum constant with its corresponding label

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.