org.xmlBlaster.util.protocol.email
Class SmtpClient

java.lang.Object
  javax.mail.Authenticator
      org.xmlBlaster.util.protocol.email.SmtpClient

All Implemented Interfaces:

I_AdminSmtpClient, I_AdminUsage, I_Plugin, SmtpClientMBean

public class SmtpClient
extends javax.mail.Authenticator
implements I_Plugin, SmtpClientMBean

This class sends outgoing emails.

Developer note: Please don't use log.severe() or log.warning() to avoid recursion for logging-notification mails.

Author:

Marcel Ruff

See Also:

James MTA, Java Mail API, Javamail tutorial, The protocol.email requirement

Field Summary

static java.lang.String

OBJECTENTRY_KEY

Constructor Summary

SmtpClient()
Called from runlevel manager on server side.

Method Summary

int	getAsyncSendQueueSizeMax()
java.lang.String	getEnvPrefix() The command line key prefix
javax.mail.Message	getMessage()
javax.mail.PasswordAuthentication	getPasswordAuthentication() Used by Authenticator to access user name and password
java.lang.String	getProtocolId() Access the xmlBlaster internal name of the protocol driver.
javax.mail.Session	getSession() Access the mailing session.
static SmtpClient	getSmtpClient(Global glob, I_PluginConfig pluginConfig) The SmtpClient is a singleton in the Global scope.
int	getSmtpConnectionTimeout() mail.smtp.connectiontimeout Socket connection timeout value in milliseconds.
int	getSmtpIoTimeout() mail.smtp.timeout Socket I/O timeout value in milliseconds.
java.lang.String	getSmtpUrl() Access the SMTP access uri, for example "smtp://aUser:mypassword@mySmtpHost.org:25"
java.lang.String	getType() Enforced by I_Plugin
java.lang.String	getUsageUrl()
java.lang.String	getUser()
java.lang.String	getVersion() Enforced by I_Plugin
void	init(Global glob, PluginInfo pluginInfo) This method is called by the PluginManager (enforced by I_Plugin).
boolean	isAddExpiresHeader() If the message to send has an expiry date and this addExpiresHeader=true we send an 'Expires:' header in the email (Expiry Date Indication).
boolean	isAsyncSendQueueBlockOnOverflow()
boolean	isBreakLongMessageIdLine() Defaults to false.
boolean	isContentForceBase64() Force the MsgUnit attachment to always be base64 encoded.
boolean	isMessageIdForceBase64()
static void	main(java.lang.String[] args) Standalone usage example: java -Dmail.debug=true -Dmail.smtp.url=smtp://xmlBlaster:xmlBlaster@localhost:25 org.xmlBlaster.util.protocol.email.SmtpClient -from xmlBlaster@localhost -to xmlBlaster@localhost -expires +5000 The output is like
void	send(javax.mail.Message message) Send a ready prepared message.
void	sendEmail(EmailData emailData)
void	sendEmail(EmailData emailData, java.lang.String msgIdFileName)
void	sendEmail(javax.mail.internet.InternetAddress from, javax.mail.internet.InternetAddress to, java.lang.String subject, java.lang.String attachmentName, byte[] attachment, java.lang.String attachmentName2, java.lang.String attachment2, java.lang.String encoding)
void	sendEmail(javax.mail.internet.InternetAddress from, javax.mail.internet.InternetAddress to, java.lang.String subject, java.lang.String body, java.lang.String encoding)
void	sendEmail(java.lang.String from, java.lang.String to, java.lang.String subject, java.lang.String body)
void	sendEmail(java.lang.String from, java.lang.String to, java.lang.String subject, java.lang.String body, java.lang.String encoding)
void	sendEmailAsync(EmailData emailData)
void	sendEmailSync(EmailData emailData, java.lang.String msgIdFileName) Send a mail.
java.lang.String	sendTestEmail(java.lang.String to, java.lang.String from) JMX
void	setAddExpiresHeader(boolean addExpiresHeader) Add 'Expires:' email header.
void	setAsyncSendQueueBlockOnOverflow(boolean asyncSendQueueBlockOnOverflow)
void	setBreakLongMessageIdLine(boolean breakLongMessageIdLine) Defaults to false.
void	setContentForceBase64(boolean contentForceBase64) Setting this to true we can force the MsgUnit attachment to always be base64 encoded.
void	setMessageIdForceBase64(boolean messageIdForceBase64) Setting this to true we can force the messageId attachment to always be base64 encoded.
void	setSessionProperties(java.util.Properties props, Global glob, I_PluginConfig pluginConfig) Set session properties and create a session.
void	setSmtpUrl(java.lang.String uri)
void	setUsageUrl(java.lang.String url)
void	shutdown() Cleans up the resource.
java.lang.String	usage()

