SETLIST ORGANIZER

_{Built by Maksim Meliashchuk}

Table of contents

• Project Information
• Running example
• Applications Demo
• Technology Stack
• Requirements
• Installation Information
• Rest app configure
• Web app configure
• Run local tests
• Run mutation testing
• Run load testing
• Run application with PostgreSQL
• Run with docker-compose
• Local tests with Postman
• Documenting a REST API
• OpenAPI generated server
• Swagger generated client
• Excel Import and Export
• Generate test data
• Create and restore database archive

Project Information

🎙️ 'Setlist Organizer' is a web application for organizing repertoires of musical bands. 🎙️

Mind Map

• Software requirements specification
• Available REST endpoints
• Presentation

⚠️ _{Note: the Mind map, Software requirements specification, Available REST endpoints and Presentation describe the basic version of the project.The project is constantly being improved and developed. The features of the current version of the project may differ from the information in this section. See the following sections in this README for up-to-date project information.} ⚠️

Running example

Applications Demo

Applications deployed on Heroku

The web application will be accessible at:

https://setlist-organizer-web.herokuapp.com/

The rest application will be accessible at:

https://setlist-organizer-rest.herokuapp.com/

API documentation with Swagger UI:

https://setlist-organizer-rest.herokuapp.com/swagger-ui/index.html

Technology Stack

• Programming Language: Java
• Core Framework: Spring boot
• Data Access:
  • Spring JDBC
  • Spring Data JPA
• Validation Framework: Hibernate Validator
• Annotation processor:
  • Lombok
  • MapStruct
• Build System: Maven
• Control System: Git
• License: Apache license, version 2.0
• Code Style: Codacy
• Automated Testing:
  • JUnit5
  • Mockito
• Mutation Testing: PIT
• Load Testing: Gatling
• Log:
  • Log4j 2
  • Logback
  • SLF4J
• Monitoring:
  • Micrometer
  • Prometheus
  • Grafana
• Database:
  • H2
  • PostgreSQL
• Database migration tool: Flyway
• JSON library:
  • Jackson
  • GSON
• Generate test data: Java Faker
• Java API for Microsoft Excel: Apache POI
• API documentation generation:
  • Springdoc-openapi
  • Swagger UI
• Code generation:
  • OpenAPI Generator
  • Swagger Codegen
• Template Engine: Thymeleaf
• CSS Framework: Bootstrap
• App containerization: Docker

Requirements

The following software is required for the complete workflow (from git clone to the running Docker Container). The specified versions are the tested ones.

• JDK 11+
• Git 2.25.1+
• Apache Maven 3.6.3+
• Docker 20.10.12+
• Docker-compose 1.29.2+
• Scala-sdk 2.13.6+ (for load testing)

Installation Information

  $ git clone https://github.com/Brest-Java-Course-2021-2/Maksim-Meliashchuk-Setlist-Organizer.git
  $ cd Maksim-Meliashchuk-Setlist-Organizer
  $ mvn clean install

Rest app configure

Setup rest-app in application.properties:

Profile	Description
dev	Run application with embedded H2 database in memory
postgres	Run application with PostgreSQL database
test	Run application with embedded H2 database in memory, Flyway migration disabled
jdbc	Interact with a database by using Spring JDBC
jpa	Interact with a database by using Spring Data JPA

Example:

spring.profiles.active=dev, jpa

Web app configure

The web application has three web client implementations for making HTTP calls to REST application services - RestTemplate, a new WebClient alternative and automatically generated by the Swagger Codegen client API - ApiClient. Setup web-app in application.properties.

Using RestTemplate (is deprecated since Spring 5):

app.httpClient = RestTemplate

Using WebClient (exists since Spring 5):

app.httpClient = WebClient

Using ApiClient (OkHttpClient and GSON based):

app.httpClient = ApiClient

ApiClient is a preferable choice.

⚠️ _{Note: this Web application has endpoints for using create and import Excel, XML, ZIP files with the 'ApiClient' property only.} ⚠️

Run local tests

Embedded H2 in memory.

In the root directory of the project:

$ java -jar -Dspring.profiles.active=dev,jpa rest-app/target/rest-app-1.0-SNAPSHOT.jar

To start the OpenAPI generated server:

$ java -jar -Dspring.profiles.active=dev,jpa rest-app-openapi/target/rest-app-openapi-1.0-SNAPSHOT.jar

