Changes between Initial Version and Version 1 of PrototypeImplementation

Timestamp:

06/18/26 23:51:35 (2 days ago)

Author:

223091

Comment:

--

PrototypeImplementation

@@ +1 @@
+= Prototype Implementation =
+
+== Implemented use-cases ==
+
+This page documents the first application prototype for the Room Reservation System. The prototype is implemented as a Java console application that connects to the PostgreSQL database created in the previous phase. The goal of the prototype is not to represent a complete final application, but to demonstrate that the most important database usage scenarios from Phase P3 can be implemented and executed against the created database.
+
+The prototype implements the following selected use-cases:
+
+* [[UseCase0001PrototypeImplementation|UseCase0001PrototypeImplementation - Search available rooms]]
+* [[UseCase0002PrototypeImplementation|UseCase0002PrototypeImplementation - Create reservation request]]
+* [[UseCase0003PrototypeImplementation|UseCase0003PrototypeImplementation - Approve or reject reservation]]
+
+The implemented use-cases cover the main database operations needed by the system:
+
+* reading available rooms from the database;
+* checking reservation availability for a selected date and time interval;
+* creating a new reservation request;
+* selecting users and rooms from lists instead of manually entering identifiers;
+* approving a pending reservation;
+* verifying the created and modified data in the PostgreSQL database.
+
+== Prototype overview ==
+
+The prototype is a simple command-line Java application. After starting the application, the user enters the database connection parameters, and the system connects to the PostgreSQL database through the SSH tunnel. If the connection is successful, the application displays a main menu with the implemented scenarios.
+
+[[Image(p4_connection_success.png, width=100%)]]
+
+The main menu contains the following options:
+
+* Search available rooms
+* Create reservation request
+* Approve or reject reservation
+* Exit
+
+The application uses real SQL statements executed against the project schema named ''project''. The prototype uses the same database structure that was created in Phase P2 and the same use-case scenarios that were documented in Phase P3.
+
+== Implemented functionality ==
+
+=== Search available rooms ===
+
+The first implemented scenario allows a requester to search for available rooms for a selected date and time interval. The user enters the reservation date, start time, end time, minimum capacity, room type filter, and optional required equipment. The system reads rooms, buildings, equipment assigned to rooms, and existing reservations from the database and returns only rooms that satisfy the selected criteria and do not have an overlapping active reservation.
+
+Detailed documentation: [[UseCase0001PrototypeImplementation]]
+
+=== Create reservation request ===
+
+The second implemented scenario allows a requester to create a new reservation request. The user does not need to remember internal identifiers such as user_id or room_id. Instead, the application lists available users and available rooms, and the user selects values from the displayed lists. The system then inserts a new reservation record into the database with status ''pending''.
+
+Detailed documentation: [[UseCase0002PrototypeImplementation]]
+
+=== Approve or reject reservation ===
+
+The third implemented scenario allows an approver to review pending reservations and record an approval decision. The application lists pending reservations, allows the approver to select a reservation, and then records either an approved or rejected decision. The system updates the reservation status and inserts a corresponding approval record.
+
+Detailed documentation: [[UseCase0003PrototypeImplementation]]
+
+== Build and run instructions ==
+
+The instructions for compiling, configuring, running, and testing the prototype are documented on the following page:
+
+* [[BuildInstructions|BuildInstructions]]
+
+== Source code ==
+
+The source code of the prototype is prepared as a Java Maven project. The project contains the source code of the application and the required configuration for compiling and running it.
+
+The main source file of the prototype is:
+
+* ''src/main/java/mk/finki/roomreservation/App.java''
+
+The Maven configuration file is:
+
+* ''pom.xml''
+
+The application uses JDBC to connect to PostgreSQL and execute the SQL statements needed for the implemented scenarios.
+
+= Build Instructions =
+
+== Development environment description ==
+
+The prototype application is implemented as a Java console application using Maven. It connects to the PostgreSQL project database through an SSH tunnel. The application uses JDBC for database access.
+
+Required software:
+
+* Java JDK 21 or compatible newer Java version
+* IntelliJ IDEA
+* Maven
+* PostgreSQL JDBC driver, included through Maven
+* DBeaver, used for database verification
+* SSH tunnel script provided through the EPRMS / Databases section
+
+The project structure is:
+
+{{{
+room-reservation-prototype
+├── pom.xml
+├── README.md
+└── src
+└── main
+└── java
+└── mk
+└── finki
+└── roomreservation
+└── App.java
+}}}
+
+== Database connection requirements ==
+
+The application does not connect directly to the remote database server. The SSH tunnel must be started first. The provided tunnel script opens access to the PostgreSQL database through:
+
+{{{
+localhost:9999
+}}}
+
+The application uses the following JDBC URL:
+
+{{{
+jdbc:postgresql://localhost:9999/db_202526z_va_prj_room_reservation
+}}}
+
+The database username is:
+
+{{{
+db_202526z_va_prj_room_reservation_owner
+}}}
+
+The database password is the database user password assigned in the EPRMS system.
+
+Important: real passwords are not written in the source code or in this documentation. The password is entered manually when starting the application.
+
+== Starting the SSH tunnel ==
+
+Before starting the Java prototype, the SSH tunnel script must be started.
+
+Steps:
+
+1. Open the folder containing the provided tunnel script and ''plink''.
+2. Open PowerShell or Command Prompt in that folder.
+3. Start the tunnel script.
+4. Enter the SSH tunnel parameters provided in the EPRMS system if they are not already configured in the script.
+5. Keep the tunnel window open while the Java prototype is running.
+
+The tunnel must remain active during the entire test. If the tunnel window is closed, the Java application will lose access to the database.
+
+== Build instructions ==
+
+Open the project in IntelliJ IDEA.
+
+1. Open IntelliJ IDEA.
+2. Choose ''Open'' and select the ''room-reservation-prototype'' project folder.
+3. Make sure that the project SDK is set to Java JDK 21 or compatible.
+4. Wait until Maven imports the project dependencies.
+5. Open ''src/main/java/mk/finki/roomreservation/App.java''.
+6. Run the ''App'' class.
+
+The project can also be compiled with Maven using:
+
+{{{
+mvn clean package
+}}}
+
+== Running the application ==
+
+After starting the application, the program asks for database connection parameters.
+
+Use the default database URL by pressing Enter:
+
+{{{
+jdbc:postgresql://localhost:9999/db_202526z_va_prj_room_reservation
+}}}
+
+Use the default database username by pressing Enter:
+
+{{{
+db_202526z_va_prj_room_reservation_owner
+}}}
+
+Enter the assigned database password manually when prompted.
+
+If the connection is successful, the application displays:
+
+{{{
+Connected to database successfully.
+}}}
+
+Then the main menu is shown:
+
+{{{
+Main menu
+
+1. Search available rooms
+2. Create reservation request
+3. Approve or reject reservation
+4. Exit
+   Choose option:
+   }}}
+
+== Testing instructions ==
+
+The prototype should be tested by executing the three implemented scenarios.
+
+=== Test 1: Search available rooms ===
+
+Select option:
+
+{{{
+1
+}}}
+
+Example input:
+
+{{{
+Reservation date: 2026-03-01
+Start time: 09:00
+End time: 10:00
+Minimum capacity: 1
+Room type filter:
+Required equipment name:
+}}}
+
+Expected result:
+
+The system displays a list of available rooms with room code, type, capacity, building name, and address.
+
+=== Test 2: Create reservation request ===
+
+Select option:
+
+{{{
+2
+}}}
+
+Example input:
+
+{{{
+Choose user number: 1
+Reservation date: 2026-03-01
+Start time: 09:00
+End time: 10:00
+Include room in reservation: y
+Minimum capacity: 1
+Room type filter:
+Required equipment in room:
+Choose room number: 3
+Request additional/general equipment: n
+}}}
+
+Expected result:
+
+The system creates a new reservation request and displays the generated reservation ID. The created reservation has status ''pending''.
+
+=== Test 3: Approve or reject reservation ===
+
+Select option:
+
+{{{
+3
+}}}
+
+Example input:
+
+{{{
+Choose reservation number: 2
+Choose approver number: 1
+Choose decision: 1
+Decision note: Approved after checking room availability.
+}}}
+
+Expected result:
+
+The system saves the approval decision, updates the reservation status to ''approved'', and displays the final reservation details.
+
+== Database verification ==
+
+The result can be verified in DBeaver by executing the following SQL statements:
+
+{{{
+SELECT *
+FROM project.reservations
+ORDER BY reservation_id DESC;
+
+SELECT *
+FROM project.approvals
+ORDER BY approval_id DESC;
+}}}
+
+The created reservation should appear in the ''project.reservations'' table, and the approval decision should appear in the ''project.approvals'' table.
+
+== Notes ==
+
+The prototype is intentionally minimal. It demonstrates the essential database operations required for the selected use-cases, but it is not a complete production application. The completion and extension of the application can be done in later project phases.