Sezione restaurant server finita tranne listing CRUDUtils

bibliography.bib

@@ -1,6 +1,6 @@
 @online{guacdoc:arch,
 	title = "Guacamole Manual, Chapter 1. Implementation and architecture",
-	author = "The Apache Software Foundation", 
+	author = "The Apache Software Fundation", 
 	url = "https://guacamole.apache.org/doc/gug/guacamole-architecture.html",
 	note = "[Online; in data 9-aprile-2018, traduzione e rielaborazione proprie]"
 }
@@ -10,6 +10,12 @@
 	url = "https://ionicframework.com/framework",
 	note = "[Online; in data 30-aprile-2018]"
 }
+@online{guacamole:website,
+	title = {Apache Guacamole\copyright},
+	author = "The Apache Software Foundation", 
+	url = "https://guacamole.apache.org",
+	note = "[Online; in data 1-maggio-2018]"
+}
 @online{agomir:website,
 	title = "Agomir S.p.A. - Software - Sistemi - Servizi",
 	author = "Agomir S.p.A.", 

main.tex

@@ -48,7 +48,7 @@
 % listings configuration
 \begin{it}
 	\renewcommand{\lstlistingname}{Listato}
-	\renewcommand{\lstlistlistingname}{Lista dei listati}
+	\renewcommand{\lstlistlistingname}{Elenco dei listati}
 \end{it}
 \lstset{
 	basicstyle=\small\ttfamily,
@@ -57,7 +57,11 @@
 	columns=fullflexible,
 	commentstyle=\color{gray},
 	keywordstyle=\bfseries,
-	escapeinside={\%*}{*)}
+	escapeinside={\%*}{*)},
+  aboveskip=2em,
+  captionpos=b,
+  abovecaptionskip=1em,
+  belowcaptionskip=1em
 }
 
 \begin{document}
@@ -124,17 +128,22 @@
 \begin{it}
 	\section{Gestione dei progetti}
 
-	Non ho diretto controllo manageriale su ciò che sviluppo in azienda, in quanto ho un ruolo simile a quello di un
+	Non ho diretto controllo manageriale su ciò che sviluppo in azienda,
-	dipendente. L'incarico di gestire l'andamento dei progetti spetta a Mario Goretti, A.D. dell'azienda e capo del settore
+  in quanto ho un ruolo simile a quello di un dipendente. L'incarico di gestire
-	di sviluppo software gestionale (\textsc{SWG}), e ai suoi collaboratori. 
+  l'andamento dei progetti spetta a Mario Goretti, A.D. dell'azienda e capo
+  del settore di sviluppo software gestionale (\textsc{SWG}), e ai suoi collaboratori. 
 	
-	In generale sviluppo i progetti da solo. Collaboro con il collega Daniele Crippa per l'interfacciamento con i software
+	In generale sviluppo i progetti da solo. Collaboro con il collega Daniele
-	aziendali esistenti e per l'organizzazione di nuovi progetti, nonché consigli e dritte varie.
+  Crippa per l'interfacciamento con i software aziendali esistenti e per
+  l'organizzazione di nuovi progetti, nonché consigli e dritte varie.
 	
