Introducción Clases básicas Ejemplos TEMA 7. El API JavaMail Introducción Clases básicas Ejemplos

Bibliografía Sun. “Documentación de Java”. http://java.sun.com . Traducciones al castellano en http://www.programacion.com/java/tutorial/javamail

Uso del API JavaMail 1 . Introducción El API JavaMail es un paquete opcional (extensión estándard) para leer, componer, y enviar mensajes electrónicos. El uso de este paquete esta orientado a la creación de programas de tipo MUA (Mail User Agent), similares a Thunderbird y Microsoft Outlook. Su propósito principal por lo tanto no es transportar, enviar, o re-enviar mensajes como sendmail u otros programas del tipo MTA (Mail Transfer Agent). En otras palabras, los usuarios interactúan con los programas para leer y escribir e-mails. Los programas MUA tratan con los programas MTA para el envío real.

Uso del API JavaMail 1 . Introducción El API JavaMail está diseñado para proporcionar acceso independiente del protocolo para enviar y recibir mensajes dividiéndose en dos partes: La primera parte del API está orientada al envío y recepción de mensajes independientemente del proveedor/protocolo. La segunda parte esta orientada a los lenguajes específicos del protocolo como SMTP, POP, IMAP, y NNTP. Con el API, JavaMail para poder comunicar con un servidor, necesitamos un proveedor para un protocolo.

Protocolos de mensajería 1 . Introducción Protocolos de mensajería Básicamente son cuatro: SMTP POP IMAP MIME NNTP y otros Aunque el API sea independiente del protocolo, no podemos evitar las limitaciones de los protocolos subyacentes. Si una capacidad no está soportada por el protocolo elegido, el API JavaMail no hará que esa capacidad aparezca por arte de magia.

1 . Introducción SMTP El protocolo Simple Mail Transfer Protocol (SMTP) está definido por la RFC 821. Define el mecanismo para enviar e-mail. En el contexto del API JavaMail, nuestro programa basado en JavaMail comunicará con el servidor SMTP de nuestro proveedor de servicios (ISP). Este servidor SMTP dejará el mensaje en el servidor SMTP del recipiente(s) para que sea recogido por los usuarios a través de POP o IMAP. Esto no requiere que nuestro servidor SMTP sea un rele abierto, pues se utiliza la autentificación, pero es nuestra responsabilidad asegurarnos de que el servidor SMTP se configure correctamente. No hay nada en el API JavaMail sobre tareas como el configuración de un servidor para retransmitir mensajes o para agregar y para quitar cuentas del e-mail

1 . Introducción POP POP viene de Post Office Protocol. Actualmante en la versión 3, también conocido como POP3, la RFC 1939 define este protocolo. POP es el mecanismo que la mayoría de la gente usa en Internet para conseguir su correo. Define el soporte de un sólo mailbox por cada usuario. Muchas de las cosas con las que estamos familiarizados cuando usamos POP, como la capacidad de ver cuántos mensajes de correo nuevos tienen, no lo soporta POP en absoluto. Estas capacidades se construyen en programas como Eudora o Microsoft Outlook.

1 . Introducción IMAP IMAP es un protocolo más avanzado para recibir mensajes. Definido en la RFC 2060, IMAP viene de Internet Message Access Protocol, y está actualmente en la versión 4, también conocida como IMAP4. Para usar el IMAP, nuestro servidor de correo debe soportar este protocolo. Debido a las capacidades más avanzadas, podríamos pensar que IMAP sería utilizado por todos. Pero no es así. Sobrecarga mucho el servidor de correo, requiriendo que el servidor reciba los nuevos mensajes, los entregue a los usuarios cuando sean solicitados, y los mantiene en las distintas carpetas de cada usuario. Aunque esto centraliza las copias de seguridad, también hace que las carpetas de correo a largo plazo de los usuarios se hagan cada vez más grandes. Con POP, los mensajes recuperados son eliminados del servidor de correo.

javax.mail 2 . Clases Básicas Las clases básicas que componen el API: Session, Message, Address, Authenticator, Transport, Store, y Folder. Todas estas clases se encuentran en el paquete del nivel superior del API JavaMail (J2EE): javax.mail, aunque frecuentemente nos veremos utilizando clases del paquete javax.mail.internet.

Session 2 . Clases Básicas La clase Session define una sesión de correo básica. A partir de una sesión se usan el resto de clases. El objeto Session se aprovecha de un objeto java.util.Properties para obtener información como el servidor de correo, el nombre de usuario, la password, y otras informaciones. El constructor para las clases es privado. Podemos obtener una sola sesión por defecto que puede ser compartida con el método getDefaultInstance(): Properties props = new Properties(); Session session = Session.getDefaultInstance(props, null);

