Aggiorna doc e alcuni fix

doc/chapters/01_introduzione.tex

@@ -17,41 +17,48 @@ Ivan Donati - 781022
 
 \section{Repository}
 
-Come da consegna per l'assignment è stato fatto uso dello strumento di file versioning git gestito da GitLab. Tutto il materiale definitivo del progetto è presente nel branch master del repository raggiungibile al seguente collegamento:
+Come da consegna per l'assignment è stato fatto uso dello strumento di file versioning \code{git} gestito da \textit{GitLab}. Tutto il materiale finale del progetto è presente nel branch master del repository raggiungibile al seguente collegamento:
 
 \begin{center}
 \url{https://gitlab.com/meliurwen/2019_assignment3_MiVan}
 \end{center}
 
 La radice del branch raffigurata in basso presenta un'organizzazione semplice e minimale:
-\newline
+
+\begin{itemize}
+  \item \textbf{mivan:} È la cartella che contiene il sorgente dell'applicazione.
+  \item \textbf{doc:} È la cartella che contiene il sorgente della documentazione scritta in \latex .
+  \item \textbf{assignment3\_mivan.pdf:} È la versione compilata in pdf della documentazione.
+  \item \textbf{Dockerfile} e \textbf{docker-compose.yml:} Sono i file necessari per eseguire la versione containerizzata dell'applicazione.
+  \item \textbf{LICENSE} e \textbf{README.md:} Sono rispettivamente la licenza (MIT) assegnata per il progeto ed una sua breve introduzione.
+\end{itemize}
+
 \dirtree{%
  .1 <repository>.
- .2 app/.
+ .2 mivan/.
  .2 doc/.
  .2 .gitignore.
+ .2 Dockerfile.
+ .2 docker-compose.yml.
+ .2 LICENSE.
  .2 README.md.
  .2 assignment3\_mivan.pdf.
 }
 
-\begin{itemize}
-  \item \textbf{app:} È la cartella che contiene il sorgente dell'applicazione.
-  \item \textbf{doc:} È la cartella che contiene il sorgente della documentazione scritta in \latex .
-  \item \textbf{assignment3\_mivan.pdf:} È la versione compilata in pdf della documentazione.
-\end{itemize}
 
 \section{Applicazione}
 
 L'applicazione oggetto di questo assigment è \textbf{MiVan}.
 \newline
-Si tratta di un'applicazione che gestisce prestiti di libri di un sistema bibliotecario con una o più sedi. Essa, oltre ad essere in grado di gestire i prestiti, è anche in grado di gestire i libri, la loro posizione, lo staff che amministra i prestiti e gli utenti che ne fanno richiesta.
+
-\newline
+Si tratta di un'applicazione \textbf{back-end only} che \textit{gestisce prestiti di libri di un sistema bibliotecario} con \textit{una o più sedi}. Essa, oltre ad essere in grado di gestire i prestiti, possiede la capacità di gestire i libri, la loro \textit{posizione}, lo \textit{staff} che ne amministra i \textit{prestiti} e gli \textit{utenti} che ne fanno richiesta.
-Grazie a questa applicazione è possibile creare, visualizzzare, modificare e rimuovere in tempo reale lo stato di prestito dei libri. I prestiti sono descritti da una data di inizio, di fine, uno stato, un libro, un utente ed un operatore. Si ritiene che sia importante sottolineare che durante la progettazione si è presa la decisione che un prestito possa consistere in esattamente una unità di libro, in maniera tale che questo livello di granularità permetta all'utente, in caso di prestito contemporaneo di più libri, di non doverli restituire tutti in blocco.
+
-\newline
+Grazie a questa applicazione è possibile \textit{creare, visualizzzare, modificare e rimuovere} in tempo reale lo stato di cessione dei libri. I prestiti sono descritti da una \textit{data di inizio}, \textit{di fine}, uno \textit{stato}, un \textit{libro}, un \textit{utente} ed un \textit{operatore}. Si ritiene che sia importante sottolineare che durante la progettazione si è presa la decisione che un prestito debba consistere in esattamente una unità di libro, in maniera tale che questo livello di granularità permetta all'utente, in caso di prestito "contemporaneo" (in realtà avviene in rapida sequenza dal punto di vista del backend) di più libri, di non doverli restituire tutti in blocco.
-Altra caratteristica è la separazione tra concetto di libro ed "unità di libro", questo per gestire in maniera efficiente il caso molto frequente in cui il sistema bibliotecario possieda più copie dello stesso libro; nella nostra implementazione ogni singola unità (Item) corrisponderebbe in maniera univoca all'unità fisica corrispondente.
+
-\newline
+Altra caratteristica è la \textit{separazione} tra \textit{"concetto di libro"} ed \textit{"unità di libro"}, questo per gestire in maniera efficiente il caso molto frequente in cui il sistema bibliotecario possieda più copie dello stesso libro; nella nostra implementazione ogni singola unità (descritta come \textit{"Item"}) corrisponderebbe in maniera univoca all'unità fisica corrispondente. In altre parole, se il sistema bibliotecario è in possesso di \textit{n} libri identici (stesso ISBN) ognuno di essi è identificabile univocamente.
-Una feature degna di nota (che andrebbe a soddisfare il requisito del self-loop) è la possibilità di sapere se nel sistema bibliotecario è disponibile il sequel (ammesso che esistano) di un determinato libro.
+
-\newline
+Una feature degna di nota (che andrebbe a soddisfare il requisito del \textit{self-loop}) è la possibilità di sapere se nel sistema bibliotecario è presente il \textit{prequel} (ammesso che esista) di un determinato libro assieme al suos tato di disponibilità.
+
 Allo stato attuale l'applicazione è stata pensata per essere utilizzata nell'area metropolitana di \underline{\textit{Brescia}} e \underline{\textit{Novara}}, con un \textit{\textbf{target iniziale}} ristretto agli utenti delle \textit{\textbf{sedi del sistema blibliotecario comunale}} delle rispettive città.
-\newline
+
 A seconda della trazione che potrebbe ricevere una volta lanciata, si potrà valutare un'eventuale \textit{espansione} del territorio coperto e degli enti (sia pubblici che privati) interessati.

doc/chapters/02_progetto.tex

@@ -1,41 +1,34 @@
 \section{Progettazione}
 
-Nella fase iniziale di progettazione, invece che iniziare direttamente con la stesura di un diagramma UML delle Classi si è ritenuto più comodo sviluppare prima l'idea su carta disegnando un semplice diagramma ER (Entity Relationship).
+Nella fase iniziale di progettazione, invece che iniziare direttamente con la stesura di un \textit{diagramma UML delle Classi} si è ritenuto più comodo sviluppare prima l'idea su carta disegnando un semplice \textit{diagramma ER} (Entity Relationship), mostrato in figura \ref{fig:er}.
 
 \begin{figure}[h!]
   \centering
-  \includegraphics[scale=0.6]{img/logo.png}
+  \includegraphics[scale=0.8]{img/er.pdf}
   \caption{Diagramma ER}
   \label{fig:er}
 \end{figure}
 
-Una volta stesa una bozza definitva e chiara sulle entità, relazioni e relativi attributi da definire si è passati a trasporre in una forma più dettagliata e più comoda per noi da tenere come riferimento, ossia un EER (Enhaced Entity Relationship) disegnato con il tool MySQL Workbench.
+Una volta stesa una bozza definitva e chiara sulle entità, relazioni e relativi attributi da definire si è passati a trasporre in una forma più dettagliata e \textit{più comoda} per noi da tenere come riferimento, ossia un \textit{EER} (\textit{Enhaced Entity Relationship}) disegnato con il tool \textit{MySQL Workbench}.
 
 \begin{figure}[h!]
   \centering
-  \includegraphics[scale=0.6]{img/logo.png}
+  \includegraphics[scale=0.9]{img/eer.pdf}
   \caption{Diagramma EER}
   \label{fig:eer}
 \end{figure}
 
-\begin{figure}[h!]
-  \centering
-  \includegraphics[scale=0.6]{img/logo.png}
-  \caption{Diagramma delle Classi}
-  \label{fig:classi}
-\end{figure}
-
 \section{Struttura}
 
-L'applicazione è strutturata in diversi package con ognuno funzionalità specifiche:
+L'applicazione è strutturata in diversi \textit{package} con ognuno funzionalità specifiche:
 
 \begin{itemize}
-  \item \textbf{com.mivan.model:} In questo package sono presenti tutte le entità del modello dati dell'applicazione, implementate in classi come mostrate in figura \ref{fig:classi}. Per gestire la persistenza dei dati di un database relazionere, per tali classi sono state utilizzate le annotazioni delle JPA (Java Persistence API).
+  \item \textbf{com.mivan.model:} In questo package sono presenti tutte le entità del modello dati dell'applicazione, implementate in classi \textit{Author}, \textit{Book}, \textit{Location}, \textit{Staff}, \textit{User}, \textit{Loan}, \textit{Item} e \textit{Item}. Per gestire la persistenza dei dati di un database relazionere, per tali classi sono state utilizzate le annotazioni delle \textit{JPA} (\textit{Java Persistence API}).
   \item \textbf{com.mivan.repository:} In questo package sono implementate le query per l'interrogazione al database.
-  \item \textbf{com.mivan.exception:} In questo package sono contenute le classi che gestiscono le eccezioni generate dalle interrogazioni al database.
 \end{itemize}
 
 \section{Test}
 
-Per verificare l'effettivo funzionamento del programma sono stati sviluppati dei test d'integrazione, posizionati all'interno della cartella \code{mivan/src/test/java/}.\newline
+Per verificare l'effettivo funzionamento del programma sono stati sviluppati dei test d'integrazione, posizionati all'interno della cartella \code{mivan/src/test/java/}.
-Per i JUnit test volti a verificare la corretta esecuzione delle operazioni CRUD (Create, Read, Update, Delete) è stato fatto uso dell'engine H2, il quale consente di eseguire tali operazioni su un database temporaneo caricato in memoria (RAM). Tale approccio consente arginare del tutto il problema di intaccare il database persistente dai dati fittizzi dei test.
+
+Per i \textit{JUnit test} volti a verificare la \textit{corretta esecuzione} delle operazioni \textit{CRUD} (\textit{Create, Read, Update, Delete}) è stato fatto uso dell'engine \textit{H2}, il quale consente di eseguire tali operazioni su un \textit{database temporaneo} caricato in memoria (\textit{RAM}). Tale approccio consente \textit{arginare} del tutto il problema di intaccare il database persistente dai dati fittizzi dei test.

doc/chapters/03_esecuzione.tex

@@ -1,14 +1,15 @@
 \section{Requisiti}
 
-L'applicazione è stata sviluppata, eseguita e testata su sistemi UNIX Like, in particolare sulla distribuzione GNU/Linux Debian.\newline
+L'applicazione è stata sviluppata, eseguita e testata su sistemi \textit{UNIX Like}, in particolare sulla distribuzione \textit{GNU/Linux Debian}.\newline
 Per questo questo motivo le istruzioni che seguono saranno incentrate su questo ambiente, ma dovrebbero valere per tutti gli altri sistemi.\newline
-Per rendere la propria macchina pronta ad eseguire l'applicazione è necessario installare i pacchetti \code{openjdk} (la versione 8 è sufficiente) ed \code{mvn}; in caso di Debian o derivate si usa il seguente comando:
+Per rendere la propria macchina pronta ad eseguire l'applicazione è necessario installare i pacchetti \code{openjdk} (la versione 8 è sufficiente) e \code{mvn} corrispondenti rispettivamente a \textit{Open Java Development Kit} ed al tool \textit{Apache Maven}; in caso di Debian o derivate si usa il seguente comando:
 \newline
 \begin{lstlisting}[style=BashInputStyle]
     $ sudo apt-get install openjdk-8-jdk mvn
 \end{lstlisting}
 
-In caso si volesse usare Docker allora le dipendenze sono docker-compose, ed ovviamente docker stesso. Compose è presente nella maggior parte delle repo delle distro, il problema è che non è sempre aggiornato, per cui si ovvierà a questo possibile problema per mezzo di pip.\newline
+In caso si volesse usare \textit{Docker} allora le dipendenze sono \textit{docker-compose}, ed ovviamente \textit{docker} stesso. \textit{Compose} è presente nella maggior parte delle repo delle distro, il problema è che non è sempre aggiornato, per cui si ovvierà a questo possibile problema per mezzo di \code{pip}.
+
 La serie di comandi è la seguente, in caso di distro diversa da Debian usare il relativo gestore di pacchetti in sostituzione ad apt:
 \newline
 \begin{lstlisting}[style=BashInputStyle]
@@ -29,8 +30,9 @@ Per eseguire i test è necessario spostarsi all'interno della cartella del sorge
 
 \section{Build}
 
-L'operazione di build genera un file \code{.jar} all'interno della cartella di nome \code{target}, la quale se non è già presente verrà creata runtime.\newline
+L'operazione di build genera un file \code{.jar} all'interno della cartella di nome \code{target}, la quale se non è già presente \textit{verrà creata a runtime}.
-Per seguire la build è necessario spostarsi all'interno della cartella del sorgente dell'applicazione e poi lanciare il relativo comando:
+
+Per eseguire la build è necessario spostarsi all'interno della cartella del sorgente dell'applicazione e poi lanciare il wrapper \code{mvnw}:
 \newline
 \begin{lstlisting}[style=BashInputStyle]
     $ cd mivan
@@ -48,19 +50,19 @@ L'avvio immediato dell'applicazione, utile durante lo sviluppo si esegue con un
 
 \section{Avvio tramite Docker}
 
-Per poter eseguire l'applicazione per mezzo di Docker container è necessario soddisfare i requisiti indicati all'inizio di questo capitolo. Il vantaggio di usare Docker è che semplifica notevolmente sia la fase di sviluppo che di deploy dell'applicazione, specialmente per l'ultimo punto che ne riduce in maniera sensibile sia il tempo che la complessità.
+Per poter eseguire l'applicazione per mezzo di Docker container è necessario soddisfare i requisiti indicati all'inizio di questo capitolo. Il vantaggio di usare Docker è che semplifica \textit{notevolmente} sia la fase di sviluppo che di \textit{deploy} dell'applicazione, specialmente per l'ultimo punto che ne riduce in maniera sensibile sia il tempo che la complessità.
 
 \begin{leftbar}
-      \noindent\textbf{Nota:}\newline Per poter utilizzare docker è necessario avere i privilegi di root od essere nel gruppo \code{docker}!.
+      \noindent\textbf{Nota:}\newline Per poter utilizzare docker è necessario avere i privilegi di root od essere nel gruppo \code{docker}!
 \end{leftbar}
 
-Un comodo strumento di cui faremo uso per gestire i container è Compose, di cui, dato il file \code{.yml} già compilato alla radice della repository eseguiamo il comando di build:
+Un comodo strumento di cui faremo uso per gestire i container è \textit{Compose}, di cui, dato il file \code{.yml} già compilato alla radice della repository eseguiamo il comando di build:
 \newline
 \begin{lstlisting}[style=BashInputStyle]
     $ sudo docker-compose build
 \end{lstlisting}
 
-E poi, una volta buildate le immagini dei container, le eseguiamo:
+E poi, una volta buildate l'immagine del container, lo lanciamo:
 \newline
 \begin{lstlisting}[style=BashInputStyle]
     $ sudo docker-compose up