e.Toscana Compliance 
Request for Comments: 
Del: 22/11/2006 
Categoria: Infrastrutturale

	Interfacce Porta di Dominio

Abstract
========
L'infrastruttura di cooperazione applicativa (CART)  uno strumento tecnologico
utilizzato per veicolare contenuti applicativi. I contenuti applicativi sono
veicolati nell'infrastruttura attraverso l'utilizzo delle interfacce esposte da
un componente infrastrutturale chiamato Porta di Dominio (PdD). La PdD 
dispiegata su ogni Nodo Applicativo Locale (NAL) e quindi fisicamente
localizzata in ogni Ente cooperante. Dunque per instaurare la collaborazione
l'Ente deve adattare i propri sistemi informativi locali (SIL) in modo da
richiamere localmente le interfacce esposte dalla PdD. Questo RFC illustra le
interfacce che la PdD espone verso i SIL.

Indice
======
1. Introduzione
2. Definizioni
3. Modalit di utilizzo della interfacce esposte dalla PdD
3.1 Modalitd'uso trasparente dei Servizi
3.2 Uso del Servizio di Integration Manager
3.3 La gestione degli errori nell'Interazione con la Porta di Dominio
3.4 Altre informazioni di controllo
3.5 Risposta del Servizio invocato
4. Riferimenti
5. Note
6. Autori

1. Introduzione
===============
I servizi applicativi interni agli enti dovranno essere agganciati alla
piattaforma CART utilizzando i componenti di integrazione. Ci sono due modalit
per utilizzare i componenti di integrazione. Nel seguito vediamo come utilizzare
le due modalit, rinviando alla documentazione della Porta di Dominio CART per
maggiori dettagli.

2. Definizioni 
============== 
CART: Cooperazione Applicativa Regionale Toscana. E una infrastruttura che
permette ai sistemi informativi dei Soggetti della comunit di cooperare.

NAL: Nodo Applicativo Locale, il NAL  una risorsa hardware contenente le
risorse software necessarie a realizzare: la comunicazione con gli altri NAL e
la comunicazione con i SIL

SIL: Sistema Informativo Locale

Porta di Dominio (PdD): nella specifica SPCoop, un dominio  definito come il
confine di responsabilit di un Ente o Soggetto amministrativo e racchiude al
suo interno tutte le applicazioni da esso gestite. Le comunicazioni da e verso
un dominio devono attraversare la sua Porta di Dominio. Le Porte di Dominio si
mettono in collegamento tra loro scambiandosi richieste e risposte in un formato
standard, denominato busta eGov.

Busta e-Gov: estensione dello standard SOAP che definisce il protocollo
applicativo con cui i servizi applicativi sono invocati in modo remoto.

Porta Applicativa: interfaccia sulla Intranet SPCoop tramite la quale il Dominio
eroga un servizio.

Porta Delegata: interfaccia sulla Intranet SPCoop tramite la quale il Dominio
richiede un servizio.

3. Modalit di utilizzo della interfacce esposte dalla PdD
==========================================================
Le interazioni tra servizi applicativi e le porte delegate e applicative delle
Porte di Dominio che li ospitano devono avvenire tramite richieste SOAP su
protocollo https. Ogni richiesta in arrivo dal Servizio Applicativo deve essere
autenticata tramite certificati X.509. 
In generale le interazioni tra i servizi applicativi e la porta di dominio
possono avvenire in due modi:

1. modalit trasparente: prevede che il servizio applicativo utilizzi (in caso
di porta delegata) o esponga (in caso di porta applicativa) le interfacce
applicative native dei servizi, come registrate negli accordi di servizio; in
tal caso la Porta di Dominio agisce come un proxy trasparente con funzionalit
di imbustamento e sbustamento eGov dei messaggi applicativi; utilizzando questa
modalit, gli applicativi potranno continuare ad operare esattamente come se
stessero interagendo direttamente con il servizio applicativo dell'altro Ente;

2. uso del Servizio di Integration Manager: prevede di utilizzare le interfacce
di un apposito web service di Integrazione, messo a disposizione dalla Porta di
Dominio per la spedizione e/o la ricezione di messaggi applicativi da parte dei
servizi applicativi del proprio Dominio di Servizi.

3.1 Modalit d'uso trasparente dei Servizi
===========================================
Questa modalit prevede che il servizio applicativo utilizzi (in caso
di porta delegata) o esponga (in caso di porta applicativa) le
interfacce applicative native dei servizi, cos come registrate negli
accordi di servizio; in tal caso la Porta di Dominio agisce come un
proxy SOAP trasparente con funzionalit di imbustamento e sbustamento
eGov dei messaggi applicativi; utilizzando questa modalit, gli
applicativi potranno continuare ad operare esattamente come se
stessero interagendo direttamente con il servizio applicativo
dell'altro Ente.

