Ibrahim submission branch

README.md

@@ -1,61 +1,228 @@
-## Submission Instructions
-
-To submit your Oracle JAVA Spring Boot Maven project as a solution, please follow these steps:
-
-### Step 1: Install git on your PC
-- Install "git" as shown in this tutorial: [How to install git](https://youtu.be/iYkLrXobBbA?si=_l0haibv_X9NpIjJ)
-- Open command prompt and run
-  ```bash
-  git version
-  ```
-- If you see the version, then git is successfully installed.
-
-### Step 2: Fork the Repository
-- Navigate to [this repository](https://github.com/CodelineAtyab/oraclequantapi) provided by Codeline.
-- Click on the "Fork" button at the top-right corner of the page to create a copy of the repository under your own GitHub account.
-
-### Step 3: Clone the Forked Repository
-- Open your terminal or command prompt.
-- Clone the forked repository to your local machine using the following command:
-  ```bash
-  git clone https://github.com/your-username/repo-name.git
-  ```
-
-### Step 4: Create a new branch
-- Navigate to the cloned repository directory
-  ```bash
-  cd repo-name
-  ```
-- Create a new branch for your code submissions (Replace your-name with your name in your-name-submission-branch):
-  ```bash
-  git checkout -b your-name-submission-branch
-  ```
-
-
-### Step 5: Add Your Code
-- Implement the API
-
-### Step 6: Commit your changes
-- Run the following commands in order to commit your changes:
-  ```bash
-  git add *
-  git commit -m "Meaningful commit message here"
-  ```
-
-### Step 7: Push Your Branch to GitHub
-- Run the following commands to upload the changes to the forked github repository (Replace your-name with your name in your-name-submission-branch):
-  ```bash
-  git push origin your-name-submission-branch
-  ```
-
-### Step 8: Create a Pull Request
-- Go to your forked repository on GitHub.
-- You should see a prompt to create a pull request. Click on "Compare & pull request".
-- Provide a title and description for your pull request, then click "Create pull request".
-
-### Step 9: Notify Codeline
-- Notify on slack that you have created a PR for your solution.
-
-## Note: If you face any issues in the process above, Please do the following:
-- Watch [this youtube tutorial](https://www.youtube.com/watch?v=a_FLqX3vGR4)
-- Contact Ikhlas or Atyab.
+# OracleQuant ERP - Package Measurement Conversion API
+
+Trainer-style Spring Boot API for converting encoded package measurement strings into package inflow totals. The application uses Java 17, Spring Boot, Maven, Oracle Linux, and Oracle XE.
+
+## Features
+
+- `GET /convert-measurements` converts encoded measurement input into a JSON array.
+- Conversion history is stored in Oracle XE through Spring Data JPA.
+- History can be fetched, updated, and cleared through REST endpoints.
+- Console logs and rolling file logs are enabled.
+- Log files keep one week of history.
+
+## Project Structure
+
+```text
+src/main/java/om/oraclequant/pkc_api/OracleQuantPkcApiApplication.java
+src/main/java/om/oraclequant/pkc_api/controllers/MeasurementController.java
+src/main/java/om/oraclequant/pkc_api/controllers/HistoryController.java
+src/main/java/om/oraclequant/pkc_api/services/MeasurementService.java
+src/main/java/om/oraclequant/pkc_api/services/HistoryService.java
+src/main/java/om/oraclequant/pkc_api/models/MeasurementSequence.java
+src/main/java/om/oraclequant/pkc_api/models/MeasurementHistory.java
+src/main/java/om/oraclequant/pkc_api/repositories/MeasurementHistoryRepository.java
+src/main/resources/application.properties
+version.txt
+```
+
+## Conversion Rules
+
+- `a` to `z` represent `1` to `26`.
+- `_` represents `0`.
+- Uppercase letters are converted to lowercase.
+- Characters other than letters and `_` are converted to `_`, so they count as zero.
+- A sequence of `z` characters continues until the first non-`z` character.
+- Each package starts with an encoded count, then up to that many encoded measurement values.
+- If the count asks for more values than remain, the package uses only the remaining values.
+
+Examples:
+
+```text
+aa                                      -> [1]
+abbcc                                   -> [2, 6]
+dz_a_aazzaaa                            -> [28, 53, 1]
+a_                                      -> [0]
+abcdabcdab                              -> [2, 7, 7]
+abcdabcdab_                             -> [2, 7, 7, 0]
+zdaaaaaaaabaaaaaaaabaaaaaaaabbaa        -> [34]
+za_a_a_a_a_a_a_a_a_a_a_a_a_azaaa        -> [40, 1]
+a1                                      -> [0]
+```
+
+## Database Configuration
+
+The application is configured for Oracle XE using Oracle Thin JDBC.
+
+Edit `src/main/resources/application.properties`:
+
+```properties
+spring.datasource.url=jdbc:oracle:thin:@localhost:1521/XEPDB1
+spring.datasource.username=your_username
+spring.datasource.password=your_password
+spring.datasource.driver-class-name=oracle.jdbc.OracleDriver
+
+spring.jpa.hibernate.ddl-auto=update
+spring.jpa.database-platform=org.hibernate.dialect.OracleDialect
+spring.jpa.show-sql=true
+```
+
+For Oracle XE, the common service name is:
+
+```text
+XEPDB1
+```
+
+If your Oracle installation uses SID instead, the URL may look like:
+
+```properties
+spring.datasource.url=jdbc:oracle:thin:@localhost:1521:XE
+```
+
+## Running The Application
+
+From the project root:
+
+```bash
+./mvnw spring-boot:run
+```
+
+Or build and run the jar:
+
+```bash
+./mvnw clean package
+java -jar target/pkc-api.jar
+```
+
+The API runs on:
+
+```text
+http://localhost:8080
+```
+
+## REST API Endpoints
+
+Convert measurements:
+
+```bash
+curl 'http://localhost:8080/convert?input=aa'
+```
+
+Response:
+
+```json
+[1]
+```
+
+The older query parameter name is also supported:
+
+```bash
+curl 'http://localhost:8080/convert?convert=aa'
+```
+
+Get all history records:
+
+```bash
+curl 'http://localhost:8080/history'
+```
+
+Get one history record:
+
+```bash
+curl 'http://localhost:8080/history/{id}'
+```
+
+Update one history record:
+
+```bash
+curl -X PUT 'http://localhost:8080/history/{id}' \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"aa","output":"[1]"}'
+```
+
+Clear all history:
+
+```bash
+curl -X DELETE 'http://localhost:8080/history'
+```
+
+## Local No-Database Test
+
+Before connecting Oracle, the conversion logic can be tested locally with:
+
+```text
+local-test/MeasurementLocalTest.java
+```
+
+This runner checks the conversion rules without starting Spring Boot and without using Oracle.
+
+## Deploy On Oracle Linux Via SSH
+
+Build the jar locally:
+
+```bash
+./mvnw clean package
+```
+
+Copy the jar to Oracle Linux:
+
+```bash
+scp target/pkc-api.jar opc@your-server-ip:/home/opc/pkc-api.jar
+```
+
+SSH into the Oracle Linux server:
+
+```bash
+ssh opc@your-server-ip
+```
+
+Install Java 17 if needed:
+
+```bash
+sudo dnf install -y java-17-openjdk
+```
+
+Set database environment values or edit `application.properties` before building:
+
+```bash
+export ORACLE_DB_URL='jdbc:oracle:thin:@localhost:1521/XEPDB1'
+export ORACLE_DB_USERNAME='your_username'
+export ORACLE_DB_PASSWORD='your_password'
+```
+
+Run the jar:
+
+```bash
+java -jar /home/opc/pkc-api.jar
+```
+
+Optional systemd service:
+
+```ini
+[Unit]
+Description=OracleQuant Package Measurement API
+After=network.target
+
+[Service]
+User=opc
+WorkingDirectory=/home/opc
+ExecStart=/usr/bin/java -jar /home/opc/pkc-api.jar
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Save it as:
+
+```text
+/etc/systemd/system/pkc-api.service
+```
+
+Then run:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now pkc-api
+sudo systemctl status pkc-api
+```

pom.xml

@@ -10,7 +10,7 @@
 	</parent>
 	<groupId>com.oraclequantapi</groupId>
 	<artifactId>oraclequantapi</artifactId>
-	<version>0.0.1-SNAPSHOT</version>
+	<version>1.0.0</version>
 	<name/>
 	<description/>
 	<url/>
@@ -35,11 +35,29 @@
 			<artifactId>spring-boot-starter-web</artifactId>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-data-jpa</artifactId>
+		</dependency>
+
+		<dependency>
+			<groupId>com.oracle.database.jdbc</groupId>
+			<artifactId>ojdbc11</artifactId>
+			<scope>runtime</scope>
+		</dependency>
+
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-test</artifactId>
 			<scope>test</scope>
 		</dependency>
+
+		<dependency>
+			<groupId>com.h2database</groupId>
+			<artifactId>h2</artifactId>
+			<scope>test</scope>
+		</dependency>
+
 	</dependencies>
 
 	<build>

src/main/java/com/oraclequantapi/oraclequantapi/controllers/HistoryController.java

@@ -0,0 +1,48 @@
+package com.oraclequantapi.oraclequantapi.controllers;
+
+import com.oraclequantapi.oraclequantapi.models.MeasurementHistory;
+import com.oraclequantapi.oraclequantapi.services.HistoryService;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+
+@RestController
+@RequestMapping (path = "/history")
+public class HistoryController {
+    @Autowired
+    public HistoryService historyService;
+
+    // Return all saved conversion requests from Oracle DB.
+    @GetMapping
+    public ResponseEntity<List<MeasurementHistory>> getAllHistory() {
+        return ResponseEntity.status(HttpStatus.OK).body(historyService.getHistory());
+    }
+
+    // Return one saved conversion request by id.
+    @GetMapping(path = "/{id}")
+    public ResponseEntity<MeasurementHistory> getSpecificHistory(@PathVariable String id) {
+        MeasurementHistory history = historyService.getHistoryById(id);
+        return ResponseEntity.status(HttpStatus.OK).body(history);
+    }
+
+    // Update a history record by id.
+    @PutMapping(path = "/{id}")
+    public ResponseEntity<MeasurementHistory> updateHistory(
+            @PathVariable String id,
+            @RequestBody MeasurementHistory incomingHistory
+    ) {
+        MeasurementHistory history = historyService.updateHistory(id, incomingHistory);
+        return ResponseEntity.status(HttpStatus.OK).body(history);
+    }
+
+    // Delete all saved history records.
+    @DeleteMapping
+    public ResponseEntity<Void> clearHistory() {
+        historyService.clearHistory();
+        return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
+    }
+
+}