Work Station Rack Pool

Through the APIs provided in this Java WebService we can manage bookings from a pool of Work Station Rack.

What is a Work Station Rack?

A Work Station Rack is a set of the Vehicle's hardware components where the product teams can try their implementation.

What is this service used for?

There are different sort of Work Station Racks and consequently each one has its own specific use case. This causes concurrency among the product teams.

By using this service each product team can book a timeframe to use a specific Work Station Rack.

Therefore, the product team can plan better and organize themselves according to the Work Station Rack availability.

Main GOAL

Become the source of truth regarding the availability of Work Station Racks. It will also be the only tool for the BMW's product teams to manage the bookings for a pool of Work Station Rack.

Application architecture

We aim for a combination of elegance and simplicity. The application design will evolve during development as engineers create code to meet the business needs, without any hard rules defined regarding the design.

However, some standards are necessary to allow the collaboration among the team members.

Clean architecture

The entity-control-boundary (ECB), or entity-boundary-control (EBC), or boundary-control-entity (BCE) is an architectural pattern used in use-case driven object-oriented programming that structures the classes composing high-level object-oriented source code according to their responsibilities in the use-case realization.^[1].

Get familiar with that concept through the links below.

• Clean Coder Blog - Clean Architecture
• Clean Coder Blog - The Clean Architecture
• Adam Bien - Bureaucratic Design With Java EE

The project uses the ECB pattern to decouple the business logic from external part of the product like the database and the UI.

It is flat and easy to organize the application's components.

Code structure

db
   |-- changelog // Add database changes to a file
   |   |-- local // Used locally in the test context
   |   |   |-- 1.0.0 // Changesets: Define database changes
   |   |   |   |-- ddl // Data Definition Language is a type of SQL command used to define data structures and modify data
   |   |-- master // Used in the pipeline to change a database in some productive environment
   |   |   |-- 1.0.0 // Changesets: Define database changes
   |   |   |   |-- ddl // Data Definition Language is a type of SQL command used to define data structures and modify data
   |-- init-db // Hold script to initialize the database structure
src
   |-- main
   |   |-- docker // Hold docker files used to build application's image
   |   |-- java
   |   |   |-- com
   |   |   |   |-- bmw
   |   |   |   |   |-- ctw
   |   |   |   |   |   |-- workstation
   |   |   |   |   |   |   |-- rack
   |   |   |   |   |   |   |   |-- api
   |   |   |   |   |   |   |   |   |-- booking // Domain package
   |   |   |   |   |   |   |   |   |   |-- boundary // The software in this layer contains application specific business rules. It encapsulates and implements all of the use cases of the system. These use cases orchestrate the flow of data to and from the entities, and direct those entities to use their enterprise wide business rules to achieve the goals of the use case.
   |   |   |   |   |   |   |   |   |   |-- control // The software in this layer is a set of adapters that convert data from the format most convenient for the use cases and entities, to the format most convenient for some external agency such as the Database or the Web.
   |   |   |   |   |   |   |   |   |   |-- entity // Entities encapsulate Enterprise wide business rules. An entity can be an object with methods, or it can be a set of data structures and functions.
   |   |   |   |   |   |   |   |   |-- infrastructure // Hold all classes needed to support the business application
   |   |   |   |   |   |   |   |   |   |-- constants // All common constants, like the ROUTES used in the Resources path
   |   |   |   |   |   |   |   |   |   |-- database // General database rules, most used to audit log features
   |   |-- resources
   |-- test
   |   |-- java
   |   |   |-- com
   |   |   |   |-- bmw
   |   |   |   |   |-- ctw
   |   |   |   |   |   |-- workstation
   |   |   |   |   |   |   |-- rack
   |   |   |   |   |   |   |   |-- api
   |   |   |-- testsupport
   |   |-- resources
   |   |   |-- assets // Hold static content (css, img, html, js) to support the application's document
   |   |   |   |-- img

Reference books:

• Object-Oriented Software Engineering: A Use Case Driven Approach
• Clean Architecture: A Craftsman's Guide to Software Structure and Design

Development environment setup

Stack

• Java 21
• Maven¹
• JakartaEE
• Eclipse Microprofile programming model for JakartaEE
• Quarkus WebServer
• Postgres
• Docker

Set up IntelliJ

Running the application

IMPORTANT

Docker must be installed, it should be up and running in the environment before trying to run the application.

There are three different ways to run the application.

Containerized (Docker)

1) Build the application

• Open an external terminal or an embedded terminal in IntelliJ and the command below.
  

  ./mvnw clean package
  

  Test execution success messages and a build success message should be displayed as output

2) Build and startup the application's containers

• Open an external terminal or an embedded terminal in IntelliJ and the command below.
  

  docker-compose up --build -d
  

  The creation and start-up of application's container success messages should be displayed as output

3) Do a smoke test

Quarkus standalone + Database Containerized (Docker)

1) Build and startup the database containers

• Open an external terminal or an embedded terminal in IntelliJ and the command below.
  

  docker-compose -f docker-compose-sources.yml up --build -d
  

  Should be display as output success messages about the creation and start-up of application's container.

2) Packaging and running the application

The application can be packaged using:

./mvnw package

It produces the quarkus-run.jar file in the target/quarkus-app/ directory. Be aware that it’s not an über-jar as the dependencies are copied into the target/quarkus-app/lib/ directory.

The application is now runnable using java -jar target/quarkus-app/quarkus-run.jar.

3) Packaging and running the application using über-jar

If you want to build an über-jar, execute the following command:

./mvnw package -Dquarkus.package.jar.type=uber-jar

The application, packaged as an über-jar, is now runnable using java -jar target/*-runner.jar.

4) Do a smoke test

Quarkus Dev Mode (live code reload)

1) Build the application

• Open an external terminal or an embedded terminal in IntelliJ and the command below.
  

  ./mvnw clean package
  

  Should be displayed as output success messages about test execution and a build success message.

2) Set the environment variables

• Open an external terminal or an embedded terminal in IntelliJ and run the command below.
  

  set -a
  source .env.sample
  set +a
  

  There is no output. However, from now on you should use the same terminal session to perform the step below.

3) Running application in Quarkus Dev mode

• In the same terminal session that you performed the second step, run the command below.
  

  ./mvnw quarkus:dev
  

4) Do a smoke test

NOTE

In both running mode when you perform the smoke test your request must be processed by the application successfully, otherwise check the logs to see what is happening.

Swagger-ui

By default, Swagger UI is accessible at /q/swagger-ui

References

[1] Entity-control-boundary (2023) Wikipedia. Available at: https://en.wikipedia.org/wiki/Entity-control-boundary (Accessed: 14 June 2024).

Notes

[1] Or use the wrapped maven within the application root folder