L'invocazione della porta delegata in modalit trasparente pu essere
realizzata tramite gli strumenti del linguaggio di programmazione
nativo del servizio applicativo, utilizzando ad esempio stub creati
tramite il proprio ambiente di sviluppo Web Services (ad esempio
wsdl2java in Axis), facendo riferimento direttamente al WSDL del
servizio destinazione.

In questo caso l'unica modifica rispetto all'invocazione
dell'effettivo servizio destinazione sarla URL utilizzata per
l'invocazione http, che sar quella corrispondente alla porta
delegata del servizio.

3.2. Uso del Servizio di Integration Manager
============================================
Prevede di utilizzare le interfacce di un apposito web service di
Integrazione, messo a disposizione dalla Porta di Dominio per la
spedizione e/o la ricezione di messaggi applicativi da parte dei
servizi applicativi del proprio Dominio di Servizi. L'interfaccia WSDL
completa dell'integration manager sara' resa disponibile on-line sul portale
del CART; a mero titolo descrittivo si mostra di seguito l'interfaccia
esposta dal Web Service, espressa in linguaggio java:

	public interface IntegrationManager {
	   public String[] getAllMessagesId()
	   public String[] getAllMessagesIdByService(String servizio, String azione)
	   public SPCoopMessage getMessage(String idEGov)
	   public SPCoopMessage getAndDeleteMessage(String idEGov)
	   public SPCoopMessage getMessageByReference(String riferimentoMsg)
	   public SPCoopMessage getAndDeleteMessageByReference(String riferimentoMsg) 
	   public SPCoopMessage getNextMessage()
	   public SPCoopMessage getNextAndDeleteMessage()
	   public void deleteMessage(String idEGov)
	   public void deleteAllMessages()
	   public SPCoopMessage invocaPortaDelegata(String portaDelegata,SPCoopMessage msg)
	}

L'oggetto SPCoopMessage contiene l'ID del messaggio, il servizio e
l'azione SPCoop e un array di byte che rappresenta il messaggio SOAP
vero e proprio:

        public class SPCoopMessage  implements java.io.Serializable {
	   public java.lang.String getID();
	   public void setID(java.lang.String ID);

	   public java.lang.String getDestinatario();
	   public void setDestinatario(java.lang.String destinatario);

	   public java.lang.String getServizio();
	   public void setServizio(java.lang.String servizio);

	   public java.lang.String getAzione();
	   public void setAzione(java.lang.String azione);

	   public byte[] getMessage();
	   public void setMessage(byte[] message);
        }

3.3 La gestione degli errori nell'Interazione con la Porta di Dominio
=====================================================================
In funzione del fatto che si usi la modalit di invocazione
trasparente o i servizi dell'IntegrationManager, cambia il modo in cui
le condizioni di errore vengono restituite al servizio applicativo.

Nel caso si usino i servizi dell'IntegrationManager le condizioni di
errore saranno restituite all'interno di una eccezione gestita dal
servizio IntegrationManager, il cui formato  rappresentato di seguito
in linguaggio java.

  public class SPCoopException {
     public java.lang.String getCodiceEccezione();
     public void setCodiceEccezione(java.lang.String codiceEccezione);

     public java.lang.String getDescrizioneEccezione();
     public void setDescrizioneEccezione(java.lang.String descrizioneEccezione);

     public java.lang.String getIdentificativoFunzione();
     public void setIdentificativoFunzione(java.lang.String identificativoFunzione);

     public java.lang.String getIdentificativoPorta();
     public void setIdentificativoPorta(java.lang.String identificativoPorta);

     public java.lang.String getOraRegistrazione();
     public void setOraRegistrazione(java.lang.String oraRegistrazione);

     public java.lang.String getTipoEccezione();
     public void setTipoEccezione(java.lang.String tipoEccezione);
  }