Methods inherited from class javax.mail.Authenticator

getDefaultUserName, getRequestingPort, getRequestingPrompt, getRequestingProtocol, getRequestingSite

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OBJECTENTRY_KEY

public static final java.lang.String OBJECTENTRY_KEY

Constructor Detail

SmtpClient

public SmtpClient()

Called from runlevel manager on server side.

Method Detail

getUser

public java.lang.String getUser()

Returns:

Returns the user.

getSmtpClient

public static SmtpClient getSmtpClient(Global glob,
                                       I_PluginConfig pluginConfig)
                                throws XmlBlasterException

The SmtpClient is a singleton in the Global scope. Access this singleton for the given global, and if it doesn't exist create one instance.

Parameters:

glob -

pluginInfo -

Returns:

never null

Throws:

XmlBlasterException

getProtocolId

public java.lang.String getProtocolId()

Access the xmlBlaster internal name of the protocol driver.

Returns:

The configured type in xmlBlasterPlugins.xml, defaults to "smtp"

getType

public java.lang.String getType()

Enforced by I_Plugin

Specified by:

getType in interface I_Plugin

Returns:

The configured type in xmlBlaster.properties, defaults to "smtp"

getEnvPrefix

public java.lang.String getEnvPrefix()

The command line key prefix

Returns:

Defaults to "plugin/smtp"

getVersion

public java.lang.String getVersion()

Enforced by I_Plugin

Specified by:

getVersion in interface I_Plugin

init

public void init(Global glob,
                 PluginInfo pluginInfo)
          throws XmlBlasterException

This method is called by the PluginManager (enforced by I_Plugin). The SmtpClient singleton is registered in the Global object store.

Specified by:

init in interface I_Plugin

Throws:

XmlBlasterException

See Also:

I_Plugin.init(org.xmlBlaster.util.Global,org.xmlBlaster.util.plugin.PluginInfo)

getPasswordAuthentication

public javax.mail.PasswordAuthentication getPasswordAuthentication()

Used by Authenticator to access user name and password

Overrides:

getPasswordAuthentication in class javax.mail.Authenticator

setSessionProperties

public void setSessionProperties(java.util.Properties props,
                                 Global glob,
                                 I_PluginConfig pluginConfig)
                          throws XmlBlasterException

Set session properties and create a session.

Example settings:

 Properties props = System.getProperties();
 props.put("mail.debug", "true");
 props.put("mail.smtp.url", "smtp://demo:secret@localhost:2525");
 

If a property is not found System.getProperty() is consulted.

Throws:

XmlBlasterException

See Also:

SMTP API, POP3 API

sendEmailAsync

public void sendEmailAsync(EmailData emailData)
                    throws XmlBlasterException

Throws:

XmlBlasterException

getSession

public javax.mail.Session getSession()

Access the mailing session.

getMessage

public javax.mail.Message getMessage()

send

public void send(javax.mail.Message message)
          throws javax.mail.MessagingException

Send a ready prepared message.

Usually you choose the convenience method sendEmail()

Throws:

javax.mail.MessagingException

sendEmail

public void sendEmail(java.lang.String from,
                      java.lang.String to,
                      java.lang.String subject,
                      java.lang.String body)
               throws javax.mail.internet.AddressException,
                      javax.mail.MessagingException

Throws:

javax.mail.internet.AddressException

javax.mail.MessagingException

sendEmail

public void sendEmail(java.lang.String from,
                      java.lang.String to,
                      java.lang.String subject,
                      java.lang.String body,
                      java.lang.String encoding)
               throws javax.mail.internet.AddressException,
                      javax.mail.MessagingException

Throws:

javax.mail.internet.AddressException

javax.mail.MessagingException

sendEmail

