XmlBlaster Logo

REQUIREMENT

protocol.email

XmlBlaster Logo


Type NEW
Priority HIGH
Status CLOSED
Topic XmlBlaster has a protocol plugin to support access via email
Des
cription

Introduction

It is possible for a client to send/receive messages to xmlBlaster via email. This way the user can publish messages or receive updates via common emails.

Our java client library supports this automatically, you can switch to email just by setting -protocol email on startup (having configured the SMTP and POP3 beforhand).
It is possible to send such messages from a normal email software like pine, outlook or thunderbird as well, but you need to now how to format the mail to have success (examples follow in this document).

In some cases it makes sense to use a client which uses the email protocol (transparently to the user) because the combination hardware, platform and implementation language does not offer a better communication alternative or for example to bypass fire walls etc.

A further usage would be to send / receive messages from a cellular phone via sms.

Even if the email protocol in its nature has sessionless characteristics, we will create a session since this protocol may be used transparently by clients written following the protocol abstraction paradigm. So before any publishing or subscription can be done, the user must connect to get a session id.

The big picture


Email overview

In the above overview you see on the left side two client variants and on the right side a server.

The pictures shows a java client which uses transparently the email protocol (instead of for example Corba) and an email client application like outlook where a human manually sends messages.

The client needs to connect with SMTP to its MTA (mail transfer agent, for example sendmail or postfix) to be able to send outgoing messages and needs to connect with POP3 to its MTA to poll for incoming mails.

The same setup applies for the xmlBlaster server.

For testing purposes all can reuse the same MTA on your localhost (or from your internet provider) or you can even have four different MTAs one for client-SMTP, client-POP3, server-SMTP and server-POP3.

To find the MTAs you need to configure the properties mail.smtp.url and mail.pop3.url. The POP3 syntax is of the form pop3://user:password@host:port/INBOX. Only 'INBOX' is supported for pop3.
For SMTP use smtp://user:password@host:port.
Finally you need to configure what is your email address.

For fine-tuning there are many more parameters available.

When the email specific configuration is done you can switch any java client to use the email protocol on the fly:

  java org.xmlBlaster.Main

  java HelloWorld3 -protocol email

Like this the HelloWorld3 client uses transparently emails for communication to the server instead of CORBA or SOCKET.

Supported formats

The message needs to be serialized to be send in an email attachment. This formatting is configurable, currently we provide two variants. First the raw XBF (XmlBlasterFormat) format which is very dense and used in the SOCKET protocol as well, second the human readable XmlScript format which is used in the XML scripting framework of xmlBlaster already:

XfbParser email attachment:
  Content-Type: "application/xmlBlaster-xbf; name=xmlBlasterMessage.xbf"
  fileName=xmlBlasterMessage.xbf


XmlScriptParser email attachment:
  Content-Type: "text/plain; name=xmlBlasterMessage.xml; charset=UTF-8"
  fileName = "xmlBlasterMessage.xml"      


Additional meta information attachment:
  Content-Type: text/plain; name=messageId.mid; charset=UTF-8
  Content-Disposition: attachment; filename=messageId.mid

The mime type mimeType="application/xmlBlaster-xbfz; name=xmlBlasterMessage.xbfz" is used for zlib compressed messages.

If you have other formatting needs you can simply add your own Parser plugin.

The format and compression of received emails is auto-detected depending on the file name extension or mime type.

Email expiry

Each email send by xmlBlaster has an expiry date set on two places. We add a header field to the email:

Expires: Thu, 15 Dec 2005 21:45:01 +0100 (CET)

and additionally we add an expires markup tag to the send messageId attachment (or subject line if configured with mail.subject), it follows the Date/Time format of ISO 8601 and is the UTC (==GMT) time (see the trailing 'Z'):

<messageId>...<expires>2005-12-15T21:44:56.296Z</expires></messageId>

The expires date value is determined by the currently configured responseTimeout, pingResponseTimeout or updateResponseTimeout (corresponding to the type of message send).

The Expires: header field is established for news groups (RFC1036) and additionally specified in RFC2156 for X.400 -> RCF822(email) gateways as an optional header. (In the preceeding document RFC1327 it was named Expiry-Date:)

