Precedentemente negli articoli  e , abbiamo visto le nozioni fondamentali di Apache Maven, come pure una panoramica di . In questo articolo analizziamo una caratteristica molto interessante. Vedremo che Maven è in grado di generare  il sito web di un progetto (documentazione, Javadoc, etc…), costituito da pagine HTML statiche. La fase in cui si producono queste informazioni è chiamata site.

Se creiamo un progetto con Maven, supponiamo di farlo  e di chiamarlo mytest. Il da lanciare per generare il sito è:

mvn site

Dopo di che verrà letto il pom.xml e generato un sito documentale del progetto. L’output è disponibile per default, nella directory ${basedir}/target/site, che contiene il sito appena creato.

La pagina index.html dal sito del progetto mytest è illustrato di seguito:

In abbiamo visto che è possibile inserire nel pom.xml alcune informazioni generali del progetto, quali ad esempio il nome, la descrizione, la licenza, l’organizzazione proprietaria, etc… Orbene queste informazioni appariranno giustamente nel sito generato. Di queste informazioni ne abbiamo introdotte solo alcune, altre sono nella documentazione ufficiale.

Deploy

La fase site è responsabile della generazione di un sito di documentazione per un progetto Maven. E’ tuttavia spesso necessario un passaggio finale per questo ciclo, ovvero la distribuzione su un server web. Quindi, per distribuire un sito, è necessario procedere come segue…
Se il sito è già stato generato:

mvn site:deploy

Se invece si desidera generare il sito e distribuirlo in un colpo solo basta eseguire:

mvn site-deploy

In genere, per garantire che la documentazione sia aggiornata, è meglio eseguire un:

mvn clean site-deploy

Ovviamente, prima di far questo è necessaria un po’ di configurazione… Vediamo come procedere:
Per distribuire il sito, verrà utilizzata la sezione site del POM, mediante la quale sarà possibile deployare il sito del progetto in un server remoto, utilizzando una serie di protocolli, tra cui FTP, SCP e webDAV.
Supponiamo di distribuire il sito utilizzando webDAV. Per prima cosa bisogna predisporre un progetto Maven per un "site-deploy", appunto per questo occorre una sezione nella sezione del pom.xml ( vedremo più avanti cosa è questa nuova sezione distributionManagement ).
Supponiamo di distribuire il sito via webDAV:

 …
 
  
   mytest.website id>
    dav: https://cosenonjaviste.it//sample-project/ url>
  
 
 …
 Project>

Se il server Web richiede un nome utente e una password, occorre aggiungere al file $HOME/.m2/settings.xml le seguenti righe:

...

 
  mytest.website
  my_username
  my_password
 

...

Si possono configurare anche eventuali permessi, ma per semplicità non entrerò nel merito e vi rimando a questo documento.
E’ necessario adesso settare nel pom.xml anche l’eventuale plug-in di protocollo, che sarà nel nostro caso webDAV. Potete trovare maggiori dettagli sulla corretta configurazione per questo tipo di deploy ai seguenti indirizzi:

• How To Deploy Site With “Mvn Site-Deploy” – WebDAV Example
• How do I deploy a site?

A questo punto basterà come abbiamo detto, lanciare il comando:

mvn sito-deploy

per veder creato e deployato un sito completo.

Distribution management

Apriamo una parentesi per introdurre in breve la sezione  distributionManagement. Questa sezione permette la gestione della procedura di distribuzione dei file generati dal processo di build (vedi ““). La sezione ha una struttura simile a quella mostrata nel listato seguente.

 …
 
  …
  http://cosenonjaviste.it/repository_path
  deployed
 
 …

Gli elementi sono:

