ALTAS MANUAL DE USUARIO ENVÍO DE CORREOS ELECTRÓNICOS

Transcripción

1 ALTAS MANUAL DE USUARIO ENVÍO DE CORREOS ELECTRÓNICOS Versión 1.0 Área de Aplicaciones Especiales y Arquitectura de Software

2 Hoja de Control Título Documento de Referencia Responsable Manual de Usuario Envío de Correos Electrónicos NORMATIVA ATLAS Área de Aplicaciones Especiales y Arquitectura de Software Versión 1.0 Fecha Versión 28/12/2013 Registro de Cambios Versión Causa del Cambio Responsable del Cambio Fecha del Cambio Área de Integración y Arquitectura de 1.0 Versión inicial del documento Aplicaciones 28/12/ de 19

3 Índice 1. INTRODUCCIÓN AUDIENCIA OBJETIVO CONOCIMIENTOS PREVIOS DESCRIPCIÓN INSTALACIÓN Y CONFIGURACIÓN INSTALACIÓN CONFIGURACIÓN Paso 1: Parámetros de configuración del environment.properties Paso 2: Definir el bean Spring de correo en applicationcontext-services.xml Paso 3: Definir plantilla/s de correo en applicationcontext-services.xml USO CREAR SERVICIO DE CORREO Crear interfaz del servicio de correo Crear implementación del servicio de envío de s Definir servicio de correo en applicationcontext-services.xml CREAR FACHADA Crear interfaz de la fachada Crear implementación de la fachada Definir fachada en applicationcontext-services.xml CREAR PRESENTACIÓN JSF Crear backing bean Definir backing bean en faces-managed-beans.xml Crear página JSF ENLACES RELACIONADOS ANEXOS ENVIRONMENT.PROPERTIES APPLICATIONCONTEXT-SERVICES.XML de 19

4 Contenido 1. INTRODUCCIÓN En este documento se explica cómo enviar correos electrónicos desde una aplicación Atlas desplegada en ICM. Así mismo, se proporciona un ejemplo de envío de correo con texto simple y otro con texto HTML a través de una aplicación web Audiencia objetivo El lector objetivo de este documento es toda aquella persona que esté desarrollando una aplicación basada en el framework Atlas y necesite enviar correos electrónicos desde ICM Conocimientos Previos Para un completo entendimiento del documento, el lector deberá tener conocimientos previos sobre las siguientes tecnologías: - Lenguaje Java - Spring Framework Para saber más sobre dichas tecnologías, consultar los accesos referenciados en el apartado 5 de este documento, Enlaces Relacionados. 4 de 19

5 2. DESCRIPCIÓN Para el envío de correos electrónicos se utiliza el framework Spring. Dicho framework proporciona una biblioteca de utilidad para el envío de correo electrónicos que abstrae al usuario de los detalles del sistema de correo subyacente y, además, se hace responsable de manejar en nombre del cliente los recursos de más bajo nivel. El paquete raíz de la librería de correo electrónico de Spring es org.springframework.mail cuya interfaz central para los envíos es MailSender. Para nuestros proyectos utilizaremos una ampliación de dicha interfaz, JavaMailSender, la cual, junto a la clase de utilidades MimeMessageHelper, nos permitirá crear de una manera rápida y sencilla mensajes MIME más sofisticados: codificación de caracteres especiales (por ejemplo HTML), ficheros adjuntos, plantillas velocity, nombres para las direcciones, etc. También usaremos la clase Simpl Message para crear plantillas de las distintas tipologías de correo electrónico que envíe la aplicación. De esta forma no será necesario escribir en el código aspectos como el destinatario, el asunto, etc. para los diferentes tipos de correo. Es importante indicar que todas las librerías necesarias para el envío de correos (tanto las de Spring como sus dependencias) ya se encuentran incluidas en cualquier aplicación creada a través de un arquetipo Atlas. 5 de 19

