## Servicegen - overview

versione: 3.3.0

SERVICEGEN è uno strumento di generazione di codice specifico per la produzione di interi progetti software che realizzano uno o pi� servizi secondo il paradigma SOA. Attualmente sono supportate due tecnologie target:

- stack J2EE arricchito con le librerie di cooperazione applicativa C.S.I
- stack J2EE arricchito con il framework per web services CXF

Lo strumento permette di definire uno o pi� servizi realizzati all'interno di un componente di prodotto, secondo gli standard di sviluppo e le linee guida vigenti in CSIPIEMONTE. Il modello che descrive l'applicazione è:

- basato su un metamodello descritto in dettaglio in [Metamodel reference];
- strutturato in un insieme di modelli come descritto in dettaglio in [Models structure];

Per ciascuna delle due modalità (C.S.I vs CXF) il progetto viene generato per produrre pacchetti funzionanti su una specifica target platform J2EE, a scelta tra:

- Weblogic Server 9.2
- Jboss 4.3 EAP
- Jboss 6.0 EAP
- Jboss 6.2 EAP
- Jboss 6.4 EAP

Per ciascun componente è possibile definire uno o più definizioni di servizio, ciascuna delle quali è caratterizzata da:

- Un codice servizio, così come verrè classificato nel repository dei servizi
- Una versione dell�interfaccia (in formato major.minor)
- La tipologia di servizio, da scegliere tra Applicativo, di Orchestrazione, Infrastrutturale
- Un insieme di tipi user defined (entità, array tipati contenenti entità user defined, ed eccezioni)
- Un insieme di operazioni esposte dall�interfaccia del servizio, che possono utilizzare come parametri o valori di ritorno un tipo base csi o un tipo user defined (entity)
- Eventuali regole di autorizzazione all�utilizzo delle varie operazioni, secondo quanto specificato nel documento "Linee guida per la sicurezza nella cooperazione applicativa" (v.).

Il componente, oltre a definire un certo numero di servizi, li espone (provides) affinchè possano essere fruiti da sistemi utilizzatori. Questa esposizione è effettuata tramite uno o più binding, che possono essere di quattro tipi (tre per la modalità C.S.I e uno per la modalità CXF):

1. Modalità C.S.I
   1. Binding PA EJB: è il binding classico, sempre presente, rappresentato da una Porta Applicativa CSI basata su tecnologia EJB e interazione RMI con il fruitore;
   2. Binding Bridge di PA SOAP: è un binding opzionale che permette la fruizione del servizio da parte di un sistema (non necessariamente java) dotato di porta delegata soap;
   3. Binding front-adapter web-services: è un binding opzionale che permette la fruizione del servizio a tutti quei sistemi che non possono utilizzare una porta delegata ma che sono in grado di instaurare una comunicazione web-services rpc soap/http.
2. Modalità CXF
   1. Binding WS: è il binding classico per i web services soap/http;

A fronte di una applicazione logicamente definita secondo il modello appena esposto, il generatore di applicazione genera progetti di forma differente a seconda che si utilizzi la cartuccia di generazione per C.S.I o per CXF.

### generazione di servizi in modalità C.S.I

- Per ogni componente viene generato:
  - Un progetto SVN standard dotato di build ant e contenente tutti gli artifact che realizzano tutti i servizi definiti ed esposti in quel componente. Il risultato finale del build sarà un EAR contenente:
    - Un ejb-jar per ogni binding paejb
    - Un war per ogni bridge soap
    - Un war per ogni front adapter web-services
    - Il frammento di configurazione log4j da inserire nella configurazione del server, contenente:
      - Le configurazioni per il log applicativo
      - Le configurazioni per lo stopwatch
      - Le configurazioni per coop-trace, se il componente contiene almeno un servizio coop-trace enabled (default)
- Per ogni definizione di servizio all�interno di ciascun componente:
  - L�interfaccia CSI del servizio
  - Le classi java corrispondenti alle entità e alle eccezioni user-defined
  - Le classi che implementano il servizio come Stateless Session EJB
  - Nel caso dei servizi orchestrati gli scheletri dei descrittori XML svcflow dei flussi relativi a ciascuna operazione
  - Il build che costruisce i pacchetti interni relativi ai singoli binding e la distribuzione delle librerie client dell�interfaccia del servizio; nel caso di binding ejb, se il servizio è coop-trace enabled, i file conterranno anche le configurazioni dei pluggable function handler appositi .
  - I file di porta delegata (a scopo di test o da distribuire ai fruitori - ejb sempre, soap solo se presente il relativo binding) � nel caso in cui il servizio sia coop-trace enabled, i file conterranno anche le configurazioni dei pluggable function handler appositi.
  - Un abbozzo di test Junit per ciascun servizio
  - Un build specifico utile per generare gli stub axis relativi ai front-adapter web-services (se presenti) - a scopo di test

### generazione di servizi in modalità CXF