• downloadURL: indirizzo del repository utilizzabile da parte di altri POM per ottenere il manufatto prodotto dal build del POM presente;
• status: questa informazione non dovrebbe essere manipolata direttamente, si tratta di un’area di competenza di Maven che viene aggiornata ogni qualvolta si effettua un deployment;
• repository: Mentre le sezioni repository del POM permettono di specificare le posizioni e le modalità con cui Maven è in grado di effettuare il download dei vari manufatti necessari al POM, questa sezione, all’interno dell’elemento distributionManagement, permette di specificare in fase di deployment, dove e come memorizzare i manufatti prodotti, all’interno del repository.
  Qualora la sezione snaposhotRepository non sia definita, le impostazioni dell’elemento repository sono utilizzati anche per la distribuzione di tipo snapshot.
  Vediamo da quali tag è composto questo elemento:
  • id e name: entrambi i campi servono per identificare il repository. Mentre il campo id è un identificatore univoco, name serve per rendere il campo leggibile;
  • uniqueVersion: è un attributo booleano il cui valore true serve ad incaricare a Maven del versionamento dei vari manufatti pubblicati ( generazione di un numero di versione univoco da associare ai manufatti memorizzati nel repository );
  • url: rappresenta l’informazione principale dell’elemento repository. Permette di specificare sia l’ubicazione, sia il protocollo di trasporto da utilizzare, per il trasferimento dei manufatti generati dal processo di build;
  • layout: permette di specificare la struttura del repository. In particolare: default indicata la struttura introdotta con Maven 2, mentre legacy rappresenta la struttura precedente.

  Vediamo un esempio di sezione repository:
  

  
   …
  
   
    Hello
    Hello
    ftp://repository-url
   
  
   …
  
  

  A questo punto basterà eseguire mvn deploy per depositare il pacchetto generato, nel repository remoto (vedi “mvn deploy” in  );

• snapshotRepository: come la sezione repository, ma come suggerisce il nome, specifica le impostazioni per le distribuzione di tipo snapshot ( di solito vuol dire che la versione è una versione ancora in fase di sviluppo ).
  Se non presente, le impostazioni dell’elemento repository sono utilizzate anche per la distribuzione di tipo snapshot;
• relocation: questa sezione si rende necessaria ogniqualvolta si abbia la necessità di rilocare un progetto. Cioè ad esempio è possibile assistere che dei progetti, inizialmente nati all’interno di organizzazioni commerciali, vengano donati alla comunità open source, per esempio possono essere donati ad Apache. La sezione relocation, oltre alle informazioni tipiche come nuovi grupId, artifacId, permette di specificare un messaggio con opportuna spiegazione delle motivazione che hanno dato luogo alla rilocazione (vedi reference);
• site: che abbiamo già visto e che vedremo anche di seguito. 😉

Site distribution (distribuzione del sito)

Oltre che distribuire ai repository, distributionManagement è responsabile della distribuzione del sito di progetto e della documentazione. In questa sezione è possibile specificare le modalità mediante la quale questo processo può essere eseguito.

 …
 
  …
   
    mytest.website
    Mytest Website
    dav: https://cosenonjaviste.it//sample-project/
  
  …
 
 …

La struttura di questo elemento prevede gli stessi elementi id, name e url, analizzati per la sezione repository in distributionManagement. Per il resto si riveda quanto abbiamo esposto in Deploy.

Reporting

Il sito statico generato è costituito da pagine HTML e contiene sia pagine che descrivono il progetto sia report di analisi del codice, che di documentazione. Proviamo ad aggiungere all’interno del file pom.xml la sezione reporting, la quale si occupa di definire e configurare dei propri plug-in che contengono le impostazioni per poter lanciare alcuni report.

 …
 
  ${basedir}/target/site
  
   
    maven-project-info-reports-plugin
    
     
    
   
  
 
 …

Questa sezione è assolutamente consistente con la sezione di build, la differenza principale è che il controllo dei goal avviene nella sezione reportSet anziché in executions. Pertanto, avendo compreso il funzionamento di build (vedi in ), quella di reporting dovrebbe risultare assolutamente immediata. Gli unici elementi diversi sono:

• excludeDefaults: di tipo boolean, se impostato a true, forza Maven a non produrre le informazioni tipicamente generate per default. Queste sono prodotte utilizzando il plug-in: maven-project-info-reports-plugin (vedi documentazione);
• outputDirectory: che, come suggerisce il nome, specifica la directory in cui produrre il sito delle informazioni. Questa, per default, è $basedir/target/site.

