ptrenwith/listservice

Tags: latest

Maintained By: Philip M. Trenwith Date 18 November 2018

This container contains a Java application that runs a RESTful API on port 8080. The API is designed to list the files in a specified directory and return the filenames, sizes and file attributes. The Java application makes use of Maven to manage the dependencies.

============= BUILDING & RUNNING ============= To build and run this application the user can clone the repository using git: git clone https://***/philiptrenwith/listservice.git

and then run the script provided. On Linux: chmod -x buildimage.sh sudo ./buildimage.sh

On Windows: Double click buildimage.cmd (Or open the command line and navigate to the directory and then run the script)

These scripts will build the container and run it. To consume the rest server the user can make calls to the rest service using CURL and the URL's provided below.

================= REST CALLS ================= The calls that is accepted by the REST API are: http://:8080/api/list -> parameters: path, offset, size

The path parameter specifies the path where the files of interest are. When listing the files at a given path, the user has to specify the number of files that has to be returned by the rest call, using the size parameter. The user can also specify the offset which indicates which file in the list should be the first file in the list.

The files at a given path are listed making use of a File Stream. Once the Stream is opened an iterator is retrieved that is used to read the files in the directory using the next() method. If the user specifies an offset of -1, the iterator remains open and with every subsequent call to the REST API to list a subset of files in the directory the next subset of files is returned. If a user specifies an offset != -1 the filestream is closed and reopened placing the iterator at zero. The iterator is then moved the position specified by the offset and n-number of files are read and returned where n indicates the value of the size parameter.

When the iterator reaches the end of the list and there are no more files to return the stream is closed automatically. The Stream will also be closed automatically after a period of inactivity, meaning the iterator has not moved in a set amount of time. The default time of inactivity is 10-minutes. The period of inactivity can be configured in the config.yaml file. The user can also close the file stream manually with a rest call to:

http://:8080/api/close -> parameters: path Close the File stream if one is open at path.

http://:8080/api/generate -> parameters: path, size Additionally I have added a generate command that will generate n random files at the given path where path is specified as a parameter and n is the value specified by the size parameter.

http://:8080/health/alive This is a heatlh call to check if the REST server is running. For production this call can be made to return system uptime, CPU usage and Memory usage ect.

=============== CONFIGURATION ================ Some values are configurable and the configuration is provided in a YAML configuration file: config.yaml The attributes that can be configured is provided below with the default values.

host_address: 0.0.0.0 -> address to ***d to port_number: 8080 -> port to ***d to stream_timeout_period_min: 10 -> time to keep the Stream open after last access before closing rest_connect_timeout_ms: 30000 -> time to wait to connect to rest service before timeout. rest_read_timeout_ms: 60000 -> time to wait for rest response (reading) before timeout.

================= UNIT TESTS ================= Some unit tests has been added to test various parts of the application and ensure that everything works as expected. A "functional" test has also been written at org.trenwith.main.rest.client.cListDirectoryApiClientTest.java, this class test the application as a whole. First the REST service is started and the calling thread waits for the service to come online and ***d to the default port 8080. Then a call is made to generate some random files and then a call is made to list the files. The call to generate files is not blocking, therefore the call made to list files may not return all the files that is generated because the generation thread may still be in progress. However, for this functional test it is only important to ensure that the REST server starts, files can be generated and the call to list files at a given path works successfully.

================= LOGGING ==================== Logging has been added to the application using the SLF4J logger. The logger has also been configured using logback to write the log files to the standard syslog. The logger can be configured using the logback.xml file.