-	Nonostante non abbia controllo totale \`e comunque mia responsabilità fare stime orarie sul lavoro da svolgere nonché
+	Nonostante non abbia controllo totale \`e comunque mia responsabilità fare
-	definire passi e \textit{milestone} per i vari progetti.
+  stime orarie sul lavoro da svolgere nonché definire passi e \textit{milestone}
+  per i vari progetti.
 	
-	Per aumentare la forza lavoro per lo sviluppo di applicazioni \textit{mobile} ho coordinato momenti di formazione ad alcuni dipendenti nei quali ho mostrato il principale funzionamento delle tecnologie che uso.
+	Per aumentare la forza lavoro per lo sviluppo di applicazioni \textit{mobile}
+  ho coordinato momenti di formazione ad alcuni dipendenti nei quali ho mostrato
+  il principale funzionamento delle tecnologie che uso.
 \end{it}
 \begin{en}
 	\section{Projects management}
@@ -145,23 +154,29 @@
 \begin{it}
 	\section{Il progetto principale: \textit{InteGRa Mobile}}
 	
-	Questa applicazione, una volta completata, dovrebbe permettere ad utenti in mobilità di interfacciarsi con alcune
+	Questa applicazione, una volta completata, dovrebbe permettere ad utenti in
-	funzioni del prodotto ERP di punta di Agomir: il gestionale
+  mobilità di interfacciarsi con alcune funzioni del prodotto ERP di punta di
-  \textit{InteGRa}\footnote{Sito internet di InteGRa ERP: \url{https://integra.agomir.com/}}. Nel dettaglio, sarà possibile accedere alle seguenti sezioni:
+  Agomir: il gestionale \textit{InteGRa}\footnote{Sito internet di InteGRa ERP:
+    \url{https://integra.agomir.com/}}. Nel dettaglio, sarà possibile accedere
+  alle seguenti sezioni:
 	
 	\begin{description}
-	\item[Ordini cliente] per registrare ordini di prodotti a clienti;
+	  \item[Ordini cliente] per registrare ordini di prodotti a clienti;
-	\item[Soggetti] per consultare informazioni anagrafiche di clienti e fornitori;
+	  \item[Soggetti] per consultare informazioni anagrafiche di clienti e fornitori;
-	\item[Agenda] per consultare e aggiungere eventi nel calendario presente nell'ERP, il quale si pu\`o integrare con \textit{Outlook};
+	  \item[Agenda] per consultare e aggiungere eventi nel calendario presente
-	\item[Magazzini] gestire e inventariare scorte in magazzino.
+      nell'ERP, il quale si pu\`o integrare con \textit{Outlook};
+	  \item[Magazzini] gestire e inventariare scorte in magazzino.
 	\end{description}
 	
-	In aggiunta, sarà possibile anche registrare le ore per interventi in trasferta, funzione gi\`a implementata
+	In aggiunta, sarà possibile anche registrare le ore per interventi in
-	nell'applicazione \textit{InteGRa.Service}, sviluppata nei periodi di alternanza precedenti. Tale lavoro non \`e
+  trasferta, funzione gi\`a implementata nell'applicazione
-	direttamente implementabile in \textit{InteGRa Mobile} a causa di differenze consistenti nelle architetture dei due prodotti.
+  \textit{InteGRa.Service}, sviluppata nei periodi di alternanza precedenti.
+  Tale lavoro non \`e direttamente implementabile in \textit{InteGRa Mobile} a
+  causa di differenze consistenti nelle architetture dei due prodotti.
 	
-	Inoltre, l'applicazione sarà in grado di funzionare in modo limitato anche senza connessione diretta ad
+	Inoltre, l'applicazione sarà in grado di funzionare in modo limitato anche
-	\textit{InteGRa}, permettendo la sincronizzazione dei dati modificati con il gestionale in un momento futuro.
+  senza connessione diretta ad \textit{InteGRa}, permettendo la sincronizzazione
+  dei dati modificati con il gestionale in un momento futuro.
 \end{it}
 \begin{en}
 	\section{The main project: \textit{InteGRa Mobile}}
@@ -202,8 +217,8 @@
     server (chiamato \textit{InteGRaREST}) che svolge il ruolo di intermediario.
 
   \item Tale componente è una Java WebApplication che utilizza una libreria
-    sviluppata internamente (chiamata \textit{restaurant}) per offrire le
+    sviluppata internamente (chiamata \textit{restaurant}) per offrire le rotte
-    servlet accessibili al client e per interagire con il database di
+    accessibili al client e per interagire con il database di
     \textit{InteGRa}, una normale istanza di \textit{PostgreSQL}.
 
   \item Nella fase di comunicazione tramite HTTP, i dati in input vengono
@@ -225,8 +240,7 @@
    in grado di gestire (in modo limitato) operazioni eseguite in mancanza di
    connessione alla rete. 
 
- \end{itemize}
+ \end{itemize} 
- 
 \end{it}
 \begin{en}
 	\blindtext
@@ -234,7 +248,44 @@
 
 \begin{it}
   \subsubsection{\textit{restaurant} -- lato server}
-\begin{lstlisting}[caption=Interfaccia della classe \textit{JsonProducer}, label=jsonprd-java, language=Java]
+  La libreria \textit{restaurant}\footnote{Il nome \textit{restaurant} è un
+    gioco di parole sull'acronimo REST.} viene importata
+  come una normale dipendenza Maven \cite{maven:website}. Essa dipende da:
+  \begin{description}
+    \item[Hibernate ORM] un famoso Object/Relation Mapper \cite{wiki:orm} per
+      Java, utile ad interrogare il database \textit{PostgreSQL} con facilità;
+    \item[GSON] una libreria di Google per serializzare e deserializzare oggetti
+      Java in JSON;
+    \item[Jersey] un'implementazione dell'API JAX-RS per realizzare gli endpoint
+      REST. Ciò avviene senza servlet ma tramite semplici
+      metodi contenuti in classi senza ``padre'' dette \textit{controller},
+      opportunamente decorati con le annotazioni nel package
+      \texttt{javax.ws.rs}.
+  \end{description}
+
+  Le operazioni richieste per interrogare la base di dati sono ulteriormente
+  semplificate dal codice contenuto in \textit{restaurant} su due livelli:
+  \begin{itemize}
+    \item È possibile eseguire normali operazioni di CRUD \cite{wiki:crud}
+      nonchè costruire manualmente query tramite i metodi statici della classe
+      \textit{CRUDUtils}, che lavorano in input e in output con istanze delle
+      classi ``entità'';
+    \item Inoltre, è possibile creare nuovi \textit{controller} con facilità
+      ereditando dalle classi astratte \textit{JsonProducer} (per
+      implementare funzioni al di fuori di CRUD),
+      \textit{ReadableRESTController} (per implementare operazioni in sola
+      lettura, equivalenti alla ``Read'' in CRUD) e \textit{CRUDRESTController}
+      (per implementare CRUD completi), che offono
+      metodi in grado di generare autonomamente risposte in JSON, sia in caso
+      di successo che in errore.
+  \end{itemize}
+
+  Seguono le interfaccie delle classi \textit{CRUDUtils}, \textit{JsonProducer},
+  \textit{ReadableRESTController} e \textit{CRUDRESTController}, complete di
+  Javadoc.
+\end{it}
+
+\begin{lstlisting}[caption=Interfaccia della classe \textit{JsonProducer}, label={lst:jsonprd-java}, language=Java]
 /**
  * Something that generates JSON responses
  */
@@ -242,7 +293,7 @@ public abstract class JsonProducer {
   
     protected static final Logger log = %*\ldots*);
   
-    protected static final Gson GSON;
+    protected static final Gson GSON = %*\ldots*);
   
     /**
      * Generates a json response with status 200 containing an object
@@ -288,7 +339,14 @@ public abstract class JsonProducer {
     protected Response require(Object s, String propName) { %*\ldots*) }
 }
 \end{lstlisting}
-\begin{lstlisting}[caption=Interfaccia della classe \textit{ReadableRESTController}, label=rdbrest-java, language=Java]
+\begin{it}
+  Per una migliore lettura del listato \ref{lst:jsonprd-java}, si precisa che la
+  classe \textit{Error} è una enumerazione Java contenente messaggi di errore
+  standard. La classe \textit{ErrorDetails}, invece, permette al codice esterno
+  di realizzare messaggi di errore personalizzati.
+\end{it}
+
+\begin{lstlisting}[caption=Interfaccia della classe \textit{ReadableRESTController}, label={lst:rdbrest-java}, language=Java]
 /**
  * A REST Controller only readable
  * @param <T> The readable entity class
@@ -372,7 +430,16 @@ public abstract class ReadableRESTController<T extends Readable,
     protected Response existing(InputStream requestBody) { %*\ldots*) }	
 }
 \end{lstlisting}
-\begin{lstlisting}[caption=Interfaccia della classe \textit{CRUDRESTController}, label=crudrest-java, language=Java]
+\begin{it}
+  Anche il listato \ref{lst:rdbrest-java} necessita di una breve spiegazione.
+  La classe astratta \textit{Readable}, vincolo sul primo parametro generico della classe,
+  è il padre di ogni classe ``entità'', mentre \textit{PrimaryKey<T>} è il padre
+  della classe contenente la chiave primaria di \textit{T}. Un'istanza della
+  classe figlia di \textit{PrimaryKey<T>} è contenuta come attributo nella
+  classe ``entità'' \textit{T}, che a sua volta estende \textit{Readable}. 
+\end{it}
+
+\begin{lstlisting}[caption=Interfaccia della classe \textit{CRUDRESTController}, label={crudrest-java}, language=Java]
 /**
  * A REST Controller readable and writable
  * @param <T> The readable and writable entity class
@@ -434,6 +501,12 @@ public abstract class CRUDRESTController<T extends CRUDable, U extends
     %*\ldots*)
 }
 \end{lstlisting}
+
+\begin{it}
+  Oltre a quanto mostrato, \textit{restaurant} contiene vari metodi utilità per
+  la gestione di file \texttt{.properties}, per la validazione dei dati in
+  input, per la registrazione della \textit{timestamp} di creazione o modifica
+  di un record, e altro ancora.
 \end{it}
 
 \begin{it}
@@ -568,7 +641,7 @@ per \textit{InteGRa Mobile}.
 	\label{fig:argosarch}
 \end{figure}
 
-\textit{Guac Remote} è basata su un'applicativo e libreria per la connessione a computer remoto chiamato \textit{Apache Guacamole}\footnote{\textit{Apache Guacamole}: \url{https://guacamole.apache.org}}.
+\textit{Guac Remote} è basata su un'applicativo e libreria per la connessione a computer remoto chiamato \textit{Apache Guacamole}\cite{guacamole:website}.
 Tale software è costituito da due parti: \cite{guacdoc:arch}
 \begin{description}
 	\item[\textit{guacamole-server} (o \textit{guacd})] un servizio scritto in C che funge da adattatore tra il protocollo \textit{guacamole} e i protocolli VNC, RDP o SSH, utilizzando questi ultimi per stabilire connessioni con gli host remoti;