Session 2 . Clases Básicas Alternativamente Properties props = new Properties(); Session session = Session.getInstance(props, null); En ambos casos el argumento null es un objeto Authenticator que no se utiliza en este momento, lo veremos más adelante en Authenticator.

Session 2 . Clases Básicas Para indicar el servidor de envío lo hacemos mediante el objeto Properties, de la siguiente forma: String host= …; Properties props = System.getProperties(); props.put("mail.smtp.host", host); Session session = Session.getDefaultInstance(props, null);

Message 2 . Clases Básicas Una vez que tenemos nuestro objeto Session, es hora de empezar a crear un mensaje para enviar. Esto se hace con un objeto Message. Siendo una clase abstracta, debemos trabajar con una subclalse, en la mayoría de los casos será javax.mail.internet.MimeMessage. Un MimeMessage es un mensaje de e-mail que entiende los tipos MIME, definidos en las distintas RFCs. Para crear un Message, le pasamos el objeto Session al constructor de MimeMessage: MimeMessage message = new MimeMessage(session);

Message 2 . Clases Básicas El mecanismo básico para configurar el contenido es el método setContent(), con los argumentos para el contenido y tipo mime: message.setContent("Hello", "text/plain"); Sin embargo, si sabemos que estámos trabajando con un MimeMessage y nuestro mensaje es texto plano, podemos usar su método setText() que sólo requiere el contenido real. message.setText("Hello"); Para seleccionar el subject, usamos el método setSubject(): message.setSubject("First");

Address 2 . Clases Básicas Una vez que hemos creado la Session y el Message, y también hemos rellenado el mensaje con contenido, es hora de poner dirección a nuestra carta con un objeto Address. Como Message, Address es una clase abstracta. Usaremos la clase javax.mail.internet.InternetAddress. Para crear una dirección con sólo la dirección e-mail, se la pasamos al constructor: Address address = new InternetAddress("president@whitehouse.gov"); Si queremos que aparezca el nombre junto a la dirección e-mail, también podemos pasárselo al constructor: Address address = new InternetAddress("president@whitehouse.gov", "George Bush");

Address 2 . Clases Básicas Necesitaremos crear objetos address para los campos from y to del mensaje. A menos que el servidor lo evite, no hay nada que nos impida enviar un mensaje que parezca que viene de otra persona. Una vez que hemos creado las direcciones, las conectamos al mensaje de una de estas dos formas. Para identificar al que lo envía, usamos los métodos setFrom() y setReplyTo(). message.setFrom(address) Si nuestro mensaje necesita varias direcciones "from", usamos el método addFrom():

Address 2 . Clases Básicas Para identificar a los receptores del mensaje, usamos el método addRecipient(). Este método requiere un Message.RecipientType junto a la dirección. message.addRecipient(type, address) Los tres tipos predefinidos de direcciones son: Message.RecipientType.TO Message.RecipientType.CC Message.RecipientType.BCC Por eso, si el mensaeje fuera dirigido al vice-presidete, enviando copia a la primera dama, esto sería lo apropiado: Address toAddress = new InternetAddress("vice.president@whitehouse.gov"); Address ccAddress = new InternetAddress("first.lady@whitehouse.gov"); message.addRecipient(Message.RecipientType.TO, toAddress); message.addRecipient(Message.RecipientType.CC, ccAddress);

Authenticator 2 . Clases Básicas El API JavaMail puede aprovecharse de un Authenticator para proteger accesos a recursos mediante un nombre de usuario y una password. Para usar el Authenticator, subclasificamos la clase abstracta y devolvemos un ejemplar PasswordAuthentication del método getPasswordAuthentication(). Debemos registrar el Authenticator con la sesión cuando se crea. Luego, nuestro Authenticator será notificado cuando sea necesaria una autentificación. Podríamos mostrar una ventana o leer el nombre de usuario y la password desde un fichero de configuración (aunque si no está encriptado no es seguro), devolviendolo al llamador como un objeto PasswordAuthentication. Properties props = new Properties(); Authenticator auth = new MyAuthenticator(); Session session = Session.getDefaultInstance(props, auth);

Transport 2 . Clases Básicas La parte final del envío de un mensaje es usar la clase Transport. Estas clase habla el lenguaje específico del protocolo para enviar mensajes (normalmente SMTP). Es una clase abstracta y funciona como Session. Podemos usar la versión por defecto de la clase sólo llamando al método estático send(): Transport.send(message);