public void sendEmail(javax.mail.internet.InternetAddress from,
                      javax.mail.internet.InternetAddress to,
                      java.lang.String subject,
                      java.lang.String body,
                      java.lang.String encoding)
               throws javax.mail.internet.AddressException,
                      javax.mail.MessagingException

Parameters:

body - Is assumed to be of mime type "text/plain"

encoding - (charset) for example "UTF-8", will set the mail header:

          Content-Type: text/plain; charset=UTF-8
 

Throws:

javax.mail.internet.AddressException

javax.mail.MessagingException

sendEmail

public void sendEmail(javax.mail.internet.InternetAddress from,
                      javax.mail.internet.InternetAddress to,
                      java.lang.String subject,
                      java.lang.String attachmentName,
                      byte[] attachment,
                      java.lang.String attachmentName2,
                      java.lang.String attachment2,
                      java.lang.String encoding)
               throws XmlBlasterException

Parameters:

attachmentName2 - If not null this second attachment is added as "text/plain"

encoding - For example "UTF-8"

Throws:

XmlBlasterException

sendTestEmail

public java.lang.String sendTestEmail(java.lang.String to,
                                      java.lang.String from)

JMX

Specified by:

sendTestEmail in interface SmtpClientMBean

Parameters:

to - For example "demo@localhost"

from - For example "xmlBlaster@localhost"

Returns:

A success description

sendEmail

public void sendEmail(EmailData emailData)
               throws XmlBlasterException

Throws:

XmlBlasterException

sendEmail

public void sendEmail(EmailData emailData,
                      java.lang.String msgIdFileName)
               throws XmlBlasterException

Throws:

XmlBlasterException

sendEmailSync

public void sendEmailSync(EmailData emailData,
                          java.lang.String msgIdFileName)
                   throws XmlBlasterException

Send a mail.

Parameters:

emailData - Container holding the message to send

Throws:

XmlBlasterException

shutdown

public void shutdown()

Description copied from interface: I_Plugin

Cleans up the resource.

Specified by:

shutdown in interface I_Plugin

getSmtpUrl

public java.lang.String getSmtpUrl()

Description copied from interface: I_AdminSmtpClient

Access the SMTP access uri, for example "smtp://aUser:mypassword@mySmtpHost.org:25"

Specified by:

getSmtpUrl in interface I_AdminSmtpClient

Returns:

The SMTP server uri

setSmtpUrl

public void setSmtpUrl(java.lang.String uri)

Specified by:

setSmtpUrl in interface I_AdminSmtpClient

Parameters:

uri - For example "smtp://aUser:mypassword@mySmtpHost.org:25"

usage

public java.lang.String usage()

Specified by:

usage in interface I_AdminUsage

Returns:

a human readable usage help string

getUsageUrl

public java.lang.String getUsageUrl()

Specified by:

getUsageUrl in interface I_AdminUsage

Returns:

A link for JMX usage

setUsageUrl

public void setUsageUrl(java.lang.String url)

Specified by:

setUsageUrl in interface I_AdminUsage

isContentForceBase64

public boolean isContentForceBase64()

Description copied from interface: I_AdminSmtpClient

Force the MsgUnit attachment to always be base64 encoded.

Specified by:

isContentForceBase64 in interface I_AdminSmtpClient

Returns:

Returns the contentForceBase64.

setContentForceBase64

public void setContentForceBase64(boolean contentForceBase64)

Description copied from interface: I_AdminSmtpClient

Setting this to true we can force the MsgUnit attachment to always be base64 encoded.
Javamail does base64 encoding automatically if need so the default of this variable is false.

Specified by:

setContentForceBase64 in interface I_AdminSmtpClient

Parameters:

contentForceBase64 - The contentForceBase64 to set.

isMessageIdForceBase64

public boolean isMessageIdForceBase64()

Specified by:

isMessageIdForceBase64 in interface I_AdminSmtpClient

Returns:

Returns the messageIdForceBase64.

setMessageIdForceBase64

public void setMessageIdForceBase64(boolean messageIdForceBase64)

Description copied from interface: I_AdminSmtpClient

Setting this to true we can force the messageId attachment to always be base64 encoded.
Javamail does base64 encoding automatically if need so the default of this variable is false.

Specified by:

setMessageIdForceBase64 in interface I_AdminSmtpClient

Parameters:

messageIdForceBase64 - The messageIdForceBase64 to set.

main

public static void main(java.lang.String[] args)

