Las clases Corazón
Revisar las Clases Corazón
Antes de profundizar en las classes de JavaMail, veremos las clases corazón 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: javax.mail, aunque frecuentemente nos veremos utilizando clases del paquete javax.mail.internet.
Session
La clase Session define una sesión de correo básica. Es a través de esta de sesión de la que todas las demás funcionan. 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 otra información que puede compartirse a lo largo de toda la aplicación.
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();
// fill props with any information
Session session = Session.getDefaultInstance(props, null);
O podemos crear una única sesión con getInstance():
Properties props = new Properties();
// fill props with any information
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.
En la mayoría de los casos, es suficiente usar la sesión compartida, incluso si se trabaja con una sesión de correo para múltiples mailboxes de usuario. Podemos añadir una combinación de nombre de usuario y passsword en un paso posterior en el proceso de comunicación, manteniendolo todo separado.
Message
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 subcalse, 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. Las cabeceras de mensajes están restringidas a caracteres US-ASCII, aunque en ciertos campos de cabecera se pueden codificar caracteres no ASCII.
Para crear un Message, le pasamos el objeto Session al constructor de MimeMessage:
MimeMessage message = new MimeMessage(session);
|
Nota: Hay otros constructores, como para crear mensajes desde streams de entrada formateados RFC822.
|
Una vez que tenemos nuestro mensaje, podemos configurar sus diferentes partes, como Message implementa el interface Part (con MimeMessage implementando MimePart).
El mecanismo básico para configurar el contenidos 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, dejando por defecto el tipo MIME a text/plain:
message.setText("Hello");
Para mensajes de texto plano la última forma es el mecanismo preferido para seleccionar el contenido. Para enviar otros tipos de mensajes, como HTML, usaremos el formador, que veremos más adelante.
Para seleccionar el subject, usamos el método setSubject():
message.setSubject("First");
Address
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");
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 mensane necesita varias direcciones "from", usamos el método addFrom():
Address address[] = ...;
message.addFrom(address);
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);
El API JavaMail no proporciona mecanismo para chequear la validez de una dirección e-mail. Pero si podemos hacer que nuestro programa soporte un scan de caracteres válidos (según lo definido en la RFC 822) o verificar nosotros mismos el registro MX (Mai Exchange), esto va más allá del ámbito del API JavaMail.
Authenticator
Como las clases java.net, el API JavaMail peude aprovecharse de un Authenticator para proteger accesos a recursos mediante un nombre de usuario y una password. Para el API JavaMail, el recursos es el servidor de correo. El Authenticator JavaMail se encuentra en el paquete javax.mail y es diferente de la clase de java.net con el mismo nombre. Las dos no comparten el mismo Authenticator ya que el API JavaMail funciona con Java 1.1, que no tenía la veriedad java.net.
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();
// fill props with any information
Authenticator auth = new MyAuthenticator();
Session session = Session.getDefaultInstance(props, auth);
Transport
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);
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(); // implicit with send()
Transport transport = session.getTransport("smtp");
transport.connect(host, username, password);
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.
|
Nota: Para ver los comandos enviados al servidor de correo activaremos la bandera debug con session.setDebug(true).
|
Store y Folder
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);
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.
|
Nota: Los proveedores de Sun se han pensado para ser inteligentes. Mientras que Message message[] = folder.getMessages(); podría parecer una operación lenta que lee todos los mensajes del servidor, sólo cuando realmente necesitamos obtener una parte del mensaje es cuando el contenido es recuperado.
|
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 boolenao pasado al método close() del folder significa si actualizamos o no la carpeta eliminando los mensajes borrados.
Más allá
Esencialmente, entender cómo usar las siete clases es todo lo que necesitamos para manejar el API JavaMail. La mayoría de las otras capacidades del API JavaMail construidas desde estas siete clases hacen algo un poco diferente o de una forma particular, como si el contenido es un attachment. Ciertas tareas, como las búsquedas, están aisladas y se describen en la sección Busquedas por SearchItem.
Tutoriales
