PROJECT: Smart Shopping List Manager / Gestore Liste

[EN] ENGLISH VERSION

DESCRIPTION A Java application for managing shopping lists, updated with a modern Graphical User Interface (Swing GUI). The project implements the MVC (Model-View-Controller) architecture and supports list creation, adding/removing items, searching, a trash bin system, and automatic data state persistence.

1. REQUIREMENTS AND DEPENDENCIES

• Runtime Environment: Java / JDK 11 (tested on OpenJDK 11.0.16.1)
• Terminal: Windows PowerShell (for compilation scripts) or Linux Bash
• External Dependencies (for testing only): junit-standalone.jar file (JUnit Platform Console Standalone 1.10.x). The core application code has no dependencies and uses the standard Java library only.

2. PROJECT STRUCTURE /src /controller - bridge between view and model (Controller.java) /model - business logic (Articolo.java, Categoria.java, GestioneListe.java, ListaDiArticoli.java) /recources - graphical assets and icons (basket-buy-market.ico) /test - JUnit tests for logic verification (ArticoloTest.java, GestioneListeTest.java, ListaDiArticoliTest.java) /view - user interface components (ConsoleView.java, SwingView.java) Main.java - application entry point /out - folder for compiled classes (.class structures for app and tests) ShoppingList.jar - packaged executable Java archive (Cross-platform) ShoppingList.exe - standalone Windows executable binary

3. HOW TO COMPILE THE PROJECT Open your terminal in the root directory of the project.

Step 1. Compile the main application code (Windows PowerShell): javac -d out -encoding UTF-8 (Get-ChildItem src\model*.java, src\controller*.java, src\view*.java, src\Main.java)

Step 2. Compile tests (make sure junit-standalone.jar is in the root directory): javac -d out -cp "out;junit-standalone.jar" -encoding UTF-8 (Get-ChildItem src\test*.java)

4. HOW TO RUN THE PROJECT You can run the application using either the raw compiled classes or the built binaries:

• Option A: Run via compiled classes (Development mode): java -cp out Main

• Option B: Run the cross-platform JAR archive (Windows / Linux / macOS): java -jar ShoppingList.jar

• Option C: Native launch (Windows only): Double-click on ShoppingList.exe

Run all unit tests to verify the core logic: java -jar junit-standalone.jar --class-path out --scan-class-path

5. FILE FORMAT AND PERSISTENCE FEATURES The application features a robust custom-built JSON persistence engine that works seamlessly without any external dependencies:

• Format Limitation: The application implements strict FileNameExtensionFilter components. File dialogues explicitly focus on and validate *.json Data Files.
• Auto-Extension Fix: When saving, if the user manually drops the extension name, the manager automatically appends .json to secure the path.
• Robust Formatting Parsing: The engine natively strips unpredictable hidden characters (\r, \n) and handles variable whitespaces safely, preventing corruption during complex nested structural object mapping.
• Dynamic Category Mapping: Categories are parsed globally first. If an old element refers to an unregistered type during data loading, the persistence layout dynamically registers it to restore integrity.

6. PACKAGING INTO A STANDALONE EXEC (.EXE) & JAR To build and pack the application yourself into standalone formats without advanced IDEs:
7. Compile classes into the out directory using the step defined in Section 3.
8. Build the cross-platform executable jar archive via PowerShell: jar cfe ShoppingList.jar Main -C out .
9. (Optional Windows target) Wrap the generated ShoppingList.jar using Launch4j. In the Launch4j GUI, set the output file name, select the jar, and set Min JRE Version to 11.0.0 on the JRE tab to build your own ShoppingList.exe.

[IT] VERSIONE ITALIANA

DESCRIZIONE Un'applicazione Java per la gestione delle liste della spesa, aggiornata con una moderna interfaccia grafica (Swing GUI). Il progetto segue l'architettura MVC (Model-View-Controller) e supporta la creazione di liste, l'aggiunta/rimozione di articoli, la ricerca, un sistema di cestino e la persistenza automatica dello stato.

1. REQUISITI E DIPENDENZE