Transport 2 . Clases Básicas O, podemos obtener un ejemplar específico desde la sesión para nuestro protocolo, pasándole el nombre de usuario y la password (en blanco si no son necesarias), enviar el mensaje, y cerrar la conexión: message.saveChanges(); Transport transport = session.getTransport("smtp"); transport.connect(host, username, password); // envia el mensaje a la lista de destinatarios // los del mensaje o los que pongamos transport.sendMessage(message, message.getAllRecipients()); transport.close(); Esta última forma es mejor cuando necesitamos enviar varios mensajes, porque mantendrá activa la conexión entre mensajes. El mecanismo básico send() hace un conexión separada al servidor para cada llamada a método.

Store y Folder 2 . Clases Básicas Obtener los mensajes empieza de forma similar a enviar mensajes, con una Session. Sin embargo, después de obtener la sesión, conectamos a un Store, probablemente con un nombre de usuario y una password o Authenticator. Como con Transport, le decimos al Store qué protocolo utilizar: Store store = session.getStore("imap"); Store store = session.getStore("pop3"); store.connect(host, username, password);

Store y Folder 2 . Clases Básicas Después de conectar al Store, podemos obtener un Folder, que debe estar abierto antes de poder leer los mensajes que hay en su interior: Folder folder = store.getFolder("INBOX"); folder.open(Folder.READ_ONLY); Message message[] = folder.getMessages(); Para POP3, la única carpeta disponible es INBOX. Si estamos usando IMAP, podremos disponer de otras carpetas.

Store y Folder 2 . Clases Básicas Una vez que tenemos un Message para leer, podemos obtener sus contenidos con getContent() o escribir sus contenidos en un stream con writeTo(). El método getContent() sólo obtiene el contenido del mensaje, mientras que la salida de writeTo() incluye las cabeceras. System.out.println(((MimeMessage)message).getContent()) Después de haber leído el e-mail, cerramos la conexión al folder y al store. folder.close(aBoolean); store.close(); El valor booleno pasado al método close() del folder significa si actualizamos o no la carpeta eliminando los mensajes borrados.

Borrar mensajes 2 . Clases Básicas Borrar mensajes implica trabajar con las Flags asociadas con los mensajes. Hay diferentes banderas para diferentes estados, algunas definidas por el sistema y otras definidas por el usuario. Las banderas predefinidas se definen en forma de clase interna Flags.Flag y se listan abajo: Flags.Flag.ANSWERED Flags.Flag.DELETED Flags.Flag.DRAFT Flags.Flag.FLAGGED Flags.Flag.RECENT Flags.Flag.SEEN Flags.Flag.USER Sólo porque una bandera exista no significa que sea soportada por todos los proveedores/servidores de correo. Para conocer las banderas soportadas, solicitamos la carpeta con getPermanentFlags().

Borrar mensajes 2 . Clases Básicas Para borrar mensajes, seleccionamo la bandera DELETED del mensaje: message.setFlag(Flags.Flag.DELETED, true); Primero debemos abrir la carpeta en modo READ_WRITE: folder.open(Folder.READ_WRITE); Luego, cuando hayamos procesado todos los mensajes, cerramos la carpeta, pasando un valor true para purgar todos los mensajes borrados. folder.close(true); Hay un método expunge() de Folder que puede usarse para borrar los mensajes. Sin embargo, no funciona con el proveedor POP3 de Sun. Para deseleccionar una bandera, sólo pasando false al método setFlag(). Para ver si una bandera está seleccionada, lo comprobamos con isSet().

Enviar mensajes 3 . Ejemplos import java.util.Properties; import javax.mail.*; import javax.mail.internet.*; public class MailExample { public static void main (String args[]) throws Exception { String host = args[0]; String from = args[1]; String to = args[2]; // Get system properties Properties props = System.getProperties(); // Setup mail server props.put("mail.smtp.host", host); // Get session Session session = Session.getDefaultInstance(props, null); // Define message MimeMessage message = new MimeMessage(session); // Set the from address message.setFrom(new InternetAddress(from)); // Set the to address message.addRecipient(Message.RecipientType.TO, new InternetAddress(to)); // Set the subject message.setSubject("Hello JavaMail"); // Set the content message.setText("Welcome to JavaMail"); // Send message Transport.send(message); } }

Enviar mensajes 3 . Ejemplos Properties props = new Properties(); props.put("mail.smtp.host", "my-mail-server"); props.put("mail.from", "me@example.com"); Session session = Session.getInstance(props, null); try { MimeMessage msg = new MimeMessage(session); msg.setFrom(); msg.setRecipients(Message.RecipientType.TO, "you@example.com"); msg.setSubject("JavaMail hello world example"); msg.setSentDate(new Date()); msg.setText("Hello, world!\n"); Transport.send(msg); } catch (MessagingException mex) { System.out.println("send failed, exception: " + mex); }