I system contracts
I system contracts sono i contratti che si stipulano tra una risorsa J2EE esterna (nel nostro caso è il Resource Adapter) e i servizi della piattaforma J2EE ospitante (cioè l'Application Server). Tali contratti permettono di specificare le relative interazioni tra i due partecipanti. JCA specifica mediante i contratti di Connetion, Transaction e Security come il sistema Middleware deve collaborare con la risorsa EIS al fine di gestire i meccanismi di sistema.

Connection Management
Il Connection Management è il contratto che determina le politiche per stabilire/chiudere le connessioni con le risorse EIS ottimizzando la gestione degli accessi mediante un Connection Pool gestito dall'Application Server.
Permette anche di definire dei listener per gestire eventi associati alla gestione delle connessioni.

Transaction Management
Consente di gestire l'accesso transazionale verso le risorse EIS, definendo le interazioni tra la risorsa ed il transaction manager.
Le transazioni possono richiedere la presenza di un transaction manager esterno oppure possono essere gestite internamente dal resource manager della risorsa EIS stessa.
Questo contratto non è obbligatorio in quanto la specifica JCA ammette RA non transazionali.

Security
Permette di gestire la Sicurezza per accedere all'EIS. Consente allo sviluppatore del RA di implementare/fornire i meccanismi per la gestione dell'autenticazione e dell'autorizzazione, ed eventualmente consente la personalizzazione della comunicazione sicura tra il server J2EE e la risorsa EIS.

Le classi coinvolte nella realizzazione di ogni contratto JCA si possono dividere in due "categorie": le classi "Managed" e le classi "Physical Connection" [JW2].
Le classi Managed interagiscono direttamente con l'Application Server ospitante, ad esempio permettono la gestione delle connessioni mediante connection pool o di interagire con il Transaction Manager per la gestione delle transazioni.
L'altra categoria comprende le classi che gestiscono direttamente l'interazione diretta con l'EIS.

Figura 1 - Le classi Managed principali

Connection Management
Il Resource Adaptor deve essere in grado di agire come un factory di connessioni
(pattern factory) fornendo un'implementazione dell'interfaccia javax.resource.spi.ManagedConnectionFactory e javax.resource.spi.ManagedConnection, al fine di fornire rispettivamente un costruttore di connessioni ed una classe che gestisca il collegamento fisico della risorsa EIS.

Ogni Resource Adapter deve almeno fornire l'implementazione delle seguenti tre interfacce SPI :

• ManagedConnectionFactory: agisce da factory delle connessioni
• ManagedConnection: rappresenta la connessione fisica con l'EIS
• ManagedConnectionMetaData: fornisce le informazioni dell'EIS associato alla relativa istanza ManagedConnection

Tali interfacce devono essere obbligatoriamente implementate per poter realizzare un Resource Adapter JCA.
Le API Service Provider Interface (SPI) appartenenti al package javax.resource.spi contengono le classi per gestire la connessione con la risorsa EIS fornendo un framework per l'invocazione del servizio. Nel prossimo articolo si entrerà nel dettaglio delle implementazioni di tali classi parlando del MokaConnector.
Nel sequence diagram che segue si cerca di dare un'idea complessiva di come il client JCA è in grado di ottenere una connessione con l'EIS.
Il sequence diagram mette in rilievo anche l'interazione tra le classi "Managed" e le classi CCI. Si ricorda che, mentre le classi Managed sono obbligatorie per costruire un RA, le classi CCI si hanno solo nel caso in cui il RA sia CCI-compliant; quindi le classi Managed restituiscono al client JCA o classi che implementano interfacce CCI [JCA2] e [JCA3] o classi proprietarie.
Il client JCA invoca il metodo getConnection() del Connection Factory (nel caso del MokaConnector è la classe MokaCciConnectionFactory[JCA3]), il quale si limita ad invocare il metodo allocateConnection() dell'oggetto ConnectionManager dell'Application Server [JCA3].
E' l'Application Server che interagisce con la risorse Managed. Infatti come prima operazione l'AS invoca il metodo createManagedConnection() della classe Managed ConnectionFactory.
A questo punto viene o creato un nuovo oggetto di classe ManagedConnection (la connessione con l'EIS), oppure prelevato il primo disponibile dal connection pool.
Mediante l'invocazione del metodo getConnection() della classe ManagedConnection viene restituito al client il reference della connessione richiesta.

Figura 2 - Sequence diagram delle interazioni per ottenere una connessione con il RA

Un Resource Adapter può inoltre fornire la classe che implementa l'interfaccia javax.resource.spi.ConnectionRequestInfo e permette di descrivere i dati specifici della richiesta di connessione all'EIS. Il ConnectionRequestInfo viene passato come parametro al metodo allocateConnection() del ConnectionManager durante la fase di reperimento della connessione conl'EIS.
Il sequence diagram presentato ha mostrato le interazioni tra il client JCA, le classi Managed, le classi CCI e l'AS al fine di ottenere una connessione con l'EIS.
Si è quindi assunto che il RA sia stato già installato sull'AS.
In effetti ci si può chiedere chi e quando abbia creato l'oggetto ManagedConnectionFactory che agisce da classe entry-point del RA. L'operazione di deploy è AS vendor-dependent e nel prossimo articolo si risponderà alla domanda prendendo come esempio l'AS JBoss.
Vediamo di descrivere con maggior dettaglio il ruolo di ognuna della classi che permettono la gestione delle connessioni del RA.

ManagedConnectionFactory
E' la classe che agisce da entry-point per la comunicazione tra l'Application Server ed il Resource Adapter.
Permette la creazione di connessioni con l'EIS o interagendo con il Connection Pool dell'AS, o creandone delle nuove a seconda della politica di gestione delle connessioni attuata.
E' importante capire che, così come un'Applicazione J2EE utilizza il ConnectionFactory[JCA3]

Context ctx = new InitialContext();
Object obj = ctx.lookup("java:comp/env/eis/CCI_MOKA_EIS");
ConnectionFactory cf = (ConnectionFactory)obj;
Connection con = cf.getConnection(connectionSpec);

così l'Application Server utilizza il ManagedConnectionFactory per creare oggetti ManagedConnection, come rappresentato nel precedente sequence diagram.
La classe del MokaConnector che implementata l'interfaccia ManagedConnectionFactory si chiama MokaManagedConnectionFactory:

public class MokaManagedConnectionFactory implements javax.resource.spi.ManagedConnectionFactory,
java.io.Serializable {

ManagedConnection
E' la classe che incapsula la connessione fisica con la risorsa EIS.
La classe MokaManagedConnection mette a disposizione il metodo getConncetion() che permette di ottenere un handle alla connessione fisica della risorsaEIS.

public Object getConnection(Subject subject,
                            ConnectionRequestInfo cxRequestInfo)
                            throws ResourceException

Sempre mediante l'implementazione dell'interfaccia ManagedConnection è possibile accedere alle interfacce javax.resource.spi.LocalTransaction e javax.transaction.xa.XAResource per la gestione delle transazioni del RA.
Inoltre il MokaManagedConnection permette di ottenere le informazioni descrittive dell'istanza ManagedConnection mediante il metodo getMetaData().
La classe del MokaConnector che implementa l'interfaccia javax.resource.spi.ManagedConnection si chiama MokaManagedConnection.

public class MokaManagedConnection implements ManagedConnection {

ManagedConnectionMetaData
Invocando il metodo getMetaData() della classe MokaManagedConnection vengono restituite le informazioni descrittive della connessione incapuslate in un oggetto d'interfaccia ManagedConnectionMetaData.
Tale classe di fatto agisce da Wrapper per gli specifici metadata della risorsa EIS.

public class MokaManagedConnectionMetaData implements javax.resource.spi.ManagedConnectionMetaData {

Le altre interfacce SPI [SPI], come ad esempio la ConnectionEventListener(fornisce un meccanismo di callback ad eventi per permettere di ricevere notifiche dal ManagedConnection), la ConnectionManager (fornisce un hook per permettere agli adapter di inviare richieste di connessione all'application server), la ConnectionrequestInfo, … non sono obbligatorie da implementare dallo sviluppatore del RA.
Il MokaConnector fornisce la classe MokaConnectionRequestInfo che descrive i dati specifici da inoltrare per la richiesta di connessione all'EIS.

public class MokaConnectionRequestInfo implements javax.resource.spi.ConnectionRequestInfo {

Transaction Management
Le interfacce del transaction management forniscono un framework che l'Application Server utilizza per gestire le transazioni della risorsa EIS.
Le transazioni possono essere sia di tipo locale che distribuito(XA).
Un Resource Adapter può non supportare le transazioni o essere in grado di gestire quelle locali, quelle distribuite o entrambe.
Quindi le interfacce che un RA deve implementare dipendono strettamente dal livello di transazione che il connettore stesso è in grado di fornire.
E' la classe MangedConnection che, oltre a fornire l'handle della connessione alla risorsa EIS, permette di ottenere le interfacce per la gestione del Transaction contract.
Il metodo getLocaltransaction() provvede a fornire il supporto delle transazioni in ambito locale restituendo un oggetto che implementa l'interfaccia javax.resource.spi.LocalTransaction.
L'oggetto LocalTransaction permette la gestione della transazionale internamente al ResourceManager senza necessitare di unTransaction Manager fornito dall'AS.

public javax.resource.spi.LocalTransaction.LocalTransaction getLocalTransaction() throws ResourceException{

Nel caso le transazioni locali non fossero supportate dal Resource Adapter, tale metodo deve lanciare l'eccezione ResourceException.

Il metodo getXAResource() permette di ottenere un oggetto che implementa l'interfaccia javax.transaction.xa.XAResource.

public javax.transaction.xa.XAResource getXAResource () throws javax.resource.ResourceException { … }

L'oggetto XAResource definisce il contratto tra il Resource Adapter e il Transaction Manager per la gestione delle transazioni in un contesto transazionale distribuito.
Nel caso le transazioni distribuite non fossero supportate dal Resource Adapter, tale metodo deve lanciare l'eccezione ResourceException.
Nel caso in cui il RA è CCI compliant, è possibile ottenere un'istanza LocalTransaction valida invocando il metodo Connection.getLocalTransaction() per gestire la transaction-demarcation mediante i metodi begin,commit e rollback.

Security Management
Il Security Contract permette di implementare un accesso sicuro alle risorse EIS da parte dell'applicazione client J2EE.
E' possibile integrare questro contratto, all'interno nelle interfacce del Connection Management con JAAS (Java Authentication and Authorization Service).
JAAS sono le API che SUN fornisce per scopi di Autenticazione (autenticare il soggetto che sta eseguendo una certa porzione di codice Java) e di Autorizzazione (autorizzare l'utente assicurarando che abbia i giusti permessi per eseguire determinate azioni).
L'autenticazione in JAAS avviene in un modo "pluggable" cioè le applicazioni (seguendo l'ormai consolidata e affermata "filosofia Java" vedi JDBC,JMS,JNDI…JCA!) rimangono indipendenti dal livello tecnologico d'autenticazione utilizzato.
Mediante la classe javax.security.auth.login.LoginContext il codice applicativo viene disaccoppiato dall'effettiva implementazione JAAS compliant che verrà utilizzata per le operazioni di sicurezza.
Le classi e interface di JAAS si possono suddividere in 3 categorie: quelle comuni(Subject, Principal, Credential), quelle di autenticazione (LoginContext, LoginModule, CallbackHandler, Callback ) ed infine quelle di autorizzazione (Policy, AuthPermission, PrivateCredentialPermission).
Le interfacce JAAS che vengono utilizzate nel RA sono le seguenti:

• javax.security.auth.Subject
  Un oggetto di classe Subject rappresenta un gruppo di informazioni correlate ad una singola identità o a una persona. Include l'identità del soggetto denominato Principal e gli attributi di sicurezza chiamati Credentials. Un oggetto Subject è passato al RA dall'Application Server per le opportune operazioni di autenticazione e autorizzazione.
  
• java.security.Principal
  L'interfaccia Principal permette di rappresentare un'identità nel contesto di sicurezza utilizzato.

Oltre a queste classi JAAS, il security contract JCA include la classe final (non estendibile) javax.resource.spi.security.PasswordCredential per facilitare la comunicazione sicura tra AS e la risorsa EIS.

• javax.resource.spi.security.PasswordCredential
  Tale classe incapsula username e password passate dall'AS al RA. Oltre a definire i metodi get per accedere alle proprietà username e passsword definisce anche i metodi get/setManagedConnectionFactory. Questo permette di associare all'oggetto PasswordCredentials un'istanza ManagedConnectionFactory per la quale la username e password sono state assegnate dall'AS.

JAAS e le classi del Connection Management
Le classi JAAS e la classe PasswordCredential sono utilizzate nelle interfacce JCA che gestiscono il Connection Management.
Le interfacce del Connection Management che partecipano all'implementazione della sicurezza del RA sono ConnectionFactory, ManagedConnectionFactory e ManagedConnection, a seconda di chi ha in carico il processo di login e a che livello è coinvolta la risorsa EIS interfacciata.
Il MokaConnector gestisce la sicurezza in modo semplice incapsulando tutta la logica di sicurezza in una classe (MokaConnectorSecurity) creata all'interno del metodo ManageConnection.getConnection.

Conclusioni
Nel prossimo articolo si parlerà dettagliatamente dell'implementazione delle classi del MokaConnector e si vedrà come effettuare il deploy del RA sull'Application Server JBoss.

Bibliografia e riferimenti
[JCA1] S.Rossini-G.Morello: "JCA: I parte: la teoria", Mokabyte N.66 - Settembre 2002
[JCA2] S.Rossini-G.Morello: "JCA: II parte: CCI la teoria", Mokabyte N.67 - Ottobre 2002
[JCA3] S.Rossini-G.More,lo: "JCA: III parte: CCI la pratica", Mokabyte N.68 - Novembre 2002
[JCA] http://java.sun.com/j2ee/connector/
[SPEC] J2EE Connector Architecture Specification, http://java.sun.com/j2ee/download.html#connectorspec
[CCI1] Beth Stearns: Using the J2EETM Connector Architecture Common Client Interface, http://java.sun.com,Aprile 2001
[BSTW] David Marks: J2EE Connector Architecture Brings Business Systems to the web,
http://developer.java.sun.com/developer/technicalArticles/J2EE/
                                                         connectorclient/resourceadapter.html
[JW2] Dirk Reinshagen: Connect the enterprise with the JCA, Part 2,JavaWorld Febbraio 2002
[JROD] Jennifer Rodoni: The Java 2 Enterprise Edition Connector Architecture's Resource Adapter, http://developer.java.sun.com/developer/technicalArticles/J2EE/
                                                          connectorclient/resourceadapter.html
[JTUT] J2EE Tutorial, http://java.sun.com/j2ee/tutorial/download.html : esample of black box resource adapter for J2EE reference implementation.
[JBOSS] http://www.jboss.org