DataSource in JBoss AS 5

JBoss AS 5 usa di default un database Hypersonic, questa soluzione va bene in fase di sviluppo ma in produzione è preferibile fare uso di DBMS più prestanti e potenti.
La prima cosa da fare quando si fa uso di un altro DBMS consiste nell’installazione dei driver JDBC: il driver JDBC è un file jar che va copiato nella cartella lib sotto la directory corrispondente alla configurazione del server che si sta utilizzando.

Configurazione di DataSource

La configurazione di un DataSource avviene mediante un file xml che ha suffisso *-ds.xml, tale file può contenere al suo interno più definizioni di datasource ma è bene specificarne una per ogni file.

La radice del file xml è costituita dall’elemento datasources il quale può avere come figli i seguenti elementi:

• mbean: viene usato per configurare servizi usati dal datasource.
• no-tx-datasource: viene usato per definire la configurazione di un servizio NoTConnectionManager ovvero un connection manager JCA che non supporta le transazioni e quindi non viene usato in JTA.
• local-tx-datasource: viene usato per definire la configurazione di un servizio LocalTxConnectionManager che gestisce le transazioni attraverso il transaction manager su una risorsa locale (e non su più risorse distribuite).
  Per assicurare che tutto il lavoro di una transazione locale venga gestito dalla stessa ManagedConnection, quando viene richiesta una Connection o inizia una transazione con un connection handle in uso, si controlla se esiste già una ManagedConnection da usare altrimenti viene usata una ManagedConnection libera.
• xa-datasource: viene usato per specificare la configurazione di un servizio XATxConnectionManager usato per gestire transazioni multiple su risorse distribuite.
• ha-local-tx-datasource: è identico a local-tx-datasource ma supporta il failover del database, ciò significa che quando un utente chiama il metodo getConnection del DataSource e la connessione non può essere effettuata, il connection factory tenterà la connessione su un altro url, restituendo questa in caso di successo.
• ha-xa-datasource: analogamente a ha-local-tx-datasource, è identica a xa-datasource ma supporta il failover del database.

Alcuni degli elementi più importanti comuni a tutti i datasource sono:

• jndi-name: il nome JNDI al quale il DataSource verrà collegato, tale nome è relativo al context java:/ finchè use-java-context non viene settato a false.
• use-java-context: se posto a false il datasource verrà collegato al JNDI globale altrimenti al context java:/
• user-name: questo elemento specifica l’username utilizzato nella creazione di una nuova connessione.
• password: questo elemento specifica la password usata quando viene creata uan nuova connessione.
• application-managed-security: questo elemento se presente specifica che devono essere usate username e password passate al metodo getConnection o createConnection dall’applicazione.
• security-domain: viene usato per identificare il login module configurato in conf/login-module.xml
• security-domain-and-application: usato per idenificare il login module configurato in conf/login-module.xml e altre informazioni fornite dall’applicazione.
• min-pool-size: specifica il numero minimo di connessioni che un pool dovrebbe mantenere (le istanze del pool non vengono create finchè non viene fatta una richiesta iniziale). Il valore di default è 0.
• max-pool-size: specifica il numero massimo di connessioni in un pool (in un pool non verranno create più connessioni di quelle indicate da questo elemento). Il valore di default è 20.
• blocking-timeout-millis: specifica il tempo massimo di attesa di una connessione prima di produrre un’eccezione (default 5000).
• idle-timeout-minutes: questo elemento specifica il tempo massimo in minuti nel corso del quale una connessione resta sospesa prima di essere chiusa.
• new-connection-sql: specifica l’istruzione SQL che andrebbe eseguita quando una nuova connessione viene creata.
• check-valid-connection-sql: specifica l’istruzione sql che andrebbe eseguita su una connessione prima che questa venga restituita dal pool per verificare la sua validità
• exception-sorter-class-name: specifica una classe che implementa l’interfaccia org.jboss.resource.adapter.jdbc.ExceptionSorter che esamina le eccezioni del database per determinare quando queste indicano un errore della connessione.
  Le implementazioni attuali includono:
  • org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
  • org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter
  • org.jboss.resource.adapter.jdbc.vendor.SybaseExceptionSorter
  • org.jboss.resource.adapter.jdbc.vendor.InformixExceptionSorte
• track-statemens: specifica un boolean che indica se controllare eventuali statement non chiusi quando una connessione viene restituita dal pool (se posto a true viene generato un messaggio di warning per ogni statement non chiuso).
• prepared-statement-cache-size: specifica il numero di statement preparati in una cache con politica LRU (Last Recently Used).
• type-mapping: dichiara il tipo di mapping di default per il datasource.

Elementi comuni a no-tx-datasource e local-tx-datasource sono:

• connection-url: specifica l’URL di connessione al database (ad esempio jdbc:hsqldb:hsql://localhost:1701)
• driver-class: specifica la classe del driver JDBC (ad esempio org.hsqldb.jdbcDriver)
• connection-property: consente di passare un numero arbitrario di proprietà al metodo java.sql.Driver.connect(url, props)

Elementi comuni a local-tx-datasource e xa-datasource sono:

• transaction-isolation: specifica il livello di isolamento da usare per le transazioni:
  • TRANSACTION_READ_UNCOMMITTED
  • TRANSACTION_READ_COMMITTED
  • TRANSACTION_REPEATABLE_READ
  • TRANSACTION_SERIALIZABLE
  • TRANSACTION_NONE
• no-tx-separate-pools: la presenza di questo elemento indica che sono richiesti due connection pools per isolare le connessioni usate con JTA da quelle senza JTA.

Gli elementi che appartengono esclusicamente a xa-datasource sono:

• xa-datasource-class: specifica la classe che implementa javax.sql.XADataSource
• isSameRM-override-value: viene posto a false per risorvere provlemi con Oracle.
• xa-datasource-property: consente di specificare delle proprietà per l’implementazione XADataSource.
  Ogni proprietà è identificata dal nome dell’attributo e da un valore.

Le seguenti opzioni sono comuni a ha-xa-datasource e ha-local-tx-datasource:

• url-delimiter: specifica il carattere usato per separare URL JDBC multipli.
• url-property: nel caso di datasource XA specifica il nome della xa-datasource-property che contiene la lista degli URL JDBC da usare.

Esempio di file di configurazione

Nella cartella docs/examples/jca sono presenti diversi file di configurazione di DataSource per i database più comuni.
Se si vuole definire un DataSource è possibile compiare il file *-ds.xml corrispondente al database al quale si vuole accedere e cambiarne le opzioni di configurazione ponendolo infine nella directory di deploy.

Ecco cme si presenta ad esempio il file di configurazione mysql-ds.xml

  
    MySqlDS
    jdbc:mysql://mysql-hostname:3306/jbossdb
    com.mysql.jdbc.Driver
    x
    y
    org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter

    
    
    
    

    
       mySQL