ChatterBox

Made by @matbagnoletti

Docenti: prof.ssa @mciuchetti e prof.ssa Fioroni

Corso TPSIT a.s. 2023/2024, ITTS A. Volta (PG)

Descrizione

ChatterBox è un'applicazione di chat che sfrutta il protocollo UDP in modalità multicast per la comunicazione tra più utenti. Il programma permette, grazie a un'apposita API RESTful, la creazione di un gruppo chat e il loro accesso tramite credenziali di autenticazione. L'interfaccia grafica utilizzata è stata realizzata con JavaFX, mentre la gestione della comunicazione è affidata a Java e Kotlin.

Requisiti

Per poter eseguire il progetto da sorgente sono necessari:

• JDK 21 completo;
• Git;
• connessione internet al primo avvio, necessaria per scaricare Maven e le dipendenze del progetto.

Non è necessario installare Maven manualmente: il progetto contiene già il Maven Wrapper, disponibile come mvnw.cmd su Windows e come mvnw su Linux. Le dipendenze scaricate vengono salvate nella cartella locale .m2/, esclusa dalla repository.

Per creare gli archivi distribuibili è necessario utilizzare un JDK 21 completo, che includa anche il comando jpackage.

È possibile visualizzare le versioni già presenti sul proprio dispositivo mediante i seguenti comandi:

java -version
javac -version

Installazione e utilizzo

Per poter utilizzare l'applicazione ChatterBox sono disponibili due possibilità:

• avviare il progetto da sorgente dopo aver effettuato il clone della repository;
• scaricare un archivio già pronto dalla pagina delle release.

Avvio da sorgente

Questa modalità è indicata per chi vuole aprire, controllare o modificare il progetto.

Su Windows:

git clone https://www.github.com/matbagnoletti/ChatterBox.git
cd ChatterBox
.\bootstrap.ps1
.\run.ps1

Su Linux:

git clone https://www.github.com/matbagnoletti/ChatterBox.git
cd ChatterBox
chmod +x mvnw *.sh
./bootstrap.sh
./run.sh

Lo script bootstrap controlla l'ambiente, verifica il JDK 21, controlla Maven Wrapper, scarica le dipendenze ed esegue una compilazione di controllo senza aprire l'applicazione.

Per controllare soltanto l'ambiente, senza scaricare dipendenze e senza compilare, è possibile utilizzare:

.\doctor.ps1

oppure, su Linux:

./doctor.sh

Lo script run avvia l'applicazione tramite Maven Wrapper e JavaFX, senza richiedere IntelliJ IDEA.

Gli script disponibili nella repository sono:

• doctor.ps1 e doctor.sh: controllano Java, javac, Maven Wrapper e, se richiesto, jpackage;
• bootstrap.ps1 e bootstrap.sh: preparano il progetto dopo il clone ed eseguono una compilazione di controllo;
• run.ps1 e run.sh: avviano ChatterBox da sorgente;
• build.ps1 e build.sh: compilano il progetto da terminale;
• package.ps1 e package.sh: creano gli archivi distribuibili;
• clean.ps1 e clean.sh: ripuliscono gli output generati dalla build.

Archivio già pronto

Questa modalità è indicata per chi vuole soltanto eseguire l'applicazione.

Gli archivi pronti si trovano nella pagina GitHub Releases:

• ChatterBox-<version>-windows-x64-app.zip per Windows;
• ChatterBox-<version>-linux-x64-app.tar.gz per Linux.

Su Windows è sufficiente estrarre l'archivio .zip ed eseguire:

ChatterBox\ChatterBox.exe

Su Linux è sufficiente estrarre l'archivio .tar.gz ed eseguire:

./ChatterBox/bin/ChatterBox

Ogni archivio contiene una application image generata con jpackage e comprensiva della runtime Java necessaria.

Compilazione e pacchetti da terminale

Per compilare manualmente il progetto:

Su Windows:

.\build.ps1

