神马文学网xmlBlaster - Requirement protocol.email
来源：百度文库 编辑：神马文学网 时间：2024/04/27 23:55:58
REQUIREMENT
protocol.email
Type NEW
Priority HIGH
Status CLOSED
XmlBlaster has a protocol plugin to support access via email
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
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‘):
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
To get you going quickly we provide a step by step example:
Setup a mail transfer agent (MTA) or use an existing on your network Setup your preferred email application GUI to reach the MTA Configure xmlBlaster and start it 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:
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!).
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:
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.
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:
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 of the email structure
This example shows the structure of an email transporting xmlBlaster messages:
Return-Path:
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)
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, 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=, #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.
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).
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.
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.
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.
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
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.
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.
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.
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.
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
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 theclient.script framework where as the org.xmlBlaster.util.xbformat.XbfParser uses the more dense format of ourprotocol.socket framework.
compress/type zlib If you want to compress the attachment set this property to zlib. It defaults to ‘‘, that is no compression is used.
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.
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.
mail.subject XmlBlaster Generated Email $_{xmlBlaster/email/messageId} The subject to use. If your subject line contains a $_{xmlBlaster/email/messageId} token, a complete
xmlDeclaration The header to add to the attachment if formatted with XmlScriptParser.
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.
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).
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
mail.smtp.from xmlBlaster@localhost The email address used by the xmlBlaster server.
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).
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
CbProtocolPlugin[email][1.0] org.xmlBlaster.protocol.email.CallbackEmailDriver You need to activate EMAIL support in your xmlBlaster.properties file
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.
sendResponseSessionId true Add the sessionId="..." xml-attribute to the XmlScript markup? For example
sendResponseRequestId true Add the requestId="..." xml-attribute to the XmlScript markup? For example
sendSimpleExceptionFormat false If set to true and used with XmlScriptParser the UpdateReturnQos has a simple format (even for exceptions) which satisfies the XML-schemasimpleReturnQos.xsd.
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.
Make last requestId persistent to have loop and sequence protection after a restart Currently you can‘t publish from within an update (will dead lock)
protocol
admin.events
org.xmlBlaster.util.protocol.email.Pop3Driver
org.xmlBlaster.util.protocol.email.SmtpClient
org.xmlBlaster.protocol.email.EmailDriver
org.xmlBlaster.util.xbformat.XbfParser
org.xmlBlaster.util.xbformat.XmlScriptParser
This page is generated from the requirement XML file xmlBlaster/doc/requirements/protocol.email.xml
Back to overview
_xyz
xmlBlaster - Requirement protocol.email
email
Protocol Overhead
memcached protocol
情人节Email
Network Time Protocol
Simplified Arabidopsis Transformation Protocol
Arabidopsis RNA extraction protocol
Protocol的检索方法
The Bayeux Protocol
Protocol Packet Design Pattern
Protocol Layer Design Pattern
Protocol Stack Design Pattern
Real Time Streaming Protocol
TUIO Protocol Specification 1.1
Transmission Control Protocol - Wikipedia, th...
Transmit Protocol Handler Design Pattern
Receive Protocol Handler Design Pattern
BS and MS requirement on SINR and noise level
Zimbra Web2.0 email
Email可视化项目
Fuser：Email整合工具
Email前途堪忧?
Email以前的故事