Canigó - Servei de Correu

SERVEI DE CORREU

Introducció

Propósit

Context i Escenaris d'Ús

Versions i Dependències

A qui va dirigit

Documents i Fonts de Referència

Descripció Detallada

Arquitectura i Components

Instal- lació i Configuració

Instal- lació

Configuració

Utilització del Servei

Enviament de Correus

Exemples

Exemple de Prova Unitària

Introducció

Propósit

Aquest servei té com a objectiu permetre l'enviament de correus electrònics a una o diverses adreces especificades a qualsevol dels següents recipients:

Destinataris principals
Destinataris secundaris
Destinataris ocults

Permet diferents modes d'enviament, tant en text pla, com en mode HTML, i en tots 2 casos oferint la possibilitat d'adjuntar un o més fitxers.

Context i Escenaris d'Ús

El Servei de Correu es troba dins dels serveis de Propósit General de canigo.

Versions i Dependències

Les dependències descrites a la següent url son requerides per tal de compilar i fer funcionar el projecte:
Dependències Servei de Correu

A qui va dirigit

Aquest document va dirigit als següents perfils:

Programador. Per conèixer l'ús del servei
Arquitecte. Per conèixer quins són els components i la configuració del servei
Administrador. Per conèixer com configurar el servei en cadascun dels entorns en cas de necessitat

Documents i Fonts de Referència

[1]	Spring Mail	http://www.springframework.org/docs/reference/mail.html

Descripció Detallada

Arquitectura i Components

canigo ofereix la possibilitat d'utilitzar diferents implementacions del Servei de Correu. Dins la filosofia general d'oferir interfícies, els clients no es veurien afectats per un canvi d'implementació.

Els components podem classificar-los en:

Interfícies i Components Genérics. Interfícies del servei i components d'ús general amb independència de la implementació escollida.
Implementació de les interfícies basada en Spring i JavaMail

Es pot trobar tota la documentació JavaDoc y el codi font referent aquests components a les següents urls:

JavaDoc: http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_0/canigo-services-mailing/apidocs/index.html
Codi Font: http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_0/canigo-services-mailing/xref/index.html

Instal- lació i Configuració

Instal- lació

La instal- lació del servei requereix de la utilització de la llibreria 'canigo-services-mailing' i les dependències indicades a l'apartat 'Introducció-Versions i Dependències'.

Configuració

La configuració del Servei de Correu implica els següents pasos:

Definir el delegador d'enviaments
Definir el servei
Definir les propietats del servei
Definir els literals multiidioma de les excepcions

Definició del Delegador d'Enviaments

Fitxer de configuració: canigo-services-mailing.xml

Ubicació proposada: <PROJECT_ROOT>/src/main/resources/spring

Es permet l'ús de la classe 'org.springframework.mail.javamail.JavaMailSenderImpl'. Aquesta defineix les següents propietats:

Propietats:

Propietat	Requerit	Descripció
host	Sí	Nom del servidor de correu sortint (smtp)
port	No	Port del servidor de correu sortint (smtp)
username	No	Usuari de connexió al servidor de correu sorting (smtp)
password	No	Password de l'usuari de connexió

Exemple:

<bean id="mailSender"  class="net.gencat.ctti.canigo.services.mail.impl.SpringJavaMailSenderImpl">

<property  name="host" value="$\{mailSender.host\}"/>

<property name="port"  value="$\{mailSender.port\}"/>

<property name="username"  value="$\{mailSender.username\}"/>

<property name="password"  value="$\{mailSender.password\}"/>

</bean>

Definició del Servei

Fitxer de configuració: canigo-services-mailing.xml

Ubicació proposada: <PROJECT_ROOT>/src/main/resources/spring

En l'actualitat s'ofereix la implementació 'net.gencat.ctti.canigo.services.mail.impl.SpringMailServiceImpl', en la que definirem les següents propietats:

Propietat	Requerit	Descripció
mailSender	Sí	Referència a l'enviador
logService	No	Referència al Servei de Traces
maxAttachmentSize	No	Tamany màxim permés dels fitxers adjunts

Exemple:

<bean id="mailService"  class="net.gencat.ctti.canigo.services.mail.impl.SpringMailServiceImpl">

<property  name="maxAttachmentSize"  value="$\{mailService.maxAttachmentSize\}"/>

<property  name="mailSender"><ref  bean="mailSender"/></property>

<property  name="logService"><ref  bean="loggingService"/></property>

</bean>

Definició de les Propietats del Servei

Fitxer de configuració: mail.properties

Ubicació proposada: <PROJECT_ROOT>/src/main/resources/mail

En aquest fitxer definirem les propietats del servei. Aquestes propietats corresponen amb les que hem definit a les configuracions de l'enviador i del servei.

Com a recordatori, tal i com s'ha vist al 'Servei de Configuració' podem fer ús de la classe 'HostPropertyPlaceHolderConfigurer' per definir tots els nostres fitxers de propietats.

