PEtALS 2.0 & pack (2007/09/28)| Chapter 2. Service Configuration | ||
|---|---|---|
 | PEtALS-BC-MAIL Component User's Guide |  |
Table of Contents
Petals Mail binding component allows clients to send mails to external services of Petals (internet addresses). To send mails, MailBC can register new jbi endpoints and link them to specific email adresses (Internet Addresses). When MailBC receives a message exchange from Petals platform, it resolves the link to find the targeted email address, binds the message exchange to a mail message and send it to the recipient.
Step 1 : A Consumer jbi component sends a Message Exchange to the Mail Binding Component.
Step 2 : Mail Binding Component processes the Message Exchange : transforms it into a mail message and retrieve targeted External Provider Service (email address) linked to the endpoint set in the Message Exchange.
Step 3 : Mail Binding Component sends this new mail to the targeted External Provider Service (Business Service, simple email account...).
Petals Mail binding component can be configured by deploying a
new service unit to it. The jbi descriptor (
jbi.xml file) of this service unit must contain a
provides node describing the link between an internal jbi endpoint and
an external email address. Here is an exemple of jbi descriptor
activating a new "provided service" :
<jbi version="1.0"
xmlns="http://java.sun.com/xml/ns/jbi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:petals="http://petals.objectweb.org/"
xmlns:extensions="http://petals.objectweb.org/extensions/">
<services binding-component="true">
<provides
interface-name="petals:MailInterface"
service-name="petals:MailService"
endpoint-name="MailEndpoint">
<extensions:extensions>
<scheme>smtp</scheme>
<hostname>Your email host name</hostname>
<username>Your user name</username>
<from>The email address from which the mail is sent</from>
<to>The destination email address</to>
</extensions:extensions>
</provides>
</services>
</jbi>Mail communication attributes :
Table 2.1. service-unit attributes to provide services
| Attribute | Description | Default Value | Required |
|---|---|---|---|
| provides | Name of the JBI service that will be activated to expose the Mail Destination into the JBI environment. interface (qname), service (qname) and endpoint (string) name are required. | Yes | |
| scheme | the connection protocol (smtp) | Yes | |
| username | the username used for authentication | system username | No |
| password | the password used for authentication. Can be null or empty | No | |
| hostname | the host address used for connection | Yes | |
| port | the port used for connection | 25 (default smtp port) | No |
| to |
email address of the recipient NEW FONCTIONNALITY : You can specify the recipient address dynamicaly by setting a "destinationAddress" property in the incoming message exchange. WARNING : the recipient address must be specified at least once in the message exchange or in the SU descriptor | No | |
| from | email address of the sender. This email address will be used as reply (from) address | No |
Table 2.2. Configuration avancée des Services Units (champs provides)
| Parametre | Description | Valeur par defaut | Obligatoire |
|---|---|---|---|
| wsdl | Adresse d'un fichier wsdl décrivant les services et opérations proposées par un endpoint activé par la service unit. Cette extension n'est utilisable qu'avec les champs provides. L'adresse peut être une url de type "http" ou "file" ou un chemin relatif par rapport à la racine de l'archive de la SU. Ex : "file:///user/ofabre/test.wsdl" ou "/WSDL/test.wsdl". Si aucun wsdl n'est spécifié, une description simplifiée est crée automatiquement par le CF | Non |
Table 2.3. Configuration des intercepteurs au niveau de la service unit
| Parametre | Description | Valeur par defaut | Obligatoire |
|---|---|---|---|
| name | Le nom de l'intercepteur a utiliser. C'est le nom qui est definit au niveau du composant. | Oui |
The Service Unit has to contain the following elements, packaged in an archive:
The META-INF/jbi.xml descriptor file, has described above,
An optional wsdl file describing the related service
service-unit.zip + META-INF - jbi.xml (as defined above) - service.wsdl (optional)
Once a provides node is configured, you can start to send email via the mail binding component. You just have to send message exchange to endpoints activated by service unit deployments (containing jbi.xml with provides node).
![[]](./resources/images/caution.png) | Caution |
|---|---|
The subject of the sent mail is the name of the mail binding component. It can't be customized. |
| Caution |
|---|---|
Only InOnly message exchange pattern is allowed. |
Petals Mail binding component (MailBC) allows to receive mails from external consumer and to bind them to message exchanges intinded to internal jbi components. To receive new mails, MailBC can be linked to specific mail stores. It will check these stores periodicaly to retrieve new mails. If it finds a new mail in a store, it will process it (map this mail to a message exchange) and send it to the targeted jbi endpoint. Then the mail is removed from the store. So, all mails (read or unread) in a store are considered as new mail.
Step 1 : An External Consumer Entity (Business Service or simple mail client) sends an email to the registered Mail Store (a classical email account).
Step 2 : Mail Binding Component periodicaly checks for new mails and imports them.
Step 3 and 4 : Mail Binding Component processes this new mails : transforms them into Message Exchanges, sends them to targeted jbi components (step 4) and finally delete them from the mail Store.
Petals Mail binding component can be configured by deploying a new service unit to it. The jbi descriptor (jbi.xml file) of this service unit must contains a consumes node describing the link between an external mail store and an internal jbi endpoint. Here is an exemple of jbi descriptor activating a new "consumed service" :
<jbi version="1.0"
xmlns="http://java.sun.com/xml/ns/jbi"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:petals="http://petals.objectweb.org/"
xmlns:extensions="http://petals.objectweb.org/extensions/">
<services binding-component="true">
<consumes
interface-name="HelloworldInterface">
<extensions:extensions>
<scheme>Your email protocol (imap or pop3)</scheme>
<hostname>Your email hostname</hostname>
<username>Your user name</username>
<password>Your user password</password>
</extensions:extensions>
</consumes>
</services>
</jbi>Mail communication attributes :
Table 2.4. service-unit attributes to consume services
| Attribute | Description | Default Value | Required |
|---|---|---|---|
| consumes | Name of the JBI service that will be called into the JBI environment. When a mail message is received. Only the interface (qname) name can be provided (the container will choose a ServiceEndpoint for this interface), or you can only set service (qname) and endpoint (string) names, without the interface name. | Yes | |
| scheme | the connection protocol (imap or pop3) | Yes | |
| username | the username used for authentication | system username | No |
| password | the password used for authentication. Can be null or empty | No | |
| hostname | the host address used for connection | Yes | |
| port | the port used for connection |
imap : 143 pop3 : 110 | No |
| folder | the folder to check for new mails | INBOX | No |
| period | the checking period time | 60 000 ms | No |
Table 2.5. Configuration avancée des Services Units (champs consumes)
| Parametre | Description | Valeur par defaut | Obligatoire |
|---|---|---|---|
| pattern | Message exchange pattern abréviation. Ce paramètre peut être utilisé en conjonction avec une méthode utilitaire des Listeners : createExchange(MEPConstants mep). Cette méthode renvoie alors un Exchange correspondant au type de pattern spécifié. Les valeurs admises sont : in-only, robust-in-only, in-opt-out et in-out. | Non | |
| operation | Opération à appeler sur un service. Ce paramètre peut être utilisé en conjonction avec les méthodes sendXXX des Listeners. Si l'opération n'est pas spécifiée dans l' Exchange à envoyer, c'est la valeur de ce paramètre qui est utilisée. | Non | |
| timeout | Timeout en millisecondes lors d'un envoie synchrone. Ce paramètre peut être utilisé en conjonction avec la méthode sendSync(Exchange exchange) des Listeners. Un envoi synchrone est alors effectué avec un timeout correspondant à cette valeur. Entier supérieur ou égal à 0. 0 pour aucun timeout. | 0 | Non |
| org.objectweb.petals.routing.strategy | Cette propriété définie la stratégie de routage. Deux types de stratégies peuvent etre définies: highest ou random. Les autres parametres représentent respectivement la ponderation locale, la ponderation des endpoints actifs et la ponderation des endpoints inactifs. La strategy "random" choisit un endpoint en fonction des pondérations définies. L'endpoint qui a la plus forte pondération sera plus facilement selectionné par rapport aux autres. La strategy "highest" choisit le premier endpoint dans la liste qui a la plus forte ponderation. | Non | |
| org.objectweb.petals.transport.compress | La charge utile d'un MessageExchange est un texte XML. Il peut être intéressant de la compresser avant que les messages ne soient échangés entre deux noeuds Petals. Les valeurs admises sont true ou false. Positionner la valeur à true permet de compresser le contenu du message. | Non | |
| org.objectweb.petals.messaging.noack | Tous les échanges JBI finissent par un message contenant un status "DONE" ou "ERROR". Le consommateur doit accepter ces messages, sinon ils sont accumulés dans le NMR. De plus, ces messages génèrent du traffic souvent inutile. Les valeurs admises sont true ou false. Positionner la valeur à true permet de ne pas envoyer les messages de type "DONE" ou "ERROR". | Non | |
| org.objectweb.petals.transporter.qos | Cette propriété définie la règle de qualité de service supportés par les transporters PEtALS. Les valeurs possibles sont: reliability ou fast. Si ce n'est pas spécifié, la règle "reliability" est selectionnée par défaut. | Non |
Table 2.6. Configuration des intercepteurs au niveau de la service unit
| Parametre | Description | Valeur par defaut | Obligatoire |
|---|---|---|---|
| name | Le nom de l'intercepteur a utiliser. C'est le nom qui est definit au niveau du composant. | Oui |
The Service Unit has to contain the following elements, packaged in an archive:
The META-INF/jbi.xml descriptor file, has described above
service-unit.zip + META-INF - jbi.xml (as defined above)
Once an email store is configured, you can send email to it. You
can specify an operation and a Message Exchange Pattern (MEP) to use
with the targeted service. You just have to specify them in the email
subject as follow :
operation=operation-name&mep=mep-name
Table 2.7. Email subject attributes
| Attribute | Description | Default Value | Required | |||
|---|---|---|---|---|---|---|
| operation-name | the targeted operation name | No | ||||
| scheme | the message exchange pattern to use. The possible
values are: in-only, robust-in-only, in-out,
in-optional-out.
| No |
| |  | |
| Chapter 1. Component Configuration |  | Chapter 3. Samples |