Nel caso in cui si utilizzi la modalit trasparente, sar invece
possibile, in caso di eccezione SOAPFault, testare il campo FaultActor
per riconoscere e gestire i casi di errore dovuti all'interazione con
la porta di dominio (valore "it.cart.pdd") da quelli puramente
applicativi. Nel frammento di codice seguente vediamo, a titolo di
esempio, come gestire questa situzione nel caso specifico del
linguaggio java usando Axis 1.4 come web-services engine.

        try {
            HelloWSServiceLocator locator = new HelloWSServiceLocator();
            locator.setHelloWorldEndpointAddress("http://pdd/cart/PD/GetDate");
            HelloWS port = locator.getHelloWorld();
            String msg = port.getDate();
        }
        catch (AxisFault e) {
            if("it.cart.pdd".equals(e.getFaultActor())){

                System.out.println("Ricevuto Messaggio di Errore Applicativo ["+e.getFaultCode()+"]:");
                System.out.println(e.getFaultString());

            }else{

                System.out.println("Ricevuto SOAPFault applicativo");
                System.out.println("Actor: "+e.getFaultActor());
                System.out.println("Code: "+e.getFaultCode());
                System.out.println("String: "+e.getFaultString());

            }
        }
        catch (Exception e) {
            System.out.println("ClientError: "+e.getMessage());
            e.printStackTrace();
        }

Come evidenziato nell'esempio, il particolare codice di eccezione
generato dalla Porta di Dominio potr essere ottenuto tramite il campo
FaultCode del messaggio di Fault SOAP.

In entrambi gli approcci, in caso di errore, la Porta di Dominio
restituir gli stessi codici di errore, elencati nella tabella
seguente.


  FaultCode		 Dettaglio di Errore
  -------------------------------------------------------------------------------
  CART_IT_500	 Porta di Dominio Temporaneamente non Disponibile
  -------------------------------------------------------------------------------
  CART_IT_401	 Porta Delegata Inesistente
  -------------------------------------------------------------------------------
  CART_IT_402	 Autenticazione Fallita
  -------------------------------------------------------------------------------
  CART_IT_403	 Pattern Ricerca Porta Delegata Non Valido
  -------------------------------------------------------------------------------
  CART_IT_404	 Autorizzazione Fallita
  -------------------------------------------------------------------------------
  CART_IT_405	 Servizio SPCoop abbinato alla Porta Delegata Inesistente
  -------------------------------------------------------------------------------
  CART_IT_406	 Nessun Messaggio disponibile per il Servizio Applicativo
  -------------------------------------------------------------------------------
  CART_IT_407	 Messaggio Richiesto Inesistente
  -------------------------------------------------------------------------------

I servizi applicativi sono tenuti a gestire tutti gli errori generati
dalla porta, trattenendo i messaggi che hanno generato errore per una
successiva spedizione. In particolare, in caso di errore CART_IT_500,
il servizio applicativo e' tenuto a sospendere temporaneamente per un
tempo calcolato in maniera random, la spedizione di messaggi, in modo
da favorire il decongestionamento dell'infrastruttura.

3.4 Altre informazioni di controllo
===================================
Ulteriori informazioni di controllo possono essere, in funzione del
profilo di collaborazione e del tipo di porte delegate e applicative
in gioco, scambiate tra la Porta di Dominio e i servizi applicativi,
come il nome del destinatario/mittente, del servizio, dell'azione,
dell'identificatore della busta eGov, etc.).

Nel caso si usino i servizi dell'IntegrationManager della Porta di
Dominio  possibile utilizzare le interfacce appositamente progettate
per supportare i servizi di integrazione SPCoop. 

Nel caso in cui si utilizzi la modalit trasparente, sar invece
necessario utilizzare la URL invocata e/o gli header del trasporto
http per lo scambio delle informazioni aggiuntive, dovendo
l'interfaccia rimanere quella originale del servizio applicativo
invocato. Pertanto, sia al momento dell'invocazione di una porta
delegata da parte di un servizio applicativo, che nel caso di
invocazione del servizio applicativo da parte della Porta Applicativa,
viene settato il seguente header http della richiesta o della
risposta:

  Nome: SPCoop.ID
  Valore: l'id della busta EGov a cui la richiesta si riferiva

3.5 Risposta del Servizio invocato
==================================
Per le interazioni Sincrone, il servizio applicativo richiedente
ottiene la busta SOAP o il SOAP Fault generato dal servizio
applicativo corrispondente.

Per le interazioni Asincrone, al servizio applicativo viene invece
ritornato un messaggio SOAP con body "OK", aderente ad un apposito
xsd, che sara' reso disponibile on-line sul portale del CART.

In caso di errore, viene invece restituito un messaggio di Soap Fault
contenente nel FaultString un messaggio di errore applicativo, in
linea con quanto indicato nella specifica SPCoop (rif. Sistema
pubblico di cooperazione: PORTA DI DOMINIO).

4. Riferimenti
==============
Nessuno

5. Note
=======
Nessuna

6. Autori
=========
Walter Volpi - walter.volpi@regione.toscana.it