It is up to the used mail agent (MTA) if you can find a way to destroy expired emails. This may be very useful if you have a high ping frequency configured and the xmlBlaster client or xmlBlaster server is offline. The ping emails will fill up your mail box until the counter part comes online again.

If an expired email arrives at the destination, xmlBlaster throws it away.

You can prevent sending expire information by setting useEmailExpiryTimestamp=false

Example
Java

To get you going quickly we provide a step by step example:

  1. Setup a mail transfer agent (MTA) or use an existing on your network
  2. Setup your preferred email application GUI to reach the MTA
  3. Configure xmlBlaster and start it
  4. Use your email application to send messages to xmlBlaster

Setup a POP3 and SMTP mail transfer agent (MTA)

The fastest way for a test environment is to use the James MTA http://james.apache.org. Here are the steps for a running test environment (runs fine on Windows, Unix and Linux):

Download james, unpack it and start it:

tar xzvf /opt/download/james-2.2.0.tar.gz
cd james-2.2.0/bin
# Change to be 'root' to have access to ports 25 (SMTP) and 110 (POP3)
./run.sh

Configure some users, here we use xmlBlaster for the server and demo for the client:

telnet localhost 4555

# Login as 'root' with password 'root'

# Add users demo and xmlBlaster:
adduser xmlBlaster xmlBlaster
 User xmlBlaster added

adduser demo demo
 User demo added

listusers
 Existing accounts 2
 user: demo
 user: xmlBlaster

quit

Now our MTA is ready for testing.

Hint: On UNIX and Linux you can avoid starting james as root.

Just change the ports to be above 1000, you could change the SMTP port from 25 -> 8025 and the POP3 port from 110 -> 8110.
Edit james-2.2.0/apps/james-plus/SAR-INF/config.xml to do this and remove the nntp service. Additionally add those ports to xmlBlasterPlugins.xml and xmlBlaster.properties, here is an example for SMTP smtp://xmlBlaster:xmlBlaster@localhost:8025 and for POP3 pop3://xmlBlaster:xmlBlaster@localhost:8110/INBOX

Simple command line example to test your MTA

To test access to your MTA you can invoke our SMTP and POP3 implementation standalone on the command line. This can be usefull to test if your connection URL (user name, password etc) is correct:

1. Start a command line poller for user 'xmlBlaster':

java -Dmail.pop3.url=pop3://xmlBlaster:xmlBlaster@localhost:110/INBOX org.xmlBlaster.util.protocol.email.Pop3Driver -receivePolling true

2. Send from command line an email:

java -Dmail.smtp.url=smtp://xmlBlaster:xmlBlaster@localhost:25 org.xmlBlaster.util.protocol.email.SmtpClient -from xmlBlaster@localhost -to xmlBlaster@localhost

For debugging, check in directory james-2.2.0/apps/james/var/mail/inboxes/xmlBlaster for any pending and not yet delivered emails.

Sending mails manually from your email client (outlook, thunderbird etc.)

After having a configured james MTA you can play with your email client software (outlook, thunderbird etc.) and send manually emails to xmlBlaster.

The first step is to setup the server side configuration:

xmlBlasterPlugins.xml:
   <!-- General EMAIL SMTP client service -->
   <!-- needed by 'email' plugin and 'CbProtocolPlugin[email][1.0]' plugin -->
   <plugin id='smtp' className='org.xmlBlaster.util.protocol.email.SmtpClient'>
      <action do='LOAD' onStartupRunlevel='4' sequence='7' 
              onFail='resource.configuration.pluginFailed'/>
      <action do='STOP' onShutdownRunlevel='4' sequence='9'/>   
      <attribute id='mail.smtp.url'>smtp://xmlBlaster:xmlBlaster@localhost:25</attribute>
   </plugin>

   <!-- General EMAIL POP3 polling service -->
   <!-- needed by 'email' plugin and 'CbProtocolPlugin[email][1.0]' plugin -->
   <plugin id='pop3' className='org.xmlBlaster.util.protocol.email.Pop3Driver'>
      <action do='LOAD' onStartupRunlevel='4' sequence='9' 
              onFail='resource.configuration.pluginFailed'/>
      <action do='STOP' onShutdownRunlevel='4' sequence='7'/>   
      <attribute id='mail.pop3.url'>pop3://xmlBlaster:xmlBlaster@localhost:110/INBOX</attribute>
      <attribute id='pop3PollingInterval'>500</attribute>
   </plugin>

   <!-- EMAIL protocol driver (please activate 'pop3' and 'smtp' service at an earlier runlevel) -->
   <plugin id='email' className='org.xmlBlaster.protocol.email.EmailDriver'>
      <action do='LOAD' onStartupRunlevel='7' sequence='10' 
              onFail='resource.configuration.pluginFailed'/>
      <action do='STOP' onShutdownRunlevel='7' sequence='10'/>
      <attribute id='mail.smtp.from'>xmlBlaster@localhost</attribute>   
      <attribute id='compress/type'>zlib</attribute>
      <attribute id='compress/minSize'>2000</attribute>
      <attribute id='parserClass'>org.xmlBlaster.util.xbformat.XmlScriptParser</attribute>
      <attribute id='mail.subject'>XmlBlaster generated mail</attribute>
   </plugin>