6 3. INSTALACIÓN Y CONFIGURACIÓN 3.1. INSTALACIÓN No hay que hacer ninguna instalación. La aplicación que se cree a través de un arquetipo Atlas ya tendrá incluidas las librerías necesarias para el envío de correos CONFIGURACIÓN Éste es el punto más importante, aquí definimos y configuramos los beans que usaremos tanto para el envío de correos (JavaMailSender) como de plantillas para los correos (Simpl Message). Para que los valores de los parámetros de configuración sean invisibles al entorno de la aplicación, estos son obtenidos del fichero environment.properties Paso 1: Parámetros de configuración del environment.properties Para establecer la configuración para envío de correos simplemente tenemos que descomentar las siguientes propiedades, ya existentes, del fichero environment.properties: .smtp.host, .smtp.user y .smtp.pass. Opcionalmente podemos definir propiedades para que sean utilizadas en nuestras plantillas de correo. Algunas de las propiedades son: from, to, subject, text, etc. environment.properties # correo electronico .smtp.host=mail.madrid.org .smtp.user=pendiente .smtp.pass=pendiente # plantilla .from=icm_dga_soporte_arquitectura@madrid.org .to=icm_dga_soporte_arquitectura@madrid.org .subject=ejemplo de integración de correo electrónico .cc=icm_dga_soporte_arquitectura@madrid.org .text=texto de prueba de envío de correo NOTA Para más información sobre el fichero de configuración environment.properties consultar el manual de arquetipos Paso 2: Definir el bean Spring de correo en applicationcontext-services.xml Definimos y configuramos el bean de envío de correos de Spring. Usamos la clase JavaMailSenderImpl y establecemos valor a los parámetros host, username y password procedentes del fichero environment.properties. applicationcontext-services.xml 6 de 19

