com.noelios.restlet.ext.javamail
Class JavaMailClientHelper

java.lang.Object
  extended by org.restlet.util.Helper<T>
      extended by com.noelios.restlet.ConnectorHelper<Client>
          extended by com.noelios.restlet.ClientHelper
              extended by com.noelios.restlet.ext.javamail.JavaMailClientHelper

public class JavaMailClientHelper
extends ClientHelper

Client connector to a mail server. This connector supports the SMTP, SMTP with STARTTLS and SMTPS protocols to send emails, POP v3 and POPS v3 to retrieved emails from a mail box.

To send an email, send a POST request with a resource reference on a SMTP or SMTPS URI and use an XML email as the entity. A SMTP URI has the following syntax: smtp://host[:port]

Use the Request.setChallengeResponse(org.restlet.data.ChallengeResponse) method to set the identified/login and secret/password. You will also need to specify the ChallengeScheme.SMTP_PLAIN challenge scheme.

Sample XML email:

 <?xml version="1.0" encoding="ISO-8859-1" ?>
  <email>
  <head>
  <subject>Account activation</subject>
  <from>support@restlet.org</from>
  <to>user@domain.com</to>
  <cc>log@restlet.org</cc>
  </head>
  <body><![CDATA[Your account was sucessfully created!]]></body>
  </email>
 
To receive the list of emails, send a GET request to a resource reference on a POP or POPS URI, leaving the reference path empty. A POP URI has the following syntax: pop://host[:port]

Use the Request.setChallengeResponse(org.restlet.data.ChallengeResponse) method to set the identified/login and secret/password. You will also need to specify the ChallengeScheme.POP_BASIC or the ChallengeScheme.POP_DIGEST challenge scheme.

Sample XML list of emails:
 <?xml version="1.0" encoding="ISO-8859-1" ?>
 <emails>
    <email href="/1234"/>
    <email href="/5678"/>
    <email href="/9012"/>
    <email href="/3456"/>
 </emails>
 
To retrieve an individual email, just add the href attribute at the end of the POP URI, such as: pop://host/1234
Here is the list of parameters that are supported:
Parameter name Value type Default value Description
startTls boolean false If true, the SMTP connector will attempt to start a TLS tunnel, right after the SMTP connection is established.
debug boolean false If true, the connector will generate JavaMail debug messages.
representationMessageClass String null If not null, represents the name of a class that extends the JavaMail "javax.mail.Message" class. This class is able to generate a Message from an XML representation and a JavaMail Session. The constructor must accept a Representation and a JavaMail Session objects as parameters in this order.

Author:
Jerome Louvel

Field Summary
static Protocol POP
          POP protocol.
static ChallengeScheme POP_BASIC
          Basic POP scheme.
static ChallengeScheme POP_DIGEST
          Digest POP scheme.
static Protocol POPS
          POPS protocol (via SSL/TLS socket)..
 
Constructor Summary
JavaMailClientHelper(Client client)
          Constructor.
 
Method Summary
static Request create(java.lang.String smtpURI, Representation email)
          Deprecated. With no replacement as it creates an unecessary dependency on NRE classes.
static Request create(java.lang.String smtpURI, Representation email, java.lang.String login, java.lang.String password)
          Deprecated. With no replacement as it creates an unecessary dependency on NRE classes.
protected  Message createMessage(Representation xmlMessage, Session session)
          Creates a JavaMail message by parsing an XML representation.
protected  Representation createRepresentation(Message message)
          Creates an XML representation based on a JavaMail message.
protected  Representation createRepresentation(Message[] messages, POP3Folder inbox)
          Creates an XML representation based on a list of JavaMail messages.
 java.lang.String getRepresentationMessageClass()
          Returns the full name of the class used for generating JavaMail Message instances from an XML representation and a JavaMail Session.
 void handle(Request request, Response response)
           
 boolean isDebug()
          Indicates if the connector should generate JavaMail debug messages.
 boolean isStartTls()
          Indicates if the SMTP protocol should attempt to start a TLS tunnel.
 
Methods inherited from class com.noelios.restlet.ClientHelper
getConnectTimeout
 
Methods inherited from class com.noelios.restlet.ConnectorHelper
getProtocols, start, stop, update
 
Methods inherited from class org.restlet.util.Helper
getAttributes, getContext, getHelped, getHelpedParameters, getLogger, setHelped
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

POP

public static final Protocol POP
POP protocol.


POP_BASIC

public static final ChallengeScheme POP_BASIC
Basic POP scheme. Based on the USER/PASS commands.


POP_DIGEST

public static final ChallengeScheme POP_DIGEST
Digest POP scheme. Based on the APOP command.


POPS

public static final Protocol POPS
POPS protocol (via SSL/TLS socket)..

Constructor Detail

JavaMailClientHelper

public JavaMailClientHelper(Client client)
Constructor.

Parameters:
client - The client to help.
Method Detail

create

@Deprecated
public static Request create(java.lang.String smtpURI,
                                        Representation email)
Deprecated. With no replacement as it creates an unecessary dependency on NRE classes.

Creates a high-level request.

Parameters:
smtpURI - The SMTP server's URI (ex: smtp://localhost).
email - The email to send (valid XML email).

create

@Deprecated
public static Request create(java.lang.String smtpURI,
                                        Representation email,
                                        java.lang.String login,
                                        java.lang.String password)
Deprecated. With no replacement as it creates an unecessary dependency on NRE classes.

Creates a high-level request.

Parameters:
smtpURI - The SMTP server's URI (ex: smtp://localhost).
email - The email to send (valid XML email).
login - Authenticate using this login name.
password - Authenticate using this password.

createMessage

protected Message createMessage(Representation xmlMessage,
                                Session session)
                         throws java.io.IOException,
                                AddressException,
                                MessagingException
Creates a JavaMail message by parsing an XML representation.

Parameters:
xmlMessage - The XML message to parse.
session - The current JavaMail session.
Returns:
The created JavaMail message.
Throws:
java.io.IOException
AddressException
MessagingException

createRepresentation

protected Representation createRepresentation(Message message)
                                       throws org.w3c.dom.DOMException,
                                              java.io.IOException,
                                              MessagingException
Creates an XML representation based on a JavaMail message.

Parameters:
message - The JavaMail message to format.
Returns:
The XML representation.
Throws:
org.w3c.dom.DOMException
java.io.IOException
MessagingException

createRepresentation

protected Representation createRepresentation(Message[] messages,
                                              POP3Folder inbox)
                                       throws java.io.IOException,
                                              MessagingException
Creates an XML representation based on a list of JavaMail messages.

Parameters:
messages - The list of JavaMail messages to format.
Returns:
The XML representation.
Throws:
java.io.IOException
MessagingException

getRepresentationMessageClass

public java.lang.String getRepresentationMessageClass()
Returns the full name of the class used for generating JavaMail Message instances from an XML representation and a JavaMail Session.

Returns:
The full name of the class used for generating JavaMail Message instances from an XML representation and a JavaMail Session.

handle

public void handle(Request request,
                   Response response)
Overrides:
handle in class Helper<Client>

isDebug

public boolean isDebug()
Indicates if the connector should generate JavaMail debug messages.

Returns:
True the connector should generate JavaMail debug messages.

isStartTls

public boolean isStartTls()
Indicates if the SMTP protocol should attempt to start a TLS tunnel.

Returns:
True if the SMTP protocol should attempt to start a TLS tunnel.


Copyright © 2005-2008 Noelios Technologies.