xmlBlaster.properties:
CbProtocolPlugin[email][1.0]=org.xmlBlaster.protocol.email.CallbackEmailDriver,\
                             mail.smtp.from=xmlBlaster@localhost,\
                             parserClass=org.xmlBlaster.util.xbformat.XmlScriptParser
Start xmlBlaster:

java -Dcom.sun.management.jmxremote org.xmlBlaster.Main -cluster.node.id heron

Now we are ready to send an XmlScript to xmlBlaster, the following sequence shows a connect, two publishes, one subscribe and a disconnect. Please take it with your mouse and paste it into your email application window. Use as TO: destination xmlBlaster@localhost, you can leave the SUBJECT: empty.

Note: If using james configured as described above you need to setup your email GUI application with a new account demo with password demo. Setup the outgoing SMTP to the above james localhost:25 and configure to poll on james for incoming mails with POP3 on localhost:110. Take care to send the email as plain text only (not with HTML markup!).

<xmlBlaster>
  <connect>
    <qos>
      <securityService type="htpasswd" version="1.0">
        <user>tester</user>
        <passwd>tester</passwd>
      </securityService>
      <session name='emailTester/1' timeout='-1'/>
      <queue relating='connection'>
         <address type="email" />
      </queue>
      <queue relating='callback' maxEntries='5' maxEntriesCache='2'>
         <callback type="email" pingInterval='0' retries='-1'>
           demo@localhost
         </callback>
      </queue>
    </qos>
 </connect>

 <publish>
   <key oid="Hello"><airport /></key>
   <content>Hi world</content>
 </publish>

 <publish>
   <key oid="Hello"/>
   <content>Hi again</content>
 </publish>

 <subscribe>
   <key oid="__sys__Login"></key>
   <qos><updateOneway>true</updateOneway></qos>
 </subscribe>

 <disconnect/>
</xmlBlaster>

Usually you need to take the private session id from the returned ConnectReturnQos email and use it for further communication (like 'sessionId:127.0.0.2-null-1134492824506--1769759418-3'). As we do all communication in one mail and disconnect at the end we don't need to bother about this.
We have set pingInterval='0' to not receive unwanted pings, and set retries='-1' so that the server never deletes us until our disconnect arrives. Further we have set with timeout='-1' the session expiry to unlimited.

See our above subscribe(). Note that we have set updateOneway=true otherwise we would need to acknowledge each received update message.

This screen dump shows the setup just before sending with mozilla/thunderbird, the subject line is ignored:


Sending messages with thunderbird

As a response you will receive multiple of emails, one acknowledge for each request and one update() message for the subscribe, this screen dump shows the received update() only:


Receiving update with thunderbird

Sending requests in separate emails

You can send the above connect() in a single first email.


Sending messages with thunderbird

You will receive an email with the ConnectReturnQos in the email-body and your secret sessionId in the email-subject. Just press your reply button to keep the subject and send the next publish() request email. The publish is authenticated by the secret sessionId in the subject.


Sending messages with thunderbird

Limitation

Each email needs a unique and ascending requestId. As we haven't supplied one in our above examples the sent-date of the email header is chosen as a fallback. As this date is based on seconds you may manually not send more than one email per second.

You can send such a requestId in the subject as well, but now you have to take care yourself to increment it manually for each follow up email:
<messageId> <sessionId>sessionId:127.0.0.2-null-1134491480448--1073813090-3</sessionId> <requestId>1136486974900000000</requestId> <methodName>subscribe</methodName> <expires>2005-12-13T19:17:53.148Z</expires> </messageId>

