REQUIREMENT
protocol.email
|
|
REQUIREMENT protocol.email |
|
| 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
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 
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 The client needs to connect with SMTP to its MTA (mail transfer agent, for example The same setup applies for the xmlBlaster server. For testing purposes all can reuse the same MTA on your To find the MTAs you need to configure the properties 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 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 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 <messageId>...<expires>2005-12-15T21:44:56.296Z</expires></messageId> The expires date value is determined
by the currently configured The 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 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Example Java |
To get you going quickly we provide a step by step example:
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 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. 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 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 Note: If using james configured as described above you need to setup
your email GUI application with a new account
<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. See our above subscribe(). Note that we have set This screen dump shows the setup just before sending with mozilla/thunderbird, the subject line is ignored: 
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: 
Sending requests in separate emails You can send the above connect() in a single first email. 
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. 
LimitationEach email needs a unique and ascending You can send such a If you use our embedded java client protocol plugin for 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><messageId><sessionId>1132061265263000000</sessionId>
<requestId>1132965149890000000</requestId>
<methodName>ping</methodName></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 sideThe email driver plugin listening on incoming emails is configured in
<!-- 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
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 clientThe format of send messages from the client to the xmlBlaster server
or to listen on server messages
is configured in
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.
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.
Other general configurations
Other configurations server side only
Other configurations client side only
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. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Todo |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