Standalone usage example: java -Dmail.debug=true -Dmail.smtp.url=smtp://xmlBlaster:xmlBlaster@localhost:25 org.xmlBlaster.util.protocol.email.SmtpClient -from xmlBlaster@localhost -to xmlBlaster@localhost -expires +5000 The output is like

Return-Path: 
Received: from localhost ([127.0.0.1])
          by noty (JAMES SMTP Server 2.2.0) with SMTP ID 501
          for ;
          Tue, 21 Feb 2006 10:54:58 +0100 (CET)
Message-ID: <13748088.01140515698827.JavaMail.xmlBlaster@noty>
Date: Tue, 21 Feb 2006 10:54:58 +0100 (CET)
From: blue@localhost
To: blue@localhost
Subject: Hi from java
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Expires: Tue, 21 Feb 2006 10:55:00 +0100 (CET)

Some body text

See Also:

for other properties

isAddExpiresHeader

public boolean isAddExpiresHeader()

Description copied from interface: I_AdminSmtpClient

If the message to send has an expiry date and this addExpiresHeader=true we send an 'Expires:' header in the email (Expiry Date Indication).
Supported as new RFC 822 header (Expires:). In general, no automatic action can be expected by MTAs.
Defaults to true.

Specified by:

isAddExpiresHeader in interface I_AdminSmtpClient

Returns:

Returns the addExpiresHeader.

See Also:

http://www.faqs.org/rfcs/rfc2156.html

setAddExpiresHeader

public void setAddExpiresHeader(boolean addExpiresHeader)

Description copied from interface: I_AdminSmtpClient

Add 'Expires:' email header. If the message to send has an expiry date and this addExpiresHeader=true we send an 'Expires:' header in the email (Expiry Date Indication).
Supported as new RFC 822 header (Expires:). In general, no automatic action can be expected by MTAs.
Defaults to true.

Specified by:

setAddExpiresHeader in interface I_AdminSmtpClient

Parameters:

addExpiresHeader - The addExpiresHeader to set.

See Also:

http://www.faqs.org/rfcs/rfc2156.html

isBreakLongMessageIdLine

public boolean isBreakLongMessageIdLine()

Description copied from interface: I_AdminSmtpClient

Defaults to false.

Specified by:

isBreakLongMessageIdLine in interface I_AdminSmtpClient

Returns:

Returns the breakLongMessageIdLine.

setBreakLongMessageIdLine

public void setBreakLongMessageIdLine(boolean breakLongMessageIdLine)

Description copied from interface: I_AdminSmtpClient

Defaults to false. If set to true tries to keep the <messageId> markup in lines shorter than 72 characters.

Specified by:

setBreakLongMessageIdLine in interface I_AdminSmtpClient

Parameters:

breakLongMessageIdLine - The breakLongMessageIdLine to set.

getSmtpIoTimeout

public int getSmtpIoTimeout()

Description copied from interface: I_AdminSmtpClient

mail.smtp.timeout Socket I/O timeout value in milliseconds. Default is infinite timeout.

Specified by:

getSmtpIoTimeout in interface I_AdminSmtpClient

getSmtpConnectionTimeout

public int getSmtpConnectionTimeout()

Description copied from interface: I_AdminSmtpClient

mail.smtp.connectiontimeout Socket connection timeout value in milliseconds. Default is infinite timeout.

Specified by:

getSmtpConnectionTimeout in interface I_AdminSmtpClient

getAsyncSendQueueSizeMax

public int getAsyncSendQueueSizeMax()

Specified by:

getAsyncSendQueueSizeMax in interface I_AdminSmtpClient

Returns:

the asyncSendQueueSizeMax

isAsyncSendQueueBlockOnOverflow

public boolean isAsyncSendQueueBlockOnOverflow()

Specified by:

isAsyncSendQueueBlockOnOverflow in interface I_AdminSmtpClient

Returns:

the asyncSendQueueBlockOnOverflow

setAsyncSendQueueBlockOnOverflow

public void setAsyncSendQueueBlockOnOverflow(boolean asyncSendQueueBlockOnOverflow)

Specified by:

setAsyncSendQueueBlockOnOverflow in interface I_AdminSmtpClient

Parameters:

asyncSendQueueBlockOnOverflow - the asyncSendQueueBlockOnOverflow to set