If you use our embedded java client protocol plugin for email this limitation does not exist, here we correctly send a unique and ascending timestamp.

Additional note: Optionally you can send an expire date, when this is elapsed the email is discarded by the xmlBlaster server.

Example
Java

Example of the email structure

This example shows the structure of an email transporting xmlBlaster messages:

<message>
  <from>demo@localhost</from>
  <to>xmlBlaster@localhost</to>
  <subject>XmlBlaster Generated Email</subject>
  <content>javax.mail.internet.MimeMultipart@16614e7</content>

  <attachment>
    <filename>xmlBlasterMessage.xml</filename>
    <contenttype>text/plain; name=xmlBlasterMessage.xml; charset=UTF-8</contenttype>
    <content>
      <ping sessionId='unknown' requestId='1' type='I'/>
    </content>
  </attachment>

  <attachment>
    <filename>messageId.mid</filename>
    <contenttype>text/plain; name=messageId.mid; charset=UTF-8</contenttype>
    <content>&lt;messageId>&lt;sessionId>1132061265263000000&lt;/sessionId>
                &lt;requestId>1132965149890000000&lt;/requestId>
                &lt;methodName>ping&lt;/methodName>&lt;/messageId>
    </content>
  </attachment>
</message>

The raw email content looks more like this

Return-Path: <demo@localhost>
Received: from localhost ([127.0.0.1])
          by linux (JAMES SMTP Server 2.2.0) with SMTP ID 248
          for <xmlBlaster@localhost>;
          Thu, 17 Nov 2005 16:45:12 +0100 (CET)
Message-ID: <5683514.1132242312629.JavaMail.root@linux>
Date: Thu, 17 Nov 2005 16:45:12 +0100 (CET)
From: demo@localhost
To: xmlBlaster@localhost
Subject: XmlBlaster Generated Email
MIME-Version: 1.0
Content-Type: multipart/mixed; 
   boundary="----=_Part_3_23776721.1132242312553"
Expires: Fri, 27 Jan 2006 13:01:17 +0100 (CET)
Delivered-To: xmlBlaster@localhost

------=_Part_3_23776721.1132242312553
Content-Type: text/plain; name=xmlBlasterMessage.xml; charset=UTF-8
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename=xmlBlasterMessage.xml


<update sessionId='unknown' requestId='5' type='R'>
 <qos><state id='OK'/></qos>
</update>

------=_Part_3_23776721.1132242312553
Content-Type: text/plain; name=messageId.mid; charset=UTF-8
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename=messageId.mid

<messageId><sessionId>xmlblast</sessionId><requestId>5</requestId><methodName>update</methodName></messageId>
------=_Part_3_23776721.1132242312553--
Configure

Debugging

-logging/org.xmlBlaster.util.protocol.email.Pop3Driver FINEST
-logging/org.xmlBlaster.util.protocol.email.SmtpClient FINEST
-logging/org.xmlBlaster.util.protocol.email.EmailExecutor FINEST

Example configuration server side

The email driver plugin listening on incoming emails is configured in xmlBlasterPlugins.xml (for example listening on connect(), subscribe() and publish() requests)

   <!-- General EMAIL SMTP client service -->
   <!-- needed by 'email' plugin and 'CbProtocolPlugin[email][1.0]' plugin -->
   <plugin id='smtp' className='org.xmlBlaster.util.protocol.email.SmtpClient'>
      <action do='LOAD' onStartupRunlevel='4' sequence='7' 
              onFail='resource.configuration.pluginFailed'/>
      <action do='STOP' onShutdownRunlevel='4' sequence='9'/>   
      <attribute id='mail.smtp.url'>smtp://xmlBlaster:xmlBlaster@localhost</attribute>
   </plugin>

   <!-- General EMAIL POP3 polling service -->
   <!-- needed by 'email' plugin and 'CbProtocolPlugin[email][1.0]' plugin -->
   <plugin id='pop3' className='org.xmlBlaster.util.protocol.email.Pop3Driver'>
      <action do='LOAD' onStartupRunlevel='4' sequence='9' 
              onFail='resource.configuration.pluginFailed'/>
      <action do='STOP' onShutdownRunlevel='4' sequence='7'/>   
      <attribute id='mail.pop3.url'>pop3://xmlBlaster:xmlBlaster@localhost:110/INBOX</attribute>
      <attribute id='pop3PollingInterval'>500</attribute>
   </plugin>

   <!-- EMAIL protocol driver (please activate 'pop3' and 'smtp' service at an earlier runlevel) -->
   <plugin id='email' className='org.xmlBlaster.protocol.email.EmailDriver'>
      <action do='LOAD' onStartupRunlevel='7' sequence='10' 
              onFail='resource.configuration.pluginFailed'/>
      <action do='STOP' onShutdownRunlevel='7' sequence='10'/>
      <attribute id='mail.smtp.from'>xmlBlaster@localhost</attribute>   
      <attribute id='compress/type'>zlib</attribute>
      <attribute id='compress/minSize'>200</attribute>
      <attribute id='parserClass'>org.xmlBlaster.util.xbformat.XbfParser</attribute>
      <attribute id='mail.subject'>XmlBlaster generated mail</attribute>
   </plugin>

