Java – Utilizzo di jar in normali “Java Project” di Eclipse

Mi è capitato più volte di spiegare sui forum Java come utilizzare delle librerie (file .jar) all’interno di “normali” progetti Java con il IDE Eclipse. In questo articolo fornirò questa spiegazione in maniera più completa ed accurata con l’aiuto anche di alcune immagini.

Prima di continuare, è bene chiarire quale è il contesto generale a cui faccio riferimento:

  • Si utilizza Eclipse come IDE, ragionevolmente va bene qualunque versione, vecchia o recente che sia, e perlomeno sicuramente le pacchettizzazioni “for Java Developers” e “for Enterprise Java Developers” (quest’ultima in passato si chiamava “for Java EE Developers”).
  • È stato creato un “normale” Java Project, per intenderci quello che si ottiene usando le voci di menù File → New → Project... e poi selezionando nel wizard “Java Project”.
    Nota: questa tipologia di progetto si usa solitamente per delle semplici applicazioni console o grafiche (AWT, Swing, ecc...).
  • Non si utilizzano strumenti di build specifici come Apache Ant, Apache Maven, Gradle o altro.

Se le premesse sono queste allora, purtroppo, è necessario gestire esplicitamente “a mano” eventuali librerie esterne. È bene precisare subito che con Eclipse ci sono diversi modi per configurare e referenziare dei file .jar in un normale Java Project, non esiste un solo ed unico modo. Quello che descriverò di seguito è solamente uno dei possibili modi, che comunque è abbastanza semplice, “pulito” e permette anche di rendere più facilmente “portabile” il progetto su un altro Eclipse (anche eventualmente su un’altra macchina!).

Passo 1) Creazione della directory

Innanzitutto si crea una nuova directory chiamata lib (o libs o library o altro, il nome esatto non è molto rilevante) nella directory principale del progetto. Questa nuova directory in pratica deve stare allo stesso livello della directory src dove ci sono i sorgenti.

Per creare materialmente la directory ci sono svariati modi, ad esempio si può usare la vista “Project Explorer”, poi si fa click con tasto destro del mouse sul progetto e infine si sceglie il menù New → Folder che visualizza la dialog per creare la directory.

Una volta creata la directory la struttura dovrebbe essere come la seguente:

Passo 2) Copia del file .jar

Si copiano i file .jar in questa cartella lib (o come è stata chiamata). Si può fare questo internamente o esternamente ad Eclipse. Come si effettua materialmente la copia (da un “esplora risorse” del sistema, da un prompt dei comandi o altro) non è particolarmente importante. Se si fa tutto esternamente ad Eclipse bisogna solo ricordarsi di fare poi in Eclipse un refresh della cartella lib (o al limite di tutto il progetto) in modo che Eclipse “veda” il contenuto aggiornato della cartella. Se invece si fa una operazione di “incolla” già in Eclipse, è tutto automatico.

Supponiamo, per puro esempio, di voler utilizzare nel progetto la ben nota libreria log4j 1.2.x che per tanti anni (e in parte ancora oggi) ha rappresentato lo standard de facto per il logging nelle applicazioni Java. Per usare log4j 1.2 è sufficiente reperire un solo ed unico file .jar a cui farò riferimento di seguito con il nome di log4j-1.2.17.jar .

Alla fine della copia la situazione dovrebbe essere come la seguente:

Passo 3) Impostazione del Build Path

Si deve andare nelle “proprietà del progetto”. Ci sono diversi modi per arrivarci ma un modo semplice è fare click con tasto destro del mouse sul nome del progetto e poi scegliere “Properties” (o in alternativa selezionare il progetto e poi usare la combinazione Alt+Enter da tastiera).

Si deve quindi rintracciare la sezione denominata “Java Build Path” e poi selezionare la scheda “Libraries”. Poi si deve cliccare sul pulsante denominato “Add JARs...” (attenzione: non il “Add External JARs...”, c’è una differenza importante che è descritta al fondo di questo articolo nella sezione Nota finale).

Il pulsante “Add JARs...” visualizza una dialog che permette di selezionare il file .jar da aggiungere. Basta semplicemente arrivare alla cartella lib del progetto, aprila, selezionare il file .jar e confermare con “OK”.

Una volta aggiunto il file .jar, la scheda “Libraries” dovrebbe risultare simile alla seguente:

A questo punto è sufficiente cliccare su “Apply and Close” per confermare le modifiche e chiudere questa dialog.

Risultato

Il risultato finale nella vista “Project Explorer” dovrebbe essere come il seguente:

A prima vista sembrerebbe che ci sia una duplicazione. In realtà la cartella lib è la cartella fisica che contiene materialmente i file .jar mentre la voce “Referenced Libraries” è solamente un elemento logico di Eclipse che elenca le librerie referenziate. Non c’è di fatto alcuna duplicazione né problema a riguardo.

Se si è arrivati a questo punto, comunque, la libreria è correttamente referenziata nel progetto e può essere usata nei sorgenti.

Nota finale: la differenza tra “Add JARs...” e “Add External JARs...”

Nella scheda “Libraries” del “Java Build Path” ci sono vari pulsanti, tra cui i due più in alto chiamati “Add JARs...” e “Add External JARs...”. Esiste una differenza fondamentale e importante tra i due pulsanti che bisogna conoscere molto bene.

Il pulsante “Add JARs...” permette di inserire nel progetto un jar utilizzando un percorso “relativo” rispetto alla cartella del progetto. Se si analizza il file di progetto di Eclipse chiamato .classpath (che tecnicamente è un documento XML) tramite un normale editor di testo (es. Notepad++), si può osservare la seguente configurazione:

<classpathentry kind="lib" path="lib/log4j-1.2.17.jar"/>

Si può ben notare che il percorso è composto solo da lib/ . Non c’è alcun riferimento al nome del progetto né al percorso assoluto dove risiede fisicamente il progetto. Questo in sostanza permette di rendere “portabile” il progetto. Se si sposta il progetto su un altro Eclipse, anche su un’altra macchina fisica, il riferimento alla libreria resta correttamente impostato (a patto di portarsi dietro anche la cartella lib, ovviamente!).

Il pulsante “Add External JARs...” invece permette di scegliere un file .jar ovunque sul file-system. Si può quindi referenziare qualunque .jar anche esterno al progetto ma lo svantaggio è che nel progetto viene inserito un percorso “assoluto” al file jar.
Se si prova ad inserire il jar presente nella cartalla lib usando “Add External JARs...”, si può successivamente vedere nel file .classpath una configurazione come la seguente:

<classpathentry kind="lib" path="C:/……ecc……/MyWorkspace/progetto-prova/lib/log4j-1.2.17.jar"/>

La presenza di un percorso “assoluto” rende in generale il progetto meno facilmente portabile. Potrebbe non essere un problema in molti casi ma è comunque un aspetto da sapere e tenere ben presente.