En el cas del Servei de Correu podem seguir la mateix filosofia, tal i com es mostra en el següent exemple:

<bean id="configurationService" class="net.gencat.ctti.canigo.services.configuration.
springframework.beans.factory.config.HostPropertyPlaceholderConfigurer">
<property name="basePropertyFiles">
<list>
<value>classpath:jdbc/jdbc.properties</value>
<value>classpath:mail/mail.propertiesc</value>
<value>classpath:file/fileUploadService.properties</value>
<value>classpath:file/fileService.properties</value>
</list>
</property>
</bean>

>> Referència al fitxer de propietats 'mail.properties', que estarà ubicat al directori '/mail' dins el classpath

En l'exemple el configurador fa ús d'un localitzador de fitxers depenent del host (HostPropertyResourceConfigurer). Això vol dir que si en aquest configurador incloem una referència a un fitxer de propietats anomenat " mail.properties", realment es buscarà un fitxer anomenat "mail.properties.nom_del_host". No obstant, aquesta no és l'única possibilitat, ja que es pot fer servir un altre configurador que no depengui del host (com per exemple PropertyOverrideConfigurer). Per a més informació sobre els configuradors veure el document del Servei de Configuració.

Exemple de fitxer de propietats:

mailSender.host=smtp.es.int.atosorigin.com

mailSender.port=25

mailSender.username=user name

mailSender.password=

mailService.maxAttachmentSize=1024

Definició dels Missatges d'Error del Servei

Fitxer de configuració: canigo-errorCodes.properties

Ubicació proposada: <PROJECT_ROOT>/src/main/resources/i18n/errorCodes.properties

Configurar els següents codis d'error:

canigo.services.mail.attachment_size_exceeded=Attachment size exceeded: \{0\} bytes (max: \{1\})

canigo.services.mail.error_preparing_addresses=Error preparing  addresses (to,bcc,cc)

canigo.services.mail.error_sending_mail=Error sending  mail

Utilització del Servei

Enviament de Correus

Per enviar correus, les classes client definiran un atribut 'mailService' de tipus 'MailService'. Mitjançant el Servei de Configuració s'especificarà quina és la implementació escollida (transparent al client).

Es permeten diferents combinacions d'enviament de correus (per a més referència consultar el javadoc de la interfície 'MailService). A mode de resum, podem enumerar:

# public void send(String from, String subject, String aMessage, boolean  isHtml, String to)

Envia un missatge ("aMessage") des d'una direcció a una altra ("from","to") amb un tópic ("subject") en format de text pla o HTML ("isHtml").

# public void send(String from,  String subject, String aMessage, boolean isHtml, String to,
File  attachment)

Envia un missatge ("aMessage") des d'una direcció a una altra ("from","to") amb un tópic ("subject") en format text pla o HTML ("isHtml") amb un fitxer annex ("attachment")

# public void send(String from, String subject, String aMessage, boolean  isHtml, String to,
Map recipients, List attachment)

Envia un missatge ("aMessage") des d'una direcció a unes altres ("from","recipients") amb un tópic ("subject") en format text pla o HTML ("isHtml") amb una llista (o sense llista) de fitxers annexes ("attachments"). La llista de direccions annexes té forma de taula ("java.util.Map") on els continguts d'aquesta taula són:

Clau: pot ser un javax.mail.Message.RecipientType.TO, un javax.mail.Message.RecipientType.BCC ó javax.mail.Message.RecipientType.CC
Valor: és un literal ("String") o una llista de literals ("String[]")

La llista d'anexes és una llista de fitxers ("java.io.File"). Si és nul- la no s'enviarà cap fitxer anexe.

Exemples

Exemple de Prova Unitària

Un exemple d'utilització del servei de correu són els tests unitaris, a on s'obté el bean del servei a partir del fitxer de definició (applicationContext.xml) i s'envia un correu electrònic a les adreces de test especificades.

package net.gencat.ctti.canigo.services.mail.test;

...

public class MailServiceTest extends TestCase \{
...
public void testMailingWithoutAttachment()\{
/**
* Obtenim les definicions dels beans utilitzats
*/
BeanFactory beanFactory = new ClassPathXmlApplicationContext("applicationContext.xml");
/**
* Obtenim el servei de correu
*/
MailService mailService = (MailService) beanFactory.getBean("mailService");
/**
* Obtenim les adreces de test
*/
TestClient clientTest = (TestClient) beanFactory.getBean("clientTest");
/**
* Obtenim el servei de logs per deixar traces
*/
LoggingService logService = (LoggingService) beanFactory.getBean("logService");

try \{
logService.getLog(this.getClass()).debug("From test="clientTest.getFromTest()",To test="+clientTest.
getToTest());
/**
* Enviem el correu de forma fàcil i senzilla
*/
mailService.send(clientTest.getFromTest(),"MailServiceTest "+new Date(),"MailServiceTest without
attachment",false,clientTest.getToTest());
\}
catch (Exception e) \{...\}
\}
...
\}