The rest application will be accessible at http://localhost:8088.

$ java -jar web-app/target/web-app-1.0-SNAPSHOT.jar 

The web application will be accessible at http://localhost:8080.

Run mutation testing

PIT runs unit tests against automatically modified versions of the application code, the most effective way to use mutation testing is to run it frequently against only the code that has been changed. TargetClasses and TargetTests to limit the tests available to be run added to parent project POM:

<configuration>
  <targetClasses>
      <param>com.epam.brest.service.impl.jpa.*</param>
  </targetClasses>
  <targetTests>
      <param>com.epam.brest.service.impl.jpa.*</param>
  </targetTests>
</configuration>

Run directly from the commandline:

$ mvn test-compile org.pitest:pitest-maven:mutationCoverage

PIT Test Coverage Report will be accessible: /service/target/pit-reports/index.html

Run load testing

Testing starts with 10 users per second making two requests to the repertoire, holding at that concurrency for five seconds. Then RestSimulationLocal test scenario increases the number of users per second by 5, 5 times, holding for 5 seconds each time. Every request must return an HTTP 200 status code to pass the test. Run the test in the root directory of the project:

$ sh gatling-test.sh

Make sure the rest-app at http://localhost:8088 is running. Gatling reports generated in: /gatling-test/target/gatling/

Run application with PostgreSQL

PostgreSQL require(can be customized in application-postgres.properties file in prod-db module):

• driver - org.postgresql.Driver
• url - jdbc:postgresql://localhost:5432/setlistOrganizer
• user - postgres
• password - password

Run rest-app with PostgreSQL:

$ java -jar -Dspring.profiles.active=postgres,jpa rest-app/target/rest-app-1.0-SNAPSHOT.jar

Run with docker-compose

In the root directory of the project, run the rest-app with monitoring and web-app in one go:

$ sudo docker-compose up --build

The web application will be accessible at http://localhost:8080

The rest application will be accessible at http://localhost:8088

The PostgreSQL database can be accessed in docker at: http://localhost:5432

Micrometer by default shows jvm metrics at http://localhost:8088/actuator/prometheus

Access the Prometheus webUI on http://localhost:9090

Access the Grafana webUI with jvm-micrometer dashboard on http://localhost:3000

To stop the containers:

$ sudo docker-compose down

Local tests with Postman

To test the REST API, you can use the Postman collection to access the API endpoints:

postman_collection.json

See the Postman online documentation.

Documenting a REST API

Using OpenAPI 3.0

The OpenAPI descriptions in JSON format will be available at the path: http://localhost:8088/v3/api-docs

The OpenAPI descriptions in YAML format will be available at the path: http://localhost:8088/v3/api-docs.yaml

API documentation with Swagger UI: http://localhost:8088/swagger-ui/index.html

OpenAPI generated server

Automatically generated by the OpenAPI Generator project by using the OpenAPI-Spec and the openapi-generator-maven-plugin.

An OpenAPI document that conforms to the OpenAPI Specification openapi.yaml has been generated automatically by using springdoc-openapi-maven-plugin in the module rest-app.

Refer to the module rest-app-openapi for more information.

Swagger generated client

Automatically generated by the Swagger Codegen by using the swagger-codegen-maven-plugin.

An OpenAPI document that conforms to the OpenAPI Specification openapi.yaml has been generated automatically by using springdoc-openapi-maven-plugin in the module rest-app.

Refer to the module service-swagger-client for more information.

Excel Import and Export

These REST applications have several endpoints (/export/excel and /import/excel) to create and import Excel files using Apache POI.

Please, after running the REST application, refer to the API documentation with Swagger UI for more information.

Following are samples of Excel files that can be imported:

Band.xlsx Track.xlsx

Generate test data

These REST applications have several endpoints /fill to generate fake data for showcase with uses Java Faker. It is possible specify language for generated data (EN, DE, FR), default EN. It is possible specify count fakes data, use parameter to multiply default size (default value 1).

Please, after running the REST application, refer to the API documentation with Swagger UI for more information.

Create and restore database archive

The database archive can be created and exported in XML format and saved as a ZIP archive. These REST applications have a /downloadZipFile endpoint with the ability to create a database archive and a /uploadZipFile endpoint with the ability to restore the database from the archive. The Simple API for XML (SAX) is used to parse XML documents.

The following is an example of a ZIP file that is the result of an export that can be imported:

database.zip