• Ambiente di runtime: Java / JDK 11 (testato su OpenJDK 11.0.16.1)
• Terminale: Windows PowerShell (per gli script di compilazione) o Linux Bash
• Dipendenze esterne (solo per i test): Il file junit-standalone.jar (JUnit Platform Console Standalone 1.10.x). Il codice principale dell'applicazione non ha dipendenze esterne e utilizza esclusivamente la libreria standard di Java.

2. STRUTTURA DEL PROGETTO /src /controller - collegamento tra view e model (Controller.java) /model - logica di business (Articolo.java, Categoria.java, GestioneListe.java, ListaDiArticoli.java) /recources - risorse grafiche e icone (basket-buy-market.ico) /test - test JUnit per la verifica della logica (ArticoloTest.java, GestioneListeTest.java, ListaDiArticoliTest.java) /view - componenti dell'interfaccia utente (ConsoleView.java, SwingView.java) Main.java - punto di ingresso dell'applicazione /out - cartella per i file di classe compilati (.class dell'applicazione e dei test) ShoppingList.jar - archivio Java eseguibile pacchettizzato (Cross-platform) ShoppingList.exe - file binario eseguibile autonomo per Windows

3. COME COMPILARE IL PROGETTO Apri il terminale nella cartella principale del progetto (root).

Passo 1. Compilazione del codice principale (Windows PowerShell): javac -d out -encoding UTF-8 (Get-ChildItem src\model*.java, src\controller*.java, src\view*.java, src\Main.java)

Passo 2. Compilazione dei test (assicurati che junit-standalone.jar sia nella root): javac -d out -cp "out;junit-standalone.jar" -encoding UTF-8 (Get-ChildItem src\test*.java)

4. COME AVVIARE IL PROGETTO È possibile avviare l'applicazione utilizzando le classi compilate o i binari generati:

• Opzione A: Avvio tramite classi compilate (Modalità sviluppo): java -cp out Main

• Opzione B: Avvio dell'archivio JAR multipiattaforma (Windows / Linux / macOS): java -jar ShoppingList.jar

• Opzione C: Avvio nativo (Solo per Windows): Fare doppio clic su ShoppingList.exe

Avvio di tutti gli unit test per verificare il corretto funzionamento: java -jar junit-standalone.jar --class-path out --scan-class-path

5. FORMATO DEI FILE E FUNZIONALITÀ DI PERSISTENZA L'applicazione include un motore di persistenza JSON personalizzato robusto che funziona nativamente senza librerie esterne:

• Limitazione del formato: L'applicazione implementa componenti FileNameExtensionFilter rigidi. I dialoghi di salvataggio/apertura convalidano esclusivamente i file dati *.json.
• Estensione automatica: Durante il salvataggio, se l'utente omette l'estensione, il sistema aggiunge automaticamente .json alla fine del percorso del file.
• Parsing robusto della formattazione: Il motore rimuove automaticamente i caratteri nascosti imprevisti (\r, \n) e gestisce in modo sicuro gli spazi vuoti variabili, evitando errori durante il caricamento di strutture annidate.
• Mappatura dinamica delle categorie: Le categorie vengono caricate globalmente. Se un articolo salvato fa riferimento a una categoria non registrata, il sistema la ricrea e la registra dinamicamente per preservare l'integrità dei dati.

6. PACCHETTO IN UN ESEGUIBILE AUTONOMO (.EXE) E JAR Per compilare e pacchettizzare l'applicazione autonomamente senza l'uso di IDE avanzati:
7. Compilare le classi nella cartella out seguendo il passo definito nella Sezione 3.
8. Creare un archivio jar eseguibile multipiattaforma tramite PowerShell: jar cfe ShoppingList.jar Main -C out .
9. (Target Windows opzionale) Pacchettizzare il file ShoppingList.jar generato utilizzando Launch4j. Nell'interfaccia di Launch4j, specificare il nome del file di output, selezionare il file jar e impostare la Min JRE Version su 11.0.0 nella scheda JRE per generare il proprio ShoppingList.exe.

---

UNIVERSITY & AUTHOR INFO / INFORMAZIONI ACCADEMICHE

Università degli Studi del Piemonte Orientale (UPO) Dipartimento di Scienze e Innovazione Tecnologica (DISIT) Corso di Laurea in Informatica

Copyright (C) 2026 Vladimir Rukavishnikov Matricola: 20063686 GitHub: https://github.com/HungryVovka