7  <bean id="mailsender" class="org.springframework.mail.javamail.javamailsenderimpl"> <property name="host"><value>${ .smtp.host</value></property> <property name="username"><value>${ .smtp.user</value></property> <property name="password"><value>${ .smtp.pass</value></property> </bean> Paso 3: Definir plantilla/s de correo en applicationcontext-services.xml Definimos y configuramos los bean de Spring Simpl Message que requiramos para modelar los diferentes tipos de correos. Asignamos valores a los parámetros de configuración del fichero environment.properties. applicationcontext-services.xml  <bean id="sampl message" class="org.springframework.mail.simpl message"> <property name="from"><value>${ .from</value></property>  <property name="subject"><value>${ .subject</value></property> <property name="text"><value>${ .text</value></property> </bean> 7 de 19

8 4. USO Una vez configurado el entorno para el uso del servicio, puede procederse a su utilización. Análogamente al resto de servicios de Spring, para hacer uso de los beans de correo, declararemos los atributos respectivos a cada uno de ellos en el servicio que los queramos usar -con sus métodos set correspondientes-. Ejemplo de envio de correo... private MailSender mailsender; private Simpl Message mailmessage; public void setmailsender(mailsender mailsender) { this.mailsender = mailsender; public void setmailmessage(simpl message mailmessage) { this.mailmessage = mailmessage; public void sendcourseenrollmentreport() { Set courselist = coursedao.findall(); Simpl Message message = new Simpl Message(this.mailMessage); StringBuffer messagetext = new StringBuffer(); messagetext.append("los cursos son los siguientes:\n\n"); for(iterator iter = courselist.iterator(); iter.hasnext(); ) { Course course = (Course) iter.next(); messagetext.append(course.getid() + " "); messagetext.append(course.getname() + " "); int enrollment = coursedao.getenrollment(course); messagetext.append(enrollment); message.settext(messagetext.tostring()); msg.setto( ); try { mailsender.send(message); catch (MailException e) { de 19

9 Cuando el contenido de los correos electrónicos manejados por la aplicación sea complejo, se empleará el mecanismo de plantillas que ofrece Velocity para crear plantillas avanzadas para envío de correo electrónico. Estas plantillas se podrán crear en formato HTML y se almacenaran en la carpeta plantillas. Ejemplo de plantilla de correo <html> <body> <h3>hi ${user.username, welcome to the Chipping Sodbury On-the-Hill message boards!</h3> <div>your address is </div> </body> </html> <a href="mailto:${user. address">${user. address</a>. De esta forma se pueden crear plantillas de correo mediante cualquier editor (por ejemplo, con un editor de HTML), y definir variables que se establecerán en tiempo de ejecución para el mensaje de correo. Para usar Velocity desde un servicio Spring, simplemente se le ha de pasar mediante inyección de control el bean de Spring que maneja el motor de Velocity, y usarlo en el código de envío de correo de la forma tradicional: Bean de Spring para Velocity <bean id="velocityengine" class="org.springframework.ui.velocity.velocityenginefactorybean"> </bean> <property name="velocityproperties"> <value>resource.loader=class class.resource.loader.class= org.apache.velocity.runtime.resource.loader.classpathresourceloader </value> </property> Para enviar el mensaje, ahora es necesario hacer uso de un mensaje MIME (estamos enviando un mail en HTML), para tal propósito aprovecharemos las interfaces de ayuda que ofrece Spring, MimeMessageHelper o MimeMessagePreparator. En este caso MimeMessagePreparator: Ejemplo de envio de correo con plantilla personalizada 9 de 19

10 private void sendconfirmation (final User user) { MimeMessagePreparator preparator = new MimeMessagePreparator() { public void prepare(mimemessage mimemessage) throws Exception { MimeMessageHelper message = new MimeMessageHelper(mimeMessage); message.setto(user.get address()); message.setfrom("from@ .com"); // Se establecen los campos a mapear en el correo Map model = new HashMap(); model.put("user", user); String text = VelocityEngineUtils.mergeTemplateIntoString( velocityengine, "plantillas/correo.vm", model); message.settext(text, true); ; this.mailsender.send(preparator); 4.1. Crear servicio de correo Crear interfaz del servicio de correo Comenzamos con la implementación de un servicio, creando una interfaz, para obligarnos a implementar una serie de métodos, los típicos para el envío de correo electrónico. NOTA El servicio que se muestra a continuación no tiene como finalidad ser utilizado como servicio de envío de correos de aplicaciones Atlas, simplemente se trata de un ejemplo de integración con el framework. Cada proveedor debe hacer los cambios oportunos para adecuarlos a sus necesidades. Para nuestro ejemplo usaremos los siguientes: CorreoService.java 10 de 19

11 * Esta interfaz representa las operaciones de envio de correos. ICM 1.0. public interface CorreoService { * Método para enviar un mail con texto plano para Campo para del mail asunto Asunto del mail texto Texto plano ServiceException Si ocurre algún error void envioejemplocorreo(string para, String asunto, String texto) throws ServiceException; * Método para enviar un mail con texto HTML para Campo para del mail asunto Asunto del mail texto Texto HTML ServiceException Si ocurre algún error void envioejemplocorreohtml(string para, String asunto, String textohtml) throws ServiceException; Crear implementación del servicio de envío de s Creamos la implementación de los métodos definidos en la interfaz CorreoService. Como se puede apreciar obtenemos algunos de los valores de la plantilla mailmessage y para el envío de s HTML creamos un mensaje tipo MIME gracias a la clase MimeMessageHelper. Para la realización de este clase se han seguido los ejemplos que vienen en la documentación del framework Spring dedicada a . CorreoServiceImpl.java 11 de 19

12 * Esta clase representa el servicio de ejemplo de envío de public class CorreoServiceImpl implements CorreoService { wrapper de Spring sobre javax.mail private JavaMailSender mailsender; Plantilla del mensaje * private Simpl Message mailmessage; public JavaMailSender getmailsender() { return mailsender; public void setmailsender(javamailsender mailsender) { this.mailsender = mailsender; public Simpl Message getmailmessage() { return mailmessage; public void setmailmessage(simpl message mailmessage) { this.mailmessage = mailmessage; * Método que envia el correo para para asunto asunto texto texto ServiceException si ocurre algún error public void envioejemplocorreo(string para, String asunto, String texto) throws ServiceException { Simpl Message message = new Simpl Message(this.mailMessage); message.setto(para); message.setsubject(asunto); message.settext(texto); try { mailsender.send(message); catch (MailException e) { throw new public void envioejemplocorreohtml(string para, String asunto, String textohtml) throws ServiceException { MimeMessage message = mailsender.createmimemessage(); try { // use the true flag to indicate you need a multipart message MimeMessageHelper helper = new MimeMessageHelper(message, true); helper.setfrom(mailmessage.getfrom()); helper.setto(para); helper.setsubject(asunto); helper.settext(textohtml, true); catch (MessagingException e) { throw new ServiceException(e); try { mailsender.send(message); catch (MailException e) { throw new ServiceException(e); 12 de 19

13 Definir servicio de correo en applicationcontext-services.xml Publicamos nuestro servicio en el contexto, inyectándole la dependencia al servicio de envío propio de Spring y la plantilla. applicationcontext-services.xml  <bean id="correoservice" class="atlas.correo.services.correoserviceimpl"> <property name="mailsender"><ref bean="mailsender"/></property> <property name="mailmessage"><ref bean="sampl message"/></property> </bean> NOTA Con la implementación de la interfaz y esta configuración ya podemos hacer uso de nuestro servicio de envío desde cualquiera de nuestras clases de negocio gestionadas por Spring. A continuación mostraremos un ejemplo de uso del servicio a través de una página JSF. Si ya se tiene claro cómo utilizarlo (igual que el resto de servicios Spring) se puede dar por finalizado el manual. El siguiente ejemplo ha sido extraído de la aplicación de ejemplo de integración*. En el documento de Normativa Atlas se pue Aplicación de ejemplo de integración Aplicación de ejemplo creada para mostrar la integración con los diferentes servicios Atlas Url de acceso (usuario_ok/usuario_ok) Código fuente 4.2. Crear fachada Como se explica en la normativa, las páginas JSF interactúan con los servicios a través de una facahada. Así pues, para nuestro ejemplo, creamos la fachada CorreoFacade (interfaz e implementación) para que llame a nuestro servicio CorreoService Crear interfaz de la fachada CorreoFacade.java 13 de 19

14 * Esta interfaz representa las operaciones de la facacha para el envio de * correos. * ICM 1.0. public interface CorreoFacade { * Método de ejemplo de envio de correo * para para asunto asunto texto texto eshtml indica si el texto del correo es HTML (true) o es texto plano (false) ServiceException si ocurre algún error void envioejemplocorreo(string para, String asunto, String texto, boolean eshtml) throws ServiceException; Crear implementación de la fachada CorreoFacadeImpl.java 14 de 19

15 * Esta clase representa la fachada para el envio de correos. ICM public class CorreoFacadeImpl implements CorreoFacade { El servicio de correo private CorreoService correoservice; * Este metodo inyecta el servicio de correo * correoservice El servicio a inyectar. public void setcorreoservice(correoservice correoservice) { this.correoservice = correoservice; * {@inheritdoc * atlas.correo.services.facade.correofacade#envioejemplocorreo() public void envioejemplocorreo(string para, String asunto, String texto, boolean eshtml) throws ServiceException { if (!eshtml) correoservice.envioejemplocorreo(para, asunto, texto); else correoservice.envioejemplocorreohtml(para, asunto, texto); Definir fachada en applicationcontext-services.xml Definir y configurar la fachada, CorreoFacade, para que haga uso de nuestro servicio de correo. applicationcontext-services.xml <bean id="correofacade" class="atlas.correo.services.facade.correofacadeimpl"> <description> Bean que representa la fachada por la cual acceder a los servicios para el envio de correos </description> <property name="correoservice" ref="correoservice" /> </bean> 4.3. Crear presentación JSF Crear backing bean Creamos un bean JSF que realiza la acción de enviar el correo. Esta clase hace uso del servicio de correo a través de la fachada recién creada. CorreoFormBean.java 15 de 19

16 * The Class CorreoFormBean. ICM public class CorreoFormBean extends BaseBean { Servicio de la fachada private CorreoFacade correofacade; private String para; Destinatario del correo private String asunto; Asunto del correo private String texto; Texto del correo private String enviado; Texto del enviado Indica si el texto es HTML o texto plano private boolean textohtml = false; * Envía correo ServiceException si ocurre algún error public void enviarcorreo() throws ServiceException { try { correofacade.envioejemplocorreo(this.para, this.asunto, this.texto, this.textohtml); this.enviado = AtlasFacesUtils.getStringFromBundle("correo.enviado"); catch (ServiceException e) { this.enviado = AtlasFacesUtils.getStringFromBundle("correo.noenviado"); AtlasFacesUtils.storeOnRequestError(FacesContext.getCurrentInstance(), "error.mail_envio_correo", e); NOTA: faltan los getters y setters de los atributos Definir backing bean en faces-managed-beans.xml faces-managed-beans.xml <managed-bean> <description> Bean de respaldo de los ejemplos de envio de correos </description> <managed-bean-name>correoformbean</managed-bean-name> <managed-bean-class> atlas.correo.jsf.correoformbean </managed-bean-class> <managed-bean-scope>request</managed-bean-scope> <managed-property> <property-name>correofacade</property-name> <value>#{correofacade</value> </managed-property> </managed-bean> 16 de 19

17 Crear página JSF Por simplicidad, sólo mostramos los campo de texto que estableces el destinatario y el cuerpo del correo y el componente que realiza la acción de enviar el correo. Se han omitido los campos para establecer el asunto y si el cuerpo del correo es texto simple o HTML. Como se ha indicado anteriormente, todo el código de la aplicación está disponible a través de la siguiente dirección: Código fuente de la aplicación de ejemplo de integración de servicios Atlas correosample.xhtml  <h:outputlabel id="outputlabelpara" for="inputtextpara" styleclass="label" value="#{bundle['correo.para']" /> <h:panelgrid columns="2" cellpadding="0" cellspacing="0"> <h:inputtext id="inputtextpara" size="62" maxlength="50" styleclass="cajatexto" value="#{correoformbean.para" required="true" requiredmessage="#{correoformbean.requiredmessage"/> <h:message for="inputtextpara" styleclass="errorclass" showdetail="true" showsummary="false"/> </h:panelgrid> <h:outputlabel id="outputlabeltexto" for="inputtexttexto" styleclass="label" value="#{bundle['correo.texto']" /> <h:panelgrid columns="2" cellpadding="0" cellspacing="0"> <h:inputtextarea id="inputtexttexto" styleclass="cajatexto" cols="60" rows="5" value="#{correoformbean.texto" required="true" requiredmessage="#{correoformbean.requiredmessage"/> <h:message for="inputtexttexto" styleclass="errorclass" showdetail="true" showsummary="false"/> </h:panelgrid> <h:commandlink styleclass="botonaplicaciontxt" action="#{correoformbean.enviarcorreo" id="enviarcorreo" value="#{bundle['correo.enviar']"> <h:graphicimage value="img/ico_nuevo.gif" alt="#{bundle['correo.enviar']" /> </h:commandlink> 17 de 19

18 5. ENLACES RELACIONADOS Producto Spring Spring Atlas Integración URL de 19

19 6. ANEXOS 6.1. environment.properties applicationcontext-services.xml # correo electronico .smtp.host=mail.madrid.org .smtp.user=pendiente .smtp.pass=pendiente # plantilla .from=icm_dga_soporte_arquitectura@madrid.org .to=icm_dga_soporte_arquitectura@madrid.org .subject=ejemplo de integraci\u00f3n de correo electr\u00f3nico .cc=icm_dga_soporte_arquitectura@madrid.org .text=texto de prueba de env\u00edo de correo 6.2. applicationcontext-services.xml applicationcontext-services.xml  <bean id="mailsender" class="org.springframework.mail.javamail.javamailsenderimpl"> <property name="host"><value>${ .smtp.host</value></property> <property name="username"><value>${ .smtp.user</value></property> <property name="password"><value>${ .smtp.pass</value></property> </bean>  <bean id="sampl message" class="org.springframework.mail.simpl message"> <property name="from"><value>${ .from</value></property>  <property name="subject"><value>${ .subject</value></property> <property name="text"><value>${ .text</value></property> </bean>  <bean id="correoservice" class="atlas.correo.services.correoserviceimpl"> <property name="mailsender"><ref bean="mailsender"/></property> <property name="mailmessage"><ref bean="sampl message"/></property> </bean> <bean id="correofacade" class="atlas.correo.services.facade.correofacadeimpl"> <description> Bean que representa la fachada por la cual acceder a los servicios para el envio de correos </description> <property name="correoservice" ref="correoservice" /> </bean> 19 de 19