- Per ogni componente viene generato:
  - Un progetto SVN standard dotato di build ant e contenente tutti gli artifact che realizzano tutti i servizi definiti ed esposti in quel componente. Il risultato finale del build sarà un EAR contenente:
    - Un war per ogni servizio esposto
    - Il frammento di configurazione log4j da inserire nella configurazione del server, contenente:
      - Le configurazioni per il log applicativo
      - Le configurazioni per lo stopwatch
- Per ogni definizione di servizio all�interno di ciascun componente:
  - L�interfaccia jax-ws compliant del servizio
  - Le classi java corrispondenti alle entità e alle eccezioni user-defined
  - Le classi che implementano il servizio come bean Spring
  - Nel caso dei servizi orchestrati gli scheletri dei descrittori XML svcflow dei flussi relativi a ciascuna operazione
  - Il build che costruisce i pacchetti interni relativi ai singoli binding e la distribuzione delle librerie client dell�interfaccia del servizio;
  - Un abbozzo di test Junit per ciascun servizio

Lo scenario di utilizzo dello strumento prevede quindi la generazione model driven con round-trip dei servizi: definendo incrementalmente il modello dell�applicazione (secondo il metamodello sepcifico di SERVICEGEN) è possibile generare una applicazione completa che può evolvere nel tempo con round trip monodirezionale modello->codice.

Compito dello sviluppatore è quello di arricchire il codice generato inserendo manualmente nelle apposite regioni protette il codice che implementa il servizio.

Nel caso si utilizzi SERVICEGEN per realizzare servizi di orchestrazione è possibile modellare l'orchestrazione, definendo:

- L'insieme dei servizi orchestrati (ovvero acceduti dall'orchestrazione), definiti come elementi di un ResourceSet
- La sequenza degli step (nodes) che costituiscono l'orchestrazione, che possono essere:
  - Nodo di start: nodo iniziale che marca l'inizio dell'orchestrazione e inserisce in uno o pi� DataSlot i valori di ciascun parametro di input del metodo di orchestrazione
  - Nodo di stop: nodo finale che marca il termine dell'orchestrazione e permette di restituire come output del metodo di orchestrazione il valore contenuto in un particolare DataSlot
  - Nodo di trasformazione: nodo che permette di effettuare trasformazioni di valori contenuti nel contesto di esecuzione (a partire da uno o più DataSlot e memorizzando il risultato in un DataSlot)
  - Nodo di richiamo di un servizio PDPA:
    - per accedere ad un particolare metodo di uno dei servizi dichiarati nel ResourceSet
    - valorizzando i parametri con il valore di uno o pi� DataSlot
    - memorizzando l'eventuale valore di ritorno in un DataSlot
    - eseguendo una sottosequenza di step in caso di eccezione (ExceptionHandler)
  - Nodo di Loop (ForEach) per ciclare all'interno di una collection contenuta in un DataSlot, ed eseguire una sottosequenza di step
  - Nodo di branch condizionale, per eseguire una tra due possibili sottosequenze di step a fronte del risultato di una condizione logica

Nel caso dei servizi di orchestrazione il generatore si preoccupa anche di gestire automaticamente:

- la creazione dei file di configurazione delle PD dei servizi acceduti
- la risoluzione delle dipendenze rispetto alle librerie client dei servizi acceduti

### Cosa cambia a livello di utilizzo nelle due modalità

Le due modalità di realizzazione dei servizi (C.S.I vs CXF) comportano differenze a livello di modellazione, istruzioni di generazione ed implementazione del codice custom. Di seguito le principali differenze.

#### differenze a livello di modellazione

aspetto | CSI | CXF | note
libreria di tipi base | `basetypes.servicegen`: libreria dei tipi base previsti dal framework di cooperazione applicativa CSI | `wsbasetypes.servicegen`: libreria dei tipi base previsti dallo standard web-services | le due modalità operano su typeset differenti: tutto ciò che fa riferimento a tipi deve adeguarsi al typeset adeguato alla modalità (nella definizione di parametri e valori di ritorno)
binding | sono supportati i binding ejbpa, pabr, wsfad | è supportato il solo binding di tipo ws | La modalità CSI non � una modalità standard web services di conseguenza gli insiemi dei binding supportati dalle due modalità sono disgiunti

#### differenze a livello di generazione

aspetto | CSI | CXF | note
cartuccia | `it/csi/mddtools/servicegen/workflow/csi14.mwe` | `it/csi/mddtools/servicegen/cxf/cxf.mwe` |

### Limitazioni

Allo stato attuale sono presenti le seguenti limitazioni:

- Limitazioni generali
  1. Non è possibile definire nello stesso componente due servizi di cui uno sia realizzato in modalità C.S.I ed un altro in modalità CXF
- Limitazioni sui Servizi CXF
  1. Non è supportata la securizzazione dei servizi dal punto di vista dell' autenticazione/autorizzazione (ovvero è supportato solo il livello A0)
  2. Non sono previste le funzioni di monitoraggio, diagnostica, tracing