Note : l'administration des queues ActiveMQ doit se trouver à l'adresse [http://localhost:8161/admin/queues.jsp] (pour observer le cycle de vie et le fonctionnement des queues du SE ASE, au déploiement des SU).

Déploiement du composant dans Petals.

h1. Fonctions / architecture

(Pour les détails, voir la [spécification du SE-ASE|Petals-SE-ASE^ESB_req_spec-2011-06-15.doc]).

Le SE, intercalé entre un client et un service, assure une garantie de livraison des échanges basée sur ActiveMQ (JMS).
ActiveMQ se charge du stockage et de la réémission des échanges, le cas échéant.

Seuls les MEP InOnly et RobustInOnly sont supportés pour le "provides", et le même MEP est utilisé pour le "consumes", sauf configuration spéficique (en cas de "consumes" en InOut, la réponse sera ignorée).

Le client, au lieu d'appeler le service directement, appelle un service intermédiaire défini dans la partie "provides" d'une SU déployée sur le SE ASE. Le SE ASE appelle ensuite le service, spécifié dans la partie "consumes" de la SU.
La médiation entre le "provides" et le "consumes" est assurée par JMS, via une queue, avec un mécanisme configurable de réémissions.

Le "provides" est fourni par un module appelé "posting process" (JBI Listener), qui reçoit les appels du client.
Le "consumes" est fourni par un module appelé "sending process" (listener JMS), qui transmet les appels au service.
Entre ces deux modules, JMS est chargé de la livraison fiable de l'échange.

Chaque SU pilote la création d'un certain nombre de queues JMS :
- <persistence-area> = la queue principale
- <persistence-area>_sending = une queue technique chargée des réémissions (erreurs, timeouts...)
- <persistence-area-fault> = une queue pour stocker les échanges dont le retour est FAULT (erreur fonctionnelle)

Lorsqu'un échange n'a pu être livré malgré les réémissions prévues, il est stocké dans la "dead letter queue" d'ActiveMQ.

Le mécanisme entre le "posting process" (PP) et le "sending process" (SP) est le suivant :
- Le SP écoute 2 queues JMS : <persistence-area> et <persistence-area>_sending (en mode transacted / AUTO_ACKNOWLEDGE).
- Un échange est reçu par le PP
- Il est mis dans la queue JMS <persistence-area>, que le SP écoute.
- Le SP reçoit l'échange et valide la lecture du message JMS ("commit").

Le SP tente alors de transmettre l'échange au service :
- En cas de fault, le SP stocke l'échange dans la queue <persistence-area-fault>.
- En cas d'erreur ou de timeout, le SP stocke l'échange dans la queue <persistence-area>_sending.

Si l'échange a été mis dans la queue <persistence-area>_sending, le SP est à nouveau activé, mais avec un comportement différent :
- Le SP tente de transmettre l'échange au service
- En cas d'erreur, il ne valide pas le message (rollback), ce qui déclenche la politique de réémission par JMS (et de nouvelles activations du SP, en fonction de cette politique).
- En cas de fault, le SP stocke l'échange dans la queue <persistence-area-fault>.

Si une erreur persiste, JMS finira par mettre l'échange dans la DLQ (dead letter queue).

h1. Configuration

Paramètres du composant :

|| Paramètre || Description || Défaut ||
| activemq-connection-user | | ActiveMQ default user (null) |
| activemq-connection-password | | ActiveMQ default password (null) |
| activemq-broker-url | | ActiveMQ default broker URL (failover://tcp://localhost:61616) |
| java-naming-factory-initial | | |
| java-naming-provider-url | | |
| jms-connection-factory-jndiname | | |
| stop-timeout | | 0 |

Paramètres du "provides" dans une SU :

|| Paramètre || Description || Défaut ||
| persistence-area-name | Nom de la queue JMS principale | <provides-service-name> |
| persistence-area-name-fault | Nom de la queue JMS pour les erreurs fonctionnelles (FAULT) | <provides-service-name>_error |
| persistence-area-name-error | Nom de la queue JMS pour les erreurs | <provides-service-name>_error |
| persistence-area-name-timedout | Nom de la queue JMS pour les timeout | <provides-service-name>_error |
| persistence-area-name-expired | | <provides-service-name>_expired |
| mustBeAutomaticallyStarted | Activation au démarrage de la SU | true |

Paramètres du "consumes" dans une SU :

|| Paramètre || Description || Défaut ||
| mustBeAutomaticallyStarted | Activation au démarrage de la SU | true |
| retry-policy-number | Nombre maximal de réémissions | 3 |
| retry-policy-base-interval | Intervalle de base entre deux réémissions (secondes) | 10 |
| retry-policy-factor | Facteur multiplicatif de l'intervalle entre deux réémissions | 3 |
| time-to-live | | time-to-live du CDK, ou 0 si absent |
| is-idempotent | | true |

h1. Logging the ActiveMQ

Le SE ASE est basé sur [ActiveMQ|http://activemq.apache.org/]. Pour avoir accès à ses traces de log, il suffit d'ajouter ceci à la configuration de log de Petals ESB.
{code}
Petals.Container.Components.level=MONIT
# The following line enable debug traces from the SE ASE itself
Petals.Container.Components.petals-se-ase.level=FINE
# The following line enable debug traces from the underlying layer 'ActiveMQ'
org.apache.activemq.level=FINE
{code}

h1. Administation JMX

*MBean composant*

Nom JMX : org.ow2.petals.se.ase:name=<component-identification>

Le SE-ASE instancie un MBean "composant", exposant ses principaux attributs de configuration, au démarrage.

Attributs :

|| Nom || Type ||
| JavaNamingFactoryInitial | String |
| JavaNamingProviderUrl | String |
| JmsConnectionFactoryJndiname | String |
| ActivemqConnectionUser | String |
| ActivemqConnectionPassword | String |
| ActivemqBrokerUrl | String |
| StopTimeout | integer |

*MBean SU*

Nom JMX : org.ow2.petals.se.ase:su=<su-name>

Chaque SU instancie au démarrage son propre MBean, lequel expose, outre ses attributs de configuration, les opérations suivantes :
- start / stop du "sending process" (si le SP est arrêté, les messages éventuels s'accumulent dans la queue JMS, en attendant le démarrage ultérieur du SP).
- start / stop du "posting process" (si le PP est arrêté, le service fourni par la SU rejette tout appel provenant d'un client).

Attributs :

|| Nom || Type ||
| PersistenceAreaName | String |
| PersistenceAreaNameError | String |
| PersistenceAreaNameFault | String |
| PersistenceAreaNameTimedout | String |
| ProvidesAutomaticallyStarted | boolean |
| ConsumesEndpoint | String |
| ConsumesAutomaticallyStarted | boolean |
| ConsumesIdempotent | boolean |
| ConsumesTTL | integer |
| ConsumesRetryPolicyNumber | integer |
| ConsumesRetryPolicyBaseInterval | integer |
| ConsumesRetryPolicyFactor | integer |

Opérations :

startPostingProcess
stopPostingProcess
startSendingProcess
stopSendingProcess


h1. Utilisation de JMS comme transport alternatif

Soit la configuration suivante :
- Une SU avec "posting process" seul démarré
- Une autre SU avec "sending process" seul démarré

Dans la mesure où les mêmes queues seraient utilisées, un appel au "provides" de la première SU déclencherait un appel au "consumes" de la seconde.

Ceci fournit un transport JMS alternatif au transport de Petals.