Precedentemente negli articoli Organizziamoci con Maven – Parte I e Parte II, abbiamo visto le nozioni fondamentali di Apache Maven, come pure una panoramica di elementi avanzati del  file POM. 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 usando eclipse e di chiamarlo mytest. Il comando 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 Maven sveliamo un POM di segreti 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 <site> nella sezione <distributionManagement> del pom.xml ( vedremo più avanti cosa è questa nuova sezione distributionManagement ).
Supponiamo di distribuire il sito via webDAV:

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

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

...
<servers>
 <server>
  <id>mytest.website</id>
  <username>my_username</username>
  <password>my_password</password>
 </server>
</servers>
...

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:

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 “Maven sveliamo un POM di segreti“). La sezione ha una struttura simile a quella mostrata nel listato seguente.

<project>
 …
 <distributionManagement>
  …
  <downloadUrl>http://cosenonjaviste.it/repository_path</downloadUrl>
  <status>deployed</status>
 </distributionManagement>
 …
</project>

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:

    <project>
     …
    <distributionManagement>
     <repository>
      <id>Hello</id>
      <name>Hello</name>
      <url>ftp://repository-url</url>
     </repository>
    </distributionManagement>
     …
    </project>
    

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

    • 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.

    <project>
     …
     <distributionManagement>
      …
       <site>
        <id>mytest.website</id>
        <name>Mytest Website</name>
        <url>dav: https://cosenonjaviste.it//sample-project/</url>
      </site>
      …
     </distributionManagement>
     …
    </project>
    

    La struttura di questo elemento prevede gli stessi elementi idname 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.

    <project>
     …
     <reporting>
      <outputDirectory>${basedir}/target/site</outputDirectory>
      <plugins>
       <plugin>
        <artifactId>maven-project-info-reports-plugin</artifactId>
        <reportSets>
         <reportSet></reportSet>
        </reportSets>
       </plugin>
      </plugins>
     </reporting>
     …
    </project>
    

    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 Maven sveliamo un pom di segreti), 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:

    <project>
     …
     <reporting>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
      </plugin>  
      <plugins>
       <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-report-plugin</artifactId>
       </plugin>
       <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-checkstyle-plugin</artifactId>
       </plugin>
       <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jxr-plugin</artifactId>
       </plugin>
       <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-pmd-plugin</artifactId>
       </plugin>
       <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>jdepend-maven-plugin</artifactId>
       </plugin>
       <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>taglist-maven-plugin</artifactId>
       </plugin>
       <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>cobertura-maven-plugin</artifactId>
       </plugin>
       <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>findbugs-maven-plugin</artifactId>
         <configuration>
           <threshold>Low</threshold>
           <effort>Default</effort>
         </configuration>
       </plugin>
      </plugins>
     </reporting>
     …
    </project>
    

    Analizziamo adesso i plug-in utilizzati:

    • 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 pom.xml. Per semplicità il POM è privo della parte di deploy.
    Lanciamo la creazione del sito eseguendo:

    mvn site

    Oppure se state usando eclipse, 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:

9 Posts

Sono laureato in Ingegneria Informatica e lavoro dal 2008 come sviluppatore Java presso OmniaGroup. Sviluppo principalmente applicazioni web soprattutto su piattaforme alternative come ad esempio lo stack JSF+Spring+Hibernate (o altri ORM) oppure lo stack JavaScript(JQuery o ExtJS)+Spring+Hibernate su Tomcat, o sui principali AS (WebSphere,Weblogic,Glassfish, Jboss). Nei ritagli di tempo mi diletto a programmare su piattaforma Android e con altri linguaggi, quali ad esempio Python. LinkedIn profile