You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ch...@apache.org on 2006/04/27 09:11:48 UTC
svn commit: r397457 -
/webservices/axis2/trunk/java/xdocs/latest/mail-transport.html
Author: chatra
Date: Thu Apr 27 00:11:47 2006
New Revision: 397457
URL: http://svn.apache.org/viewcvs?rev=397457&view=rev
Log:
did an upgrade on the document
Modified:
webservices/axis2/trunk/java/xdocs/latest/mail-transport.html
Modified: webservices/axis2/trunk/java/xdocs/latest/mail-transport.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/mail-transport.html?rev=397457&r1=397456&r2=397457&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/mail-transport.html (original)
+++ webservices/axis2/trunk/java/xdocs/latest/mail-transport.html Thu Apr 27 00:11:47 2006
@@ -1,279 +1,284 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-<head>
- <meta http-equiv="content-type" content="">
- <title>Invoking a service using a mail</title>
-</head>
-
-<body>
-<h1>Invoking a service using a mail</h1>
-
-<h2>Prologue</h2>
-
-<p>Most of Web services that we interact with are synchronous and
-request-response in nature. However, we see that the synchronous
-request-response type of interaction is only a part of the messaging
-scenarios we encounter in real life. Asynchronous messaging is very important
-in constructing loosely coupled systems. Take for instance a chain of stores,
-at the end of the day all the stores all over can send a mail to the central
-system telling it what that days business activity was and in the morning
-when the store opens there will be a reply to that mail with new instructions
-and updates. It is a lot like the way the old business worked but with a
-modern touch. Similarly Axis2 mail transport can be used to implement
-SETI@HOME through mail.</p>
-
-<h2>Introduction</h2>
-
-<p>To start you will first need to go through the Mail Transport <a
-href="mail-configuration.html">configuration document</a>. It will give you
-all the information you need on how to configure Axis2 to get mail transport
-working.</p>
-
-<p>Broadly speaking there are 3 ways of calling a service through mail.</p>
-
-<blockquote>
- 1. Using the simple mail server included in Axis2.<br/>
- 2. Using a generic mail server.<br/>
- 3. Using mailets.<br/>
-</blockquote>
-
-<p></p>
-
-<p>Option number 1 and 2 are fairly simple and easy to implement, whereas
-option 3 is somewhat harder.The mailet scenario however does provide a more
-robust and useful solution in a production environment.</p>
-
-<p>If you are not a guru in mail related issues you should probably get
-started on the simple mail server that has been provided with Axis2. Once you
-get the hang of the Axis2 related issues then you can move on to tackle the
-mail beast. Please do keep in mind that the mail server we have implemented
-is ONLY FOR DEMONSTRATION/TESTING PURPOSES.</p>
-
-<h3>1. Using the simple mail server included in Axis2</h3>
-
-<p>The SMTP/POP server that we have included has the ability to function as a
-standalone SMTP/POP server and also has the ability to work as a mailet. All
-this is done through a small filter that keeps watch for certain
-pre-configured email addresses. These pre-configured email addresses can be
-changed by doing a simple edit of the filter class
-org.apache.axis2.transport.mail.server.Sorter.</p>
-
-<p>Now that we have the environment set up, let us start pumping out some
-code to get the mail functionality off the ground. First we'll have a look at
-it from the mail server side. <br/>
-</p>
-<source><pre> // Start the mail server using the default configurations.
- ConfigurationContext configContext = UtilsMailServer.start();
-
- // Start the default mail listener. It will starting poling for mail
- // using the configuration from the XML file.
- SimpleMailListener ml = new SimpleMailListener();
- ml.init(configContext, configContext.getAxisConfiguration()
- .getTransportIn(new QName(Constants.TRANSPORT_MAIL)));
- ml.start();
-
- // Setup a service that will echo what we send to the server.
- AxisService axisService = Utils.createSimpleService(serviceName,
- Echo.class.getName(), new QName("echoOMElement"));
- configContext.getAxisConfiguration().addService(axisService);
- Utils.resolvePhases(configContext.getAxisConfiguration(), axisService);
- ServiceContext serviceContext = configContext
- .createServiceContext(new QName("EchoXMLService"));</pre>
-</source>
-<p>This code sets up your Axis2 server working through mail, with a single
-service. If you need to have a look under the hood check out the MailServer
-and UtilsMailServer classes.</p>
-
-<p>Moving onto the client side have a look at the code listing below. It will
-call the axisService that was setup on the previous code listing.</p>
-<source><pre> ConfigurationContext configContext = UtilsMailServer
- .createClientConfigurationContext();
- AxisService axisService = new AxisService(serviceName);
- AxisOperation axisOperation = new AxisOperation(operationName);
- axisOperation.setMessageReceiver(new MessageReceiver() {
- public void receive(MessageContext messgeCtx) throws AxisFault {
- envelope = messgeCtx.getEnvelope();
- }
- });
- axisService.addOperation(axisOperation);
- configContext.getAxisConfiguration().addService(axisService);
- Utils.resolvePhases(configContext.getAxisConfiguration(), axisService);
- ServiceContext serviceContext = configContext
- .createServiceContext(serviceName);
-
- Options options = new Options();
- options.setTo(targetEPR);
- options.setTransportInProtocol(Constants.TRANSPORT_MAIL);
- options.setUseSeparateListener(true);
- // Create a callback to set to the axisService invocation.
- Callback callback = new Callback() {
- public void onComplete(AsyncResult result) {
- try {
- result.getResponseEnvelope().serialize(
- XMLOutputFactory.newInstance()
- .createXMLStreamWriter(System.out));
- } catch (XMLStreamException e) {
- reportError(e);
- } finally {
- finish = true;
- }
- }
- public void reportError(Exception e) {
- log.info(e.getMessage());
- finish = true;
- }
- };
-
- ServiceClient sender = new ServiceClient(configContext, axisService);
- sender.setOptions(options);
- options.setTo(targetEPR);
- // Call the service and start poling for the reply from the server.
- sender.sendReceiveNonBlocking(operationName.getLocalPart(), createEnvelope(), callback);
-
- int index = 0;
- while (!finish) {
- Thread.sleep(1000);
- index++;
- if (index > 10) {
- throw new AxisFault(
- "Server is being shutdown as the Async response is taking too long.");
- }
- }
-</pre>
-</source>
-<p>This will call the service that was setup on the server and will poll the
-mail server till the response is received.Thats all there is to it. Please do note that
-serviceName and operationName need to be QNames.
-</p>
-
-<p></p>
-
-<h3>2. Using a generic mail server</h3>
-
-<p>First you need two email accounts that works with POP/SMTP. One will act
-as a server and the other will act as the client. For the time being we will
-use server@somewhere.org and client@somewhere.org as the server and the
-client email addresses. Now that we have the email addresses you will have to
-set up the client and the server with Mail Transport <a
-href="http://ws.apache.org/axis2/mail-transport.html">introduction
-document</a>.</p>
-
-<p>When calling the generic mail server the client side code will remain the
-same and there will be some modification to the server-side code.</p>
-
-<p></p>
-<source><pre> // Create a configuration context. This will also load the details about the mail
- // address to listen to from the configuration file.
- File file = new File(MAIL_TRANSPORT_SERVER_ENABLED_REPO_PATH);
- ConfigurationContextFactory builder = new ConfigurationContextFactory();
- ConfigurationContext configContextbuilder
- .buildConfigurationContext(file.getAbsolutePath());
-
- // Startup the default mail server and start listening to a
- // mail address.
- SimpleMailListener ml = new SimpleMailListener();
- ml.init(configContext, configContext.getAxisConfiguration()
- .getTransportIn(new QName(Constants.TRANSPORT_MAIL)));
- ml.start();
-
- // Setup a simple service.
- AxisService axisService = Utils.createSimpleService(serviceName,
- Echo.class.getName(), operationName);
- configContext.getAxisConfiguration().addService(axisService);
- Utils.resolvePhases(configContext.getAxisConfiguration(), axisService);
- ServiceContext serviceContext = configContext.createServiceContext(serviceName);</pre>
-</source>
-<p>Note that a separate ConfigurationContext needs to be created and used.</p>
-
-<h3>3. Calling Axis through a James mailet</h3>
-
-<p>This process will be a bit more challenging than the other two methods but
-will provide a really elegant way to use the mail transport. Before we get
-started you will have to go though the James documents <a
-href="http://james.apache.org/custom_matcher_2_1.html">Writing a Custom
-Matcher</a> and <a
-href="http://james.apache.org/custom_mailet_2_1.html">Writing a Custom
-Mailet</a>.</p>
-
-<p>Now that we know the James part of it lets dive into to the Axis2 part of
-the code. Once you have set up the James side of business we need to use the
-same functionality that is used in the above code. Have a look at the code
-listing below for more details</p>
-<source><pre> public void processMail(ConfigurationContext confContext, MimeMessage mimeMessage) {
- // create an Axis server
- AxisEngine engine = new AxisEngine(confContext);
- MessageContext msgContext = null;
- // create and initialize a message context
- try {
- // Create a message context with mail as in and out transports.
- msgContext =
- new MessageContext(confContext,
- confContext.getAxisConfiguration().getTransportIn(new QName(Constants.TRANSPORT_MAIL)),
- confContext.getAxisConfiguration().getTransportOut(new QName(Constants.TRANSPORT_MAIL)));
- msgContext.setServerSide(true);
-
- msgContext.setProperty(MailConstants.CONTENT_TYPE, mimeMessage.getContentType());
- msgContext.setWSAAction(getMailHeader(MailConstants.HEADER_SOAP_ACTION, mimeMessage));
-
- // The service path is in the subject of the mail.
- String serviceURL = mimeMessage.getSubject();
- if (serviceURL == null) {
- serviceURL = "";
- }
-
- String replyTo = ((InternetAddress) mimeMessage.getReplyTo()[0]).getAddress();
- if (replyTo != null) {
- msgContext.setReplyTo(new EndpointReference(replyTo));
- }
-
- String recipients = ((InternetAddress) mimeMessage.getAllRecipients()[0]).getAddress();
-
- if (recipients != null) {
- msgContext.setTo(new EndpointReference(recipients + "/" + serviceURL));
- }
-
- // add the SOAPEnvelope
- String message = mimeMessage.getContent().toString();
- ByteArrayInputStream bais = new ByteArrayInputStream(message.getBytes());
- XMLStreamReader reader = XMLInputFactory.newInstance().createXMLStreamReader(bais);
-
- // This is just in place to work with SOAP 1.1 and 1.2.
- String soapNamespaceURI = "";
- if (mimeMessage.getContentType().indexOf(SOAP12Constants.SOAP_12_CONTENT_TYPE) > -1) {
- soapNamespaceURI = SOAP12Constants.SOAP_ENVELOPE_NAMESPACE_URI;
- } else if (mimeMessage.getContentType().indexOf(SOAP11Constants.SOAP_11_CONTENT_TYPE) > -1) {
- soapNamespaceURI = SOAP11Constants.SOAP_ENVELOPE_NAMESPACE_URI;
-
- }
- StAXBuilder builder = new StAXSOAPModelBuilder(reader, soapNamespaceURI);
-
- SOAPEnvelope envelope = (SOAPEnvelope) builder.getDocumentElement();
- msgContext.setEnvelope(envelope);
- if (envelope.getBody().hasFault()) {
- engine.receiveFault(msgContext);
- } else {
- engine.receive(msgContext);
- }
- } catch (Exception e) {
- try {
- if (msgContext != null) {
- MessageContext faultContext = engine.createFaultMessageContext(msgContext, e);
- engine.sendFault(faultContext);
- }
- } catch (Exception e1) {
- log.error(e);
- }
- }
- }</pre>
-</source>
-<p>If you don't happen to have a ConfigurationContext lying around to call
-this method you can use the following bit of code to get one. Once you create
-one you can store that on the mailet and keep using it.</p>
-<source><pre> File file = new File(MAIL_TRANSPORT_SERVER_ENABLED_REPO_PATH);
- ConfigurationContextFactory builder = new ConfigurationContextFactory();
- ConfigurationContext configContextbuilder
- .buildConfigurationContext(file.getAbsolutePath());</pre>
-</source>
-<p></p>
-</body>
-</html>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Invoking a service using a mail</title>
+</head>
+
+<body>
+<h1>Invoking a Service Using a Mail</h1>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#prologue">Prologue</a></li>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#axis2">Using Simple Mail Server Included in Axis2</a></li>
+ <li><a href="#generic">Using a Generic Mail Server</a></li>
+ <li><a href="#mailet">Calling Axis Through a James Mailet</a></li>
+</ul>
+<a name="prologue"></a>
+<h2>Prologue</h2>
+
+<p>Most of Web services that we interact with are synchronous and
+request-response in nature. However, we see that the synchronous
+request-response type of interaction is only a part of the messaging
+scenarios we encounter in real life. Asynchronous messaging is very important
+in constructing loosely coupled systems. Take for instance a chain of stores,
+at the end of the day all the stores all over can send a mail to the central
+system telling it what that days business activity was and in the morning
+when the store opens there will be a reply to that mail with new instructions
+and updates. It is a lot like the way the old business worked but with a
+modern touch. Similarly Axis2 mail transport can be used to implement
+SETI@HOME through mail.</p>
+<a name="intro"></a>
+<h2>Introduction</h2>
+
+<p>To start you will first need to go through the Mail Transport <a
+href="mail-configuration.html" target="_blank">configuration document</a>. It will give you
+all the information you need on how to configure Axis2 to get mail transport
+working.</p>
+
+<p>Broadly speaking there are 3 ways of calling a service through mail.</p>
+
+<blockquote>
+ 1. Using the simple mail server included in Axis2.<br>
+ 2. Using a generic mail server.<br>
+ 3. Using mailets.<br>
+</blockquote>
+
+<p></p>
+
+<p>Option number 1 and 2 are fairly simple and easy to implement, whereas
+option 3 is somewhat harder.The mailet scenario however does provide a more
+robust and useful solution in a production environment.</p>
+
+<p>If you are not a guru in mail related issues you should probably get
+started on the simple mail server that has been provided with Axis2. Once you
+get the hang of the Axis2 related issues then you can move on to tackle the
+mail beast. Please do keep in mind that the mail server we have implemented
+is ONLY FOR DEMONSTRATION/TESTING PURPOSES.</p>
+<a name="axis2"></a>
+<h2>1. Using Simple Mail Server Included in Axis2</h2>
+
+<p>The SMTP/POP server that we have included has the ability to function as a
+standalone SMTP/POP server and also has the ability to work as a mailet. All
+this is done through a small filter that keeps watch for certain
+pre-configured email addresses. These pre-configured email addresses can be
+changed by doing a simple edit of the filter class
+org.apache.axis2.transport.mail.server.Sorter.</p>
+
+<p>Now that we have the environment set up, let us start pumping out some
+code to get the mail functionality off the ground. First we'll have a look at
+it from the mail server side. <br>
+</p>
+<source><pre> // Start the mail server using the default configurations.
+ ConfigurationContext configContext = UtilsMailServer.start();
+
+ // Start the default mail listener. It will starting poling for mail
+ // using the configuration from the XML file.
+ SimpleMailListener ml = new SimpleMailListener();
+ ml.init(configContext, configContext.getAxisConfiguration()
+ .getTransportIn(new QName(Constants.TRANSPORT_MAIL)));
+ ml.start();
+
+ // Setup a service that will echo what we send to the server.
+ AxisService axisService = Utils.createSimpleService(serviceName,
+ Echo.class.getName(), new QName("echoOMElement"));
+ configContext.getAxisConfiguration().addService(axisService);
+ Utils.resolvePhases(configContext.getAxisConfiguration(), axisService);
+ ServiceContext serviceContext = configContext
+ .createServiceContext(new QName("EchoXMLService"));</pre>
+</source>
+<p>This code sets up your Axis2 server working through mail, with a single
+service. If you need to have a look under the hood check out the MailServer
+and UtilsMailServer classes.</p>
+
+<p>Moving onto the client side have a look at the code listing below. It will
+call the axisService that was setup on the previous code listing.</p>
+<source><pre> ConfigurationContext configContext = UtilsMailServer
+ .createClientConfigurationContext();
+ AxisService axisService = new AxisService(serviceName);
+ AxisOperation axisOperation = new AxisOperation(operationName);
+ axisOperation.setMessageReceiver(new MessageReceiver() {
+ public void receive(MessageContext messgeCtx) throws AxisFault {
+ envelope = messgeCtx.getEnvelope();
+ }
+ });
+ axisService.addOperation(axisOperation);
+ configContext.getAxisConfiguration().addService(axisService);
+ Utils.resolvePhases(configContext.getAxisConfiguration(), axisService);
+ ServiceContext serviceContext = configContext
+ .createServiceContext(serviceName);
+
+ Options options = new Options();
+ options.setTo(targetEPR);
+ options.setTransportInProtocol(Constants.TRANSPORT_MAIL);
+ options.setUseSeparateListener(true);
+ // Create a callback to set to the axisService invocation.
+ Callback callback = new Callback() {
+ public void onComplete(AsyncResult result) {
+ try {
+ result.getResponseEnvelope().serialize(
+ XMLOutputFactory.newInstance()
+ .createXMLStreamWriter(System.out));
+ } catch (XMLStreamException e) {
+ reportError(e);
+ } finally {
+ finish = true;
+ }
+ }
+ public void reportError(Exception e) {
+ log.info(e.getMessage());
+ finish = true;
+ }
+ };
+
+ ServiceClient sender = new ServiceClient(configContext, axisService);
+ sender.setOptions(options);
+ options.setTo(targetEPR);
+ // Call the service and start poling for the reply from the server.
+ sender.sendReceiveNonBlocking(operationName.getLocalPart(), createEnvelope(), callback);
+
+ int index = 0;
+ while (!finish) {
+ Thread.sleep(1000);
+ index++;
+ if (index > 10) {
+ throw new AxisFault(
+ "Server is being shutdown as the Async response is taking too long.");
+ }
+ }</pre>
+</source>
+<p>This will call the service that was setup on the server and will poll the
+mail server till the response is received.Thats all there is to it. Please do
+note that serviceName and operationName need to be QNames.</p>
+<a name="generic"></a>
+<h2>2. Using a Generic Mail Server</h2>
+
+<p>First you need two email accounts that works with POP/SMTP. One will act
+as a server and the other will act as the client. For the time being we will
+use server@somewhere.org and client@somewhere.org as the server and the
+client email addresses. Now that we have the email addresses you will have to
+set up the client and the server with Mail Transport <a
+href="http://ws.apache.org/axis2/mail-transport.html" target="_blank">introduction
+document</a>.</p>
+
+<p>When calling the generic mail server the client side code will remain the
+same and there will be some modification to the server-side code.</p>
+
+<p></p>
+<source><pre> // Create a configuration context. This will also load the details about the mail
+ // address to listen to from the configuration file.
+ File file = new File(MAIL_TRANSPORT_SERVER_ENABLED_REPO_PATH);
+ ConfigurationContextFactory builder = new ConfigurationContextFactory();
+ ConfigurationContext configContextbuilder
+ .buildConfigurationContext(file.getAbsolutePath());
+
+ // Startup the default mail server and start listening to a
+ // mail address.
+ SimpleMailListener ml = new SimpleMailListener();
+ ml.init(configContext, configContext.getAxisConfiguration()
+ .getTransportIn(new QName(Constants.TRANSPORT_MAIL)));
+ ml.start();
+
+ // Setup a simple service.
+ AxisService axisService = Utils.createSimpleService(serviceName,
+ Echo.class.getName(), operationName);
+ configContext.getAxisConfiguration().addService(axisService);
+ Utils.resolvePhases(configContext.getAxisConfiguration(), axisService);
+ ServiceContext serviceContext = configContext.createServiceContext(serviceName);</pre>
+</source>
+<p>Note that a separate ConfigurationContext needs to be created and used.</p>
+<a name="mailet"></a>
+<h3>3. Calling Axis Through a James Mailet</h3>
+
+<p>This process will be a bit more challenging than the other two methods but
+will provide a really elegant way to use the mail transport. Before we get
+started you will have to go though the James documents <a
+href="http://james.apache.org/custom_matcher_2_1.html" target="_blank">Writing a Custom
+Matcher</a> and <a
+href="http://james.apache.org/custom_mailet_2_1.html" target="_blank">Writing a Custom
+Mailet</a>.</p>
+
+<p>Now that we know the James part of it lets dive into to the Axis2 part of
+the code. Once you have set up the James side of business we need to use the
+same functionality that is used in the above code. Have a look at the code
+listing below for more details</p>
+<source><pre> public void processMail(ConfigurationContext confContext, MimeMessage mimeMessage) {
+ // create an Axis server
+ AxisEngine engine = new AxisEngine(confContext);
+ MessageContext msgContext = null;
+ // create and initialize a message context
+ try {
+ // Create a message context with mail as in and out transports.
+ msgContext =
+ new MessageContext(confContext,
+ confContext.getAxisConfiguration().getTransportIn(new QName(Constants.TRANSPORT_MAIL)),
+ confContext.getAxisConfiguration().getTransportOut(new QName(Constants.TRANSPORT_MAIL)));
+ msgContext.setServerSide(true);
+
+ msgContext.setProperty(MailConstants.CONTENT_TYPE, mimeMessage.getContentType());
+ msgContext.setWSAAction(getMailHeader(MailConstants.HEADER_SOAP_ACTION, mimeMessage));
+
+ // The service path is in the subject of the mail.
+ String serviceURL = mimeMessage.getSubject();
+ if (serviceURL == null) {
+ serviceURL = "";
+ }
+
+ String replyTo = ((InternetAddress) mimeMessage.getReplyTo()[0]).getAddress();
+ if (replyTo != null) {
+ msgContext.setReplyTo(new EndpointReference(replyTo));
+ }
+
+ String recipients = ((InternetAddress) mimeMessage.getAllRecipients()[0]).getAddress();
+
+ if (recipients != null) {
+ msgContext.setTo(new EndpointReference(recipients + "/" + serviceURL));
+ }
+
+ // add the SOAPEnvelope
+ String message = mimeMessage.getContent().toString();
+ ByteArrayInputStream bais = new ByteArrayInputStream(message.getBytes());
+ XMLStreamReader reader = XMLInputFactory.newInstance().createXMLStreamReader(bais);
+
+ // This is just in place to work with SOAP 1.1 and 1.2.
+ String soapNamespaceURI = "";
+ if (mimeMessage.getContentType().indexOf(SOAP12Constants.SOAP_12_CONTENT_TYPE) > -1) {
+ soapNamespaceURI = SOAP12Constants.SOAP_ENVELOPE_NAMESPACE_URI;
+ } else if (mimeMessage.getContentType().indexOf(SOAP11Constants.SOAP_11_CONTENT_TYPE) > -1) {
+ soapNamespaceURI = SOAP11Constants.SOAP_ENVELOPE_NAMESPACE_URI;
+
+ }
+ StAXBuilder builder = new StAXSOAPModelBuilder(reader, soapNamespaceURI);
+
+ SOAPEnvelope envelope = (SOAPEnvelope) builder.getDocumentElement();
+ msgContext.setEnvelope(envelope);
+ if (envelope.getBody().hasFault()) {
+ engine.receiveFault(msgContext);
+ } else {
+ engine.receive(msgContext);
+ }
+ } catch (Exception e) {
+ try {
+ if (msgContext != null) {
+ MessageContext faultContext = engine.createFaultMessageContext(msgContext, e);
+ engine.sendFault(faultContext);
+ }
+ } catch (Exception e1) {
+ log.error(e);
+ }
+ }
+ }</pre>
+</source>
+<p>If you don't happen to have a ConfigurationContext lying around to call
+this method you can use the following bit of code to get one. Once you create
+one you can store that on the mailet and keep using it.</p>
+<source><pre> File file = new File(MAIL_TRANSPORT_SERVER_ENABLED_REPO_PATH);
+ ConfigurationContextFactory builder = new ConfigurationContextFactory();
+ ConfigurationContext configContextbuilder
+ .buildConfigurationContext(file.getAbsolutePath());</pre>
+</source>
+<p></p>
+</body>
+</html>