Canigó - Servei de Correu 2.3.x

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:

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

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

Documents i Fonts de Referència

Glossari

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ó.

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

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ó

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

<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:

<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>

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

Fitxer de configuració: canigo-errorCodes.properties
Ubicació proposada: <PROJECT_ROOT>/src/main/resources/i18n/errorCodes.properties

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:

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

# public void sendInline(String from, String subject, String aMessage, boolean isHtml, Map recipients, ArrayList attachments)

On la llista d'arxius annexes es una llista d'objectes de tipus ("AttachmentInline"). Cada objecte d'aquest tipus es composa de dos camps;

La llista de direccions annexes té forma de taula ("java.util.Map") on els continguts d'aquesta taula són:

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

Enviament de correus amb plantilla

Des de la versió 2.3.13 el servei permet incrustar adjunts inline en el cos dels missatges HTML. Els correus han d'estar en format HTML.

S'ha afegit la nova operació sendInline(String from, String subject, String aMessage, Map recipients, Map attachments) que envia correus amb adjunts mitjançant plantilles de correus HTML.

Per a incrustar una imatge inline s'ha d'afegir un comentari del tipus '' en el codi HTML al lloc on es vulgui que aparegui la imatge, 'inline1' es un identificador del fitxer inline que serà substituït (tantes vegades com aparegui en el correu) per la imatge amb el mateix identificador que s'haurà inclos en la llista d'adjunts. A continuació es mostra un exemple d'enviament de correus amb plantilla, inlines i adjunts:

public void testInLine() {
        String correu = "<html><body><!--inline1--><p>This is a paragraph.</p><!--inline2--><p>This is a paragraph.</p><!--inline2--><p>This is a paragraph.</p></body></html>";
        Map ats = new HashMap();
       
        AttachmentInline inl = new AttachmentInline();
        File fInl = new File("C:/imatge.png");
        inl.setAttachment(fInl);
        inl.setIsInline(new Boolean(true));
        ats.put("inline1", inl);
       
        AttachmentInline inl2 = new AttachmentInline();
        File fInl2 = new File("C:/imatge2.png");
        inl2.setAttachment(fInl2);
        inl2.setIsInline(new Boolean(true));
        ats.put("inline2", inl2);
       
        AttachmentInline enc = new AttachmentInline();
        File fEnc = new File("C:/enclosed.png");
        enc.setAttachment(fEnc);
        enc.setIsInline(new Boolean(false));
        ats.put("enclosed", enc);
       
        Map rec = new HashMap();
        rec.put(MimeMessage.RecipientType.TO, "destinatari@gencat.cat");
       
        mailService.sendInline("test@gencat.cat", "test", correu, rec, ats);
    }

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) \{...\}
\}
...
\}

SERVEI DE CORREU

Introducció

Propósit