Uno degli aspetti cruciali della configurazione di un application server è la gestione delle connessioni ai database.
In questo senso la tecnologia JEE (Java Enterprise Edition) ci offre uno strumento utilissimo: i Datasource.
Cosa fanno? Gesticono pool di connessioni al db evitando di dover scrivere codice per manipolare di connessione al database.
Vista così, un’applicazione, per usare un Datasource, avrà soltanto bisogno del suo JNDI name, ovvero un nome univoco esposto dal servizio JNDI (Java Naming and Directory Interface) o interrogare quest’ultimo per la risoluzione.
Per chi non è frequentatore abituale del mondo Java Enterprise JNDI è un servizio di directory che permette di indicizzare dati e oggetti all’interno di un’alberatura. Molto simile, concettualmente, a quello che accade con LDAP.
Di certo in un Datasource non può mancare la url di connessione al nostro db, come ad esempio la seguente:
jdbc:postgresql://HOST:PORT/DATABASE
Questa url, usata per la connessione ad un db PostgreSQL, richiede tre valori: host, numero di porta (5432 di default) e nome del database.
Ovviamente queste informazioni non bastano: avremo bisogno, come vedremo tra poco, anche di altre informazioni, come ad esempio delle credenziali valide (username/password), numero di connessioni da preallocare nel pool, ecc.
INSTALLAZIONE JDBC DRIVER
Prima di configurare un Datasource abbiamo bisogno di installare un JDBC driver.
JDBC è acronimo di Java Database Connectivity e un driver altro non è che un pezzo di software che gestisce, a basso livello, la connessione al database.
Ogni vendor (o community) ha, per le proprie soluzioni di database, i relativi JDBC driver. Questi sono liberamente scaricabili e installabili con modalità che possono variare in base all’application server che utilizziamo.
Per il nostro blogpost useremo il JDBC driver PostgreSQL, a mio avviso la miglior alternativa open source a più blasonati database commerciali.
Possiamo scaricare il driver al seguente link:
https://jdbc.postgresql.org/download.html
Per il nostro esercizio utilizzeremo la current version 42.0.0, fornita in tre flavor JDBC, 4.0, 4.1 e 4.2, che supportano rispettivamente Java 6, 7 e 8.
Poiché il nostro JBoss EAP 7 necessita di Java 8 procederemo a scaricare la seguente versione:
https://jdbc.postgresql.org/download/postgresql-42.0.0.jar
Per il download possiamo usare il comando wget direttamente da shell:
wget https://jdbc.postgresql.org/download/postgresql-42.0.0.jar
Una volta scaricato possiamo dare un’occhiata al contenuto dell’archivio:
jar tf postgresql-42.0.0.jar
Nell’output troveremo una directory META-INF, contenente metadati del package, e il package org.postgresql contentente le classi del driver.
La classe di default da utilizzare, per connessione di tipo non-XA, è org.postgresql.Driver, definita anche nel file META-INF/services/java.sql.Driver.
Per connessioni di tipo XA invece la classe da utilizzare è org.postgresql.xa.PGXADataSource.
Come accade nei package java i nomi delle classi corrispondo ai path della struttura della directory: ad esempio la classe org.postgresql.Driver è compilata nel file org/postgresql/Driver.class.
I più curiosi che hanno voglia di fare un po’ di hacking possono prelevare il sorgente presso l’url https://jdbc.postgresql.org/download/postgresql-jdbc-42.0.0.src.tar.gz e vedere cosa succede nel codice.
Prima di procedere dobbiamo aver installato JBoss EAP 7.0, la cui versione GA (Generally Available) può essere scaricata al link https://developers.redhat.com/downloads/?referrer=jbd.
Se ancora non lo avete esplorato vi rimando a questo nostro blogpost per un’introduzione a JBoss EAP 7.0.
Siamo pronti per installare il nostro driver JDBC! In EAP 7.0, così come in EAP 6.x, è possibile installare un JDBC driver in due modi:
- installazione come modulo
- installazione tramite deploy
La seconda opzione è sicuramente più rapida ma ci da meno controllo, per questo motivo Red Hat e la community JBoss/Wildfly danno come best practice l’installazione come modulo.
Per fare ciò abbiamo una via facile e una difficile. La via difficile è creare la struttura delle directory del modulo in JBOSS_HOME/modules, copiarvi il jar, definire il file module.xml.
La via facile, meno incline agli errori, è l’installazione del modulo tramite CLI.
Questo metodo, più sicuro e pulito, è la via che suggeriremo in questo blogpost.
L’operazione richiede di chiudere EAP, se attivo.
Eseguiamo la nostra CLI. Nell’esempio abbiamo installato EAP in /opt/jboss-eap-7.0 e assegnato l’ownership ricorsiva della directory all’utente/gruppo jboss/jboss.
sudo -u jboss /opt/jboss-eap-7.0/bin/jboss-cli.sh
Perché faccio privilege escalation come utente jboss? Perché dovrò scrivere nella directory /opt/jboss-eap-7.0/modules che gli appartiene. Una volta eseguita la CLI avremo la notifica che stiamo lavorando in modalità disconnessa:
E’ nostro interesse continuare a lavorare in modalità disconnected poiché il comando module viene esposto soltanto in questo stato. Apriamo un help del comando:
Come si può vedere la sintassi è abbastanza semplice. Per creare il nostro modulo abbiamo bisogno soltanto di definirne solo tre cose:
- nome del modulo
- path della risorsa(e) da installare
- dipendenze da altri package
module add --name=org.postgresql --resources=/tmp/postgresql-42.0.0.jar --dependencies=javax.api,javax.transaction.api
Una volta eseguito possiamo testare la nostra installazione. Chiudiamo la CLI e verifichiamo che in /opt/jboss-eap-7.0/modules sia stata creata una nuova struttura di directory org/postgresql/main. Al suo interno, il file jar che abbiamo scaricato e un file module.xml che definisce le specifiche del modulo. Il suo contentuto dovrebbe essere simile al seguente:
<?xml version="1.0" ?> <module xmlns="urn:jboss:module:1.1" name="org.postgresql"> <resources> <resource-root path="postgresql-42.0.0.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
Fantastico, la prima parte di installazione è completata! Ora dobbiamo definire il modulo dalla CLI nel subsystem Datasources.
Per fare ciò riavviamo il nostro EAP (nell’esempio uso la modalità standalone):
sudo -u jboss /opt/jboss-eap-7.0/bin/standalone.sh
Parentesi: per comodità quando lavoro in constesti laboratoriali eseguo le mie istanze all’interno di una sessione screen o tmux, in modo da poterne anche fare il detaching, se necessario. Se non sapete di cosa stiamo parlano date un’occhiata a questo interessante blogpost su tmux qui sul nostro blog. Non ne farete più a meno!
Una volta attivo EAP, eseguiamo la CLI:
sudo -u jboss /opt/jboss-eap-7.0/bin/jboss-cli.sh -c
Questa volta, passando l’opzione -c (in alternativa –controller) ci connettiamo direttamente a EAP.
Una delle cose più belle della CLI è l’auto-completion, presente per tutto, nodi, comandi e operazioni. Iniziamo a scrivere il comando che ci serve e poi premiamo TAB per un aiuto:
Le opzioni sono tante ma a noi serve di definire soltanto nome del JDBC driver e nome del relativo modulo (che abbiamo definito poc’anzi).
/subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql, driver-module-name=org.postgresql)
La prima parte di installazione del JDBC driver è completata.
CONFIGURAZIONE DI UN DATASOURCE NON-XA
Da questo momento in poi possiamo creare i nostri Datasource, XA e Non-XA, sia utilizzando la CLI che la Management Console.
La differenza tra un Datasource XA e Non-XA sta nel fatto che il primo supporta transazioni distribuite, e quindi la possibilità di accedere a più risorse nella transazione, mentre un Non-XA accede ad una singola risorsa.
BTW: spesso si abusa dei Datasource XA anche in contesti in cui sarebbe più che sufficiente un Datasource Non-XA.
Per la seconda parte, la creazione di un Datasource non-XA, utilizzeremo la Management Console. Facciamo dunque login con le nostre credenziali amministrative. Vi ricordo che la http managment interface è in ascolto si default su 127.0.0.1:9990.
Selezioniamo Configuration -> Subsystems -> Datasources -> Non-XA e clicchiamo sul tasto Add: il seguente wizard ci aiuterò nella procedura guidata di configurazione.
Dopo aver selezionato PostgreSQL Datasource passiamo alla schermata successiva (step 1/3) dove definiamo nome e JNDI name del Datasource:
Nello step 2/3 definiamo invece i dettagli sul driver. Nel campo Specify Driver vengono proposte una serie di configurazioni preallocate (notare il campo Driver Class). Clicchiamo su Detected Driver per utilizzarne uno preinstallato: qui selezioniamo postgresql e clicchiamo su avanti.
Step 3/3: definiamo i Connection Settings. In particolare l’url di connessione al db, di cui abbiamo già parlato, nome utente e password.
La schermata Summary mostra un riepilogo finale. Clicchiamo su Finish per completare la procedura guidata.
Se abbiamo svolto tutto correttamente dovremmo avere un Datasource funzionante. Possiamo testarlo sia da Management Console che da CLI. Da cli ad esemio dovremo lanciare il comando:
/subsystem=datasources/data-source=labDS:test-connection-in-pool
Un output DMR contenente “outcome” => “success” ne sancirà il corretto funzionamento.
La configurazione avanzata del Datasource esce dall’intento di questo blogpost. Ad ogni modo, se proviamo ad eseguire una :read-resource da CLI possiamo vedere già tutta una serie di attributi preconfigurati secondo dei valori di default:
/subsystem=datasources/data-source=labDS:read-resource
Anche qui possiamo optare per la Management Console per le modifiche degli attributi o per la CLI.
Se ad esempio vogliamo modificare, da CLI, il valore delle connessioni minime del database connection pool non dobbiamo fare altro che applicare una operazione :write-attribute.
/subsystem=datasources/data-source=labDS:write-attribute(name=min-pool-size, value=8)
In questo caso abbiamo impostato il min-pool-size a 8. Posso fare lo stesso con il max-pool-size.
/subsystem=datasources/data-source=labDS:write-attribute(name=max-pool-size, value=16)
Con questo chiudiamo il nostro articolo sulla creazione dei Datasource in EAP 7.0 con l’augurio che possa esservi utile. Continuate a seguirci sul blog e seguite gli aggiornamenti dei corsi Red Hat erogati in esclusiva EXTRAORDY sulla suite dei prodotti JBoss.