Per esempio utilizziamo all’interno del file pom.xml il seguente listato:

 …
 
  
    org.apache.maven.plugins
    maven-javadoc-plugin
    
  
   
    org.apache.maven.plugins
    maven-surefire-report-plugin
   
   
    org.apache.maven.plugins
    maven-checkstyle-plugin
   
   
    org.apache.maven.plugins
    maven-jxr-plugin
   
   
    org.apache.maven.plugins
    maven-pmd-plugin
   
   
    org.codehaus.mojo
    jdepend-maven-plugin
   
   
    org.codehaus.mojo
    taglist-maven-plugin
   
   
    org.codehaus.mojo
    cobertura-maven-plugin
   
   
    org.codehaus.mojo
    findbugs-maven-plugin
     
       Low
       Default
     
   
  
 
 …

Analizziamo adesso i plug-in utilizzati:

• Javadoc: Il plugin è usato per generare la documentazione Javadoc del progetto.
  Vedi: How do I generate a Javadoc report for a site?;
• Checkstyle: Il plugin può essere usato per generare report sulla qualità dello stile del codice del progetto, ad esempio su utilizzi non standard di java ( if senza parentesi graffe, mancanza di commenti etc..).
  Vedi: How do I generate a Checkstyle code style report for a site?;
• Cobertura: Cobertura è un tool che calcola la percentuale di codice Java coperta dai casi di test! Può quindi essere usato per identificare le parti di codice Java che non sono testate dalle nostre classi di test. Nel caso mostrato in figura sottostante si nota che throw new UnsupportedOperationException(); non è coperto da test.
  Vedi: How do I generate a Cobertura test coverage report for a site?;

• PMD: è un plug-in che genera report sulla qualità del codice (codice non usato, if non necessari, codice non ottimale etc..) e sulla duplicazione del codice (CPD).
  Vedi: How do I generate PMD and CPD reports for a site?;
• FindBugs: analizza il codice segnalando possibili bug.
  Vedi: How do I generate a FindBugs bug pattern report for a site?;
• JDepend: effettua un’analisi approfondita dell’utilizzo delle classi all’interno di un programma realizzato in Java e ne valuta l’efficacia. utilizzando criteri come: estensibilità, dipendenze, riutilizzabilità, manutenibilità, controllo delle dipendenze e molto altro;
• Maven Surefire Report: report che mostra l’esito dei test evidenziando eventuali errori.
  Vedi: How do I generate a unit test report for a site?;
• JRX: il plugin JXR produce un riferimento incrociato dei sorgenti del progetto. I report generati rendono più facile all’utente fare riferimento e trovare specifiche linee di codice. E’ anche utile se usato con il plugin PMD per referenziare gli errori presenti nel codice. Inoltre se un sito di progetto comprende anche il Javadoc, JXR permetterà i riferimenti alle pagine Javadoc pertinenti.
  Vedi: How do I generate a JRX report for a site?;
• Tag list: elenco di tutti i tag, tipo ad esempio TODO, presenti nel codice;

Naturalmente i plug-in per i report sono molti di più! Questi sono solo alcuni e in ogni caso a questo link potete trovare una lista di plug-in disponibili per Maven, fra i quali molti di reporting.

Adesso se non lo avete già fatto, proviamo a creare un progetto di nome mytest e utilizziamo come spunto, questo . Per semplicità il POM è privo della parte di deploy.
Lanciamo la creazione del sito eseguendo:

mvn site

Oppure , click con il tasto destro sul progetto e poi Rus As -> Maven build… specificando site nel campo goals.
Alla fine dell’esecuzione troveremo all’interno della directory target/site il sito web del nostro progetto.  
Il menù principale a sinistra contiene due sezioni:

• Project Information: include informazioni generali sul progetto;
• Project Reports: contiene i report che abbiamo impostato nel file pom.xml.

Riferimenti

Per approfondire quanto visto, eccovi alcuni link di riferimento:

• (EN) The Complete Reference – Site Generation;
• (EN) How To Deploy Site With “Mvn Site-Deploy” – WebDAV Example;
• (EN) How do I generate basic documentation for a project using maven site?
• (EN) How do I deploy a site?
• Gestione di una web app con Eclipse e Maven su Blog4j;
• (EN) POM Reference – Distribution Management.