The format of the returned messages from the xmlBlaster server to email clients is configured in xmlBlaster.properties (for example PublishReturnQos, Update messages, ConnectReturnQos etc.)

CbProtocolPlugin[email][1.0]=org.xmlBlaster.protocol.email.CallbackEmailDriver,\
                             mail.user=xmlBlaster,\
                             mail.password=xmlBlaster,\
                             compress/type=zlib,\
                             compress/minSize=200,\
                             mail.subject=Server generated email,\
                             parserClass=org.xmlBlaster.util.xbformat.XbfParser
#                             parserClass=org.xmlBlaster.util.xbformat.XmlScriptParser

#plugin/email/responseTimeout=300000
#plugin/email/pingResponseTimeout=60000
#plugin/email/updateResponseTimeout=30000000

The format of the message in the email is defined by our XbfParser (see protocl.socket requirement), additionally messages bigger 200 bytes are compressed with zlib. Optionally you can choose to send the message in clear text XML markup by using our XmlScriptParser instead of XbfParser.

Example configuration for an email client

The format of send messages from the client to the xmlBlaster server or to listen on server messages is configured in xmlBlaster.properties (for example sending publish() or receiving update() etc.)

ClientProtocolPlugin[email][1.0]=org.xmlBlaster.client.protocol.email.EmailConnection,\
                                 mail.smtp.url=smtp://demo:demo@localhost,\
                                 mail.smtp.from=demo@localhost,\
                                 mail.pop3.url=pop3://demo:demo@localhost/INBOX,\
				 mail.smtp.to=xmlBlaster@localhost,\
                                 pop3PollingInterval=500,\
                                 holdbackExpireTimeout=20000,\
                                 compress/type=zlib,\
                                 compress/minSize=200,\
                                 parserClass=org.xmlBlaster.util.xbformat.XmlScriptParser
# parserClass=org.xmlBlaster.util.xbformat.XbfParser

# Register the client side callback server plugin (to listen on update() or publishReturnQos)
ClientCbServerProtocolPlugin[email][1.0]=
         org.xmlBlaster.client.protocol.email.EmailCallbackImpl,\
         mail.smtp.url=smtp://demo:demo@localhost,\
         mail.smtp.from=demo@localhost,\
         mail.pop3.url=pop3://demo:demo@localhost/INBOX,\
         pop3PollingInterval=500,\
         holdbackExpireTimeout=20000,\
         compress/type=zlib,\
         compress/minSize=200,\
         messageIdForceBase64=false,\
         contentForceBase64=false,\
         parserClass=org.xmlBlaster.util.xbformat.XbfParser
#schemaDeclaration=xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation='mySchema.xsd',\
#xmlDeclaration=<?xml version='1.0' encoding='UTF-8'?>,\
#mail.subject=Generated email,\
#sendResponseSessionId=false,\
#sendResponseRequestId=false,\
#sendSimpleExceptionFormat=true,\
#parserClass=org.xmlBlaster.util.xbformat.XmlScriptParser

The above client has chosen to not compress the outgoing mails. Further it sends the UpdateReturnQos in clear XML text instead of using our native XfbParser protocol.

Configuration of SmtpClient.java