Su Linux:

./build.sh

Per produrre localmente gli archivi distribuibili:

Su Windows:

.\package.ps1

Su Linux:

./package.sh

Per ripulire gli output generati dalla build:

Su Windows:

.\clean.ps1

Su Linux:

./clean.sh

Gli output vengono generati nella cartella target/ e non devono essere salvati nella repository. I file destinati al download vengono pubblicati nella pagina delle GitHub Releases.

Le modifiche qui documentate riguardano soltanto build, avvio da terminale, creazione dei pacchetti, controlli automatici e pulizia della repository. Non modificano la logica applicativa, l'interfaccia grafica, la rete, la sicurezza o il comportamento del programma.

Per ulteriori dettagli:

• BUILD.md
• DISTRIBUTION.md

Struttura e funzionamento

Il progetto si compone da 3 packages principali:

• Package chatterbox: contiene le classi di gestione dell'interfaccia grafica JavaFX e la classe principale ChatterBox.
• Package multicastudpsocketchat: contiene le classi di gestione della chat, il cui progetto di riferimento è disponibile qui.
• Package security: contiene la classe di gestione della sicurezza della comunicazione tramite crittografia End-to-End (AES).

Utilizzo

1. All'avvio dell'applicazione, una schermata di setup permetterà all'utente la configurazione del proprio username e le impostazioni di connessione al gruppo chat.

   

   Il nome utente deve essere composto da almeno 3 caratteri. Il nome del gruppo è univoco ed ha una lunghezza minima di 6 caratteri, così come la password. La gestione e amministrazione dei gruppi e realizzata mediante una API RESTful apposita che permette la creazione, la modifica e l'eliminazione di gruppi chat. La password del gruppo chat è necessaria per garantire la sicurezza e la privacy dei messaggi scambiati tra gli utenti. Viene memorizzata in forma crittografata e non è possibile recuperarla una volta impostata.

   

   Il TTL (Time To Live) è un valore che determina il numero di router attraverso i quali il datagramma può passare. Un valore di 1 indica che il datagramma non può lasciare la sottorete locale, mentre un valore di 255 indica che il datagramma può attraversare un numero illimitato di router. Il valore di default è 128. Per quanto riguarda il loopback dei datagrammi, invece, è possibile disattivarlo per alleggerire il traffico di rete nel solo caso in cui multiple istanze dell'applicazione NON siano eseguite sullo stesso dispositivo.

2. Una volta configurato il gruppo, l'utente verrà reindirizzato alla schermata principale dell'applicazione. Qui sarà possibile visualizzare i messaggi inviati dagli altri utenti del gruppo chat e inviare messaggi propri.

   

   Il pulsante "Termina" permette di chiudere la connessione al gruppo chat. Una volta terminata la chat, l'utente potrà riconnettersi al gruppo chat mediante il pulsante "Riconnetti". Ogni messaggio inviato o ricevuto è accompagnato dal nome utente, dall'orario di invio e da un'icona che indica se il messaggio è stato ricevuto correttamente da tutti gli utenti online in quell'instante. A partire versione v2.1.0 ogni conversazione è protetta da crittografia End-to-End (AES). La barra di navigazione in alto permette di visualizzare i dettagli del gruppo chat e di modificare le impostazioni di connessione.

   Info gruppo: informazioni di sistema

   

   Pannello di controllo: informazioni sull'esecuzione

   

   In questo esempio gli indirizzi IP e i numeri di porta sono stati nascondi per motivi di privacy.

   Impostazioni: layout e controlli

   

   A partire dalla versione v2.1.1 è possibile modificare il tema dell'applicazione. Inoltre, tutti i cambiamenti al layout verranno storicizzati e ripristinati all'avvio successivo.

   Aiuto: a proposito di ChatterBox e comandi

   

Licenza d'uso

Questo progetto (e tutte le sue versioni) sono rilasciate sotto la MB General Copyleft License.