This plugin is responsible to send away emails with SMTP, it is used on server side and on java client side.

Note that you can set additionally any system property which is supported by javax.mail, as for example:

java -Dmail.smtp.connectiontimeout=10000 -Dmail.smtp.timeout=10000 ...

Click here for a complete list of javax.mail properties.

Property Default / Example Description Impl
mail.smtp.url smtp://user:password@host:port The SMTP connection URL, the port is optional. For example "smtp://demo:demo@localhost:25". If you leave the password away we try to connect to the MTA (mail transfer agent) with switched off authentication. If the username or password contains a '@' character it usually should be escaped by a '%40'. For easier usage we do this automatically for you. Other special characters like '%' are not handled by xmlBlaster and you need to url encode it yourself, in this case write '%25' instead (the hex 25 from the ASCII chart). yes
mail.smtp.to xmlBlaster@localhost The Address to which the server we want to contact is listening to. yes
messageIdForceBase64 false If the messageId markup contains illegal characters it is automatically base64 encoded. By setting this to true you can enforce everything to base64, even it is not necessary. yes
contentForceBase64 false If the email payload (the message content) contains illegal characters it is automatically base64 encoded, typically this happens for binary data like gif images. By setting this to true you can enforce every content email attachment to base64, even it is not necessary. yes
inlineExtension .txt,.xml A comma separated list of attachment file name extensions which should be handled as inline. Such attachments are readable in your email body in your GUI (outlook,thunderbird) so you are not forced to open the attachment to see it. yes
asyncSendQueueSizeMax 100 Mails can be marked to be send asynchronously from a separate thread decoupled with a producer/consumer queue. This decouples the sending code from the delivery to the SMTP server.
If the SMTP server hangs or blocks the sending code can continue. Note that the queue is RAM based only.
If the queue overflows the email-message is dumped to the log file and is lost. This behaviour on overflow can be changed by setting asyncSendQueueBlockOnOverflow=true.
An email-message must be marked to be send asynchronously by setting emailData.setSendAsync(true).
yes
mail.debug false Switches on/off the javamail lowlevel debugging. Use as JVM setting like 'java -Dmail.debug=true ...'.
Further debugging can be switch on with logging/org.xmlBlaster.util.protocol.email.SmtpClient FINEST
yes

Configuration of Pop3Driver.java

This plugin is responsible to poll for incoming emails with POP3, it is used on server side and on java client side.

Property Default / Example Description Impl
mail.pop3.url pop3://user:password@host:port/INBOX The POP3 connection URL, the port is optional. For example "pop3://demo:demo@localhost:110/INBOX". If you leave the password away we try to connect to the MTA (mail transfer agent) with switched off authentication. yes
pop3PollingInterval 500 The polling interval in milli seconds to poll for incoming messages. Defaults to 2000 (2 seconds) but reducing it to 500 milli seconds shouldn't eat too much CPU time. yes
holdbackExpireTimeout 20000 How many mill seconds do we keep emails for which no java bean is interested. This is solving the chicken/egg problem on xmlBlaster startup when the Pop3Poller is retrieving already emails but the email drivers are not yet ready. yes
activate true If true the driver start polling for emails on startup immediately. If set to false you need to somehow activate the poller, for example manually using the JMX console. yes
mail.debug false Switches on/off the javamail lowlevel debugging. Use as JVM setting like 'java -Dmail.debug=true ...'.
Further debugging can be switch on with logging/org.xmlBlaster.util.protocol.email.Pop3Driver] FINEST and logging/org.xmlBlaster.util.protocol.email.EmailExecutor] FINEST
yes

Other general configurations

Property Default / Example Description Impl
parserClass org.xmlBlaster.util.xbformat.XmlScriptParser Specifies how to format the message inside the email: The XmlScriptParser use the simple XML markup of the client.script framework where as the org.xmlBlaster.util.xbformat.XbfParser uses the more dense format of our protocol.socket framework. yes
compress/type zlib If you want to compress the attachment set this property to zlib. It defaults to '', that is no compression is used. yes
compress/minSize 200 If compress/type is set to zlib you can control the minimum size in bytes to switch on compression. For too small messages compression makes no sense as it would increase the size. yes
useEmailExpiryTimestamp true Adds email header of type Expires: Fri, 27 Jan 2006 13:01:17 +0100 (CET). If you have an intelligent MTA you can configure it to drop the mail if expired. The xmlBlaster library will discard expired mails if such arrives. yes
mail.subject XmlBlaster Generated Email $_{xmlBlaster/email/messageId} The subject to use. If your subject line contains a $_{xmlBlaster/email/messageId} token, a complete <messageId> markup is added to the subject by xmlBlaster. yes
xmlDeclaration <?xml version='1.0' encoding='UTF-8'?> The header to add to the attachment if formatted with XmlScriptParser. yes
schemaDeclaration xmlns:xsi= 'http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation= 'mySchema.xsd' This allows to add a schema declaration to the XmlScriptParser. The attachment root tag is complemented with the given string. yes
pingResponseTimeout 60000 When the ping() method is invoked we wait the given time [milli-seconds] on a response, the value must be bigger than zero, it defaults to one minute.
The response is the return value or an exception for method invocations which are not marked oneway.
On timeout an exception is thrown which leads on server side to a dead message (depending on the installed error handler).
yes
forceReadable false Allows to send the content of the data embedded in a CDATA instead of using BASE64. Note that if you choose to set this flag to true, then it is your responsability to avoid Encoding Problems. yes

Other configurations server side only

Property Default / Example Description Impl
CbProtocolPlugin[email][1.0]
org.xmlBlaster.protocol.email.CallbackEmailDriver
You need to activate EMAIL support in your xmlBlaster.properties file yes
mail.smtp.from xmlBlaster@localhost The email address used by the xmlBlaster server. yes
updateResponseTimeout 86400000 When the update() callback method is invoked we wait the given time [milli-seconds] on a response, the value must be bigger than zero, use Integer.MAX_VALUE for an unlimited setting, the default is to wait for one day.
The response is the return value or an exception for method invocations which are not marked oneway.
On timeout an exception is thrown which leads on server side to a dead message (depending on the installed error handler).
yes

Other configurations client side only

Property Default / Example Description Impl
ProtocolPlugin[email][1.0]
org.xmlBlaster.protocol.email.EmailDriver
You need to activate EMAIL support in your xmlBlaster.properties file yes
CbProtocolPlugin[email][1.0]
org.xmlBlaster.protocol.email.CallbackEmailDriver
You need to activate EMAIL support in your xmlBlaster.properties file yes
responseTimeout 86400000 When methods like connect(), publish, subscribe etc. is invoked we wait the given time [milli-seconds] on a response, the value must be bigger than zero, use Integer.MAX_VALUE for an unlimited setting, the default is to wait for one day.
The response is the return value or an exception for method invocations which are not marked oneway.
On timeout an exception is thrown which is forwarded to your client code.
yes
sendResponseSessionId true Add the sessionId="..." xml-attribute to the XmlScript markup? For example <update sessionId='fgg694' .... yes
sendResponseRequestId true Add the requestId="..." xml-attribute to the XmlScript markup? For example <update requestId='17743005' .... yes
sendSimpleExceptionFormat false If set to true and used with XmlScriptParser the UpdateReturnQos has a simple format (even for exceptions) which satisfies the XML-schema simpleReturnQos.xsd. yes

Note: You can easily re-configure the POP3 and SMTP behavior on a running xmlBlaster with JMX

Note: The current email callback implementation can handle max one connection per email account (like 'joe' on the POP3 server) if you don't supply a positive sessionId

NOTE: Configuration parameters are specified on command line (-someValue 17) or in the xmlBlaster.properties file (someValue=17). See requirement "util.property" for details.
Columns named Impl tells you if the feature is implemented.
Columns named Hot tells you if the configuration is changeable in hot operation.

Todo
  1. Make last requestId persistent to have loop and sequence protection after a restart
  2. Currently you can't publish from within an update (will dead lock)
See REQ protocol
See REQ admin.events
See API org.xmlBlaster.util.protocol.email.Pop3Driver
See API org.xmlBlaster.util.protocol.email.SmtpClient
See API org.xmlBlaster.protocol.email.EmailDriver
See API org.xmlBlaster.util.xbformat.XbfParser
See API org.xmlBlaster.util.xbformat.XmlScriptParser
See Javamail API

This page is generated from the requirement XML file xmlBlaster/doc/requirements/protocol.email.xml

Back to overview