eNode Clients for Web Services

Table of Contents

Markup Tutorial

Interfacing with Java™

Web Services

Message

Fax Client

A Simple SOAP-based EMail Client

Make sure you have JRE 1.3.1 or later, and Java Web Start 1.0.1 or later already installed, before you launch EMailer. Also see Security Advisories.

Structure of the EMail Client

The eMail client realizes its user interface from markup describing its main view hierarchy in eNode UI Markup Language. It invokes a web service using a controller defined as a simple JavaBean™ class.

To minimize the number of object interconnections, the controller object does not directly deal with the presentation components in the view. Instead, it defers that task to a mediator defined by another JavaBean class. (See Mediator Pattern in Gamma, et al.)

The controller activates a SOAP-based web service by sending a message to a service endpoint through a simple wrapper object for the operation. This is illustrated in the following figure:

As usual, we first present the markup, followed by the code for the JavaBean classes.

Markup for the EMail Client

The markup for the email client starts with a reserve element that contains an object element describing the controller class com.enode.xalt.services.EMailer, followed by standard edit actions, and the main menu bar for the email client. The reserve element is followed by a frame element that constitutes the root of the view hierarchy.

The emailer object is configured with two bean properties. The mediator property describes the object that manages presentation components in the view, and the operation property describes various attributes of messages that the controller sends to the service endpoint. The values for these message attributes are obtained from the WSDL Document for the EMail Service.

<?xml version="1.0"?>
<resource xmlns="http://www.enode.com/xalt" xmlns:xlink="http://www.w3.org/1999/xlink">
    <reserve>
        <object id="emailer" class="com.enode.xalt.services.EMailer">
            <property key="mediator">
                <object class="com.enode.xalt.services.EMailMediator">
                    <property key="fromField">
                        <textField id="from" columnCount="48"/>
                    </property>
                    <property key="toField">
                        <textField id="to" columnCount="48"/>
                    </property>
                    <property key="subjectField">
                        <textField id="subject" columnCount="48"/>
                    </property>
                    <property key="messageField">
                        <textArea id="message" lineWrap="true" wrapStyle="word"/>
                    </property>
                </object>
            </property>
            <property key="operation">
                <message operationNamespace="urn:EmailIPortTypeInft-IEmailService"
                    operationName="SendMail"
                    action="urn:EmailIPortTypeInft-IEmailService#SendMail"
                    endpoint="http://webservices.matlus.com/scripts/emailwebservice.dll/soap/IEmailservice"
                    class="com.enode.xalt.services.EMail"/>
            </property>
        </object>

        <object id="edit" class="com.enode.xalt.actions.Edit"/>
        <action id="undoAction" title="Undo" description="Undo" target="#edit"/>
        <action id="cutAction" title="Cut" description="Cut" target="#edit" method="doCut"/>
        <action id="copyAction" title="Copy" description="Copy" target="#edit" method="doCopy"/>
        <action id="pasteAction" title="Paste" description="Paste" target="#edit" method="doPaste"/>
        <action id="clearAction" title="Clear" description="Clear" target="#edit" method="doClear"/>

        <menuBar id="eMailMenuBar">
            <menu title="File">
                <menuItem title="Send" action="#emailer"/>
                <separator/>
                <action title="Exit" class="com.enode.xalt.actions.Exit"/>
            </menu>
            <menu title="Edit">
                <menuItem action="#undoAction" icon="" accelerator="control Z" enabled="false"/>
                <separator/>
                <menuItem action="#cutAction" icon="" accelerator="control X"/>
                <menuItem action="#copyAction" icon="" accelerator="control C"/>
                <menuItem action="#pasteAction" icon="" accelerator="control V"/>
                <menuItem action="#clearAction" icon=""/>
            </menu>
            <menu title="Help">
                <hyperlink title="About EMailer" xlink:href="http://www.enode.com/x/1_1/emailer/"/>
                <separator/>
                <hyperlink title="Terms of Use" xlink:href="http://www.enode.com/x/1_1/terms.html"/>
                <hyperlink title="Third-Party License" xlink:href="http://www.enode.com/x/1_1/parserLicense.html"/>
                <hyperlink title="Show WSDL" 
                        xlink:href="http://webservices.matlus.com/scripts/emailwebservice.dll/wsdl/IEmailService"/>
            </menu>
        </menuBar>
    </reserve>
    <frame id="mailFrame" title="eMail" menuBar="#eMailMenuBar" onClose="exit" visible="false">
        <panel>
            <borderLayout/>
            <box orientation="vertical" constraints="North">
                <panel>
                    <flowLayout horizontalAlignment="trailing"/>
                    <label title="From:"/>
                    <textFieldRef xlink:href="#from"/>
                </panel>
                <panel>
                    <flowLayout horizontalAlignment="trailing"/>
                    <label title="To:"/>
                    <textFieldRef xlink:href="#to"/>
                </panel>
                <panel>
                    <flowLayout horizontalAlignment="trailing"/>
                    <label title="Subject:"/>
                    <textFieldRef xlink:href="#subject"/>
                </panel>
            </box>
            <scrollPane preferredSize="640 400" verticalScrollBar="always">
                <textAreaRef xlink:href="#message"/>
            </scrollPane>
            <panel constraints="South">
                <label title="Use of this service for sending unsolicited email (spam) is strictly prohibited."/>
                <button title="Send" action="#emailer"/>
            </panel>
        </panel>
    </frame>
</resource>

The Controller Class

The controller com.enode.xalt.services.EMailer is a JavaBean class that extends javax.swing.AbstractAction. Its actionPerformed() method activates the email web service.

The controller class also has setter and getter methods for the two bean properties, namely mediator and operation, as indicated in the markup above.

Finally, we decided to consolidate the eMail client application by putting its main() method directly in the controller class. You may choose to define a separate class for the client application, if you wish. The full listing for the controller class is shown below:

package com.enode.xalt.services;

public class EMailer extends javax.swing.AbstractAction {
    public EMailer() {
        // Java beans must have a default public constructor
    }

    // Mediator for GUI widgets
    public void setMediator(com.enode.xalt.services.EMailMediator med) {
        mediator = med;
    }

    public com.enode.xalt.services.EMailMediator getMediator() {
        return mediator;
    }

    // Message that encapsulates an email operation
    public void setOperation(com.enode.xalt.services.EMail op) {
        operation = op;
    }

    public com.enode.xalt.services.EMail getOperation() {
        return operation;
    }

    // Action method
    public void actionPerformed(java.awt.event.ActionEvent ev) {
        final javax.swing.JComponent    trigger = (javax.swing.JComponent) ev.getSource();
        final java.awt.Container        top = trigger.getTopLevelAncestor();
        java.awt.Cursor                 cursor = null;
        if (top != null) {
            cursor = top.getCursor();   // save cursor
            top.setCursor(java.awt.Cursor.getPredefinedCursor(java.awt.Cursor.WAIT_CURSOR));
        }

        if ((mediator != null) && (operation != null)) {
            try {
                final String status = operation.email(
                    mediator.getFrom(),     // email address of sender
                    mediator.getTo(),       // email address of recipient
                    mediator.getSubject(),  // subject of email message
                    mediator.getMessage()); // body of email message
            }
            catch (org.apache.soap.SOAPException ex) {
            }
            catch (Exception ex) {
            }
        }

        if (cursor != null) {       // implies top != null
            top.setCursor(cursor);  // restore cursor
        }
    }

    // Main method is called ONLY when this bean is used as a standalone application
    public static void main(String[] args) {
        // Get the root frame from the URI specified in args[0]
        // If no args are supplied, default to a "well known" URI.
        final String    rootURI = (args.length > 0) ? args[0] : "emailer.xit";

        try {
            final javax.swing.JFrame    rootFrame; // We expect a JFrame at rootURI
            rootFrame = (javax.swing.JFrame) com.enode.Resource.getCore(rootURI);

            if (rootFrame != null) {
                javax.swing.JOptionPane.setRootFrame(rootFrame);
                com.enode.Resource.centerFrame(rootFrame);
                rootFrame.setVisible(true);
            }
        }
        catch (Exception ex) {
            System.out.println("Main: " + ex.toString());
        }
    }

    private com.enode.xalt.services.EMail           operation = null;
    private com.enode.xalt.services.EMailMediator   mediator = null;
}

To keep the controller class simple, we have suppressed most error handling code. See how the translation example handles errors by displaying easily localizable user-friendly messages.

The Mediator Class

The mediator com.enode.xalt.services.EMailMediator is a simple JavaBean class with setter and getter methods for its properties, which consist of the user interface components for the client. It also has methods that can extract data from the user interface components.

The code for the mediator class is self-explanatory. Its full listing is shown below:

package com.enode.xalt.services;

public class EMailMediator {
    public EMailMediator() {
        // Java beans must have a default public constructor
    }

    // Component that is used to provide sender's email address
    public void setFromField(javax.swing.text.JTextComponent component) {
        from = component;
    }

    public javax.swing.text.JTextComponent getFromField() {
        return from;
    }

    public String getFrom() {
        return (from == null) ? "" : from.getText();
    }

    // Component that is used to provide recipient's email address
    public void setToField(javax.swing.text.JTextComponent component) {
        to = component;
    }

    public javax.swing.text.JTextComponent getToField() {
        return to;
    }

    public String getTo() {
        return (to == null) ? "" : to.getText();
    }

    // Component that is used to provide subject of the email
    public void setSubjectField(javax.swing.text.JTextComponent component) {
        subject = component;
    }

    public javax.swing.text.JTextComponent getSubjectField() {
        return subject;
    }

    public String getSubject() {
        return (subject == null) ? "" : subject.getText();
    }

    // Component that is used to provide the body of the email message
    public void setMessageField(javax.swing.text.JTextComponent component) {
        message = component;
    }

    public javax.swing.text.JTextComponent getMessageField() {
        return message;
    }

    public String getMessage() {
        return (message == null) ? "" : message.getText();
    }

    private javax.swing.text.JTextComponent from = null;
    private javax.swing.text.JTextComponent to = null;
    private javax.swing.text.JTextComponent subject = null;
    private javax.swing.text.JTextComponent message = null;
}

The Message Class

Finally, com.enode.xalt.services.EMail is a JavaBean class that extends com.enode.Message, where most of the mundane message properties are set.

The code for the message class is self-explanatory. Its full listing is shown below:

package com.enode.xalt.services;

import org.apache.soap.rpc.Call;
import org.apache.soap.rpc.Parameter;
import org.apache.soap.rpc.Response;
import org.apache.soap.Fault;

// Much of this class can be mechanically constructed from a WSDL description.
// This particular implementation uses Apache SOAP, but can be easily adapted
// to use Axis or JAX-RPC.

// Message that encapsulates an email operation
public class EMail extends com.enode.Message {
    public EMail() {
        super();    // Java beans must have a default public constructor
    }

    public String email(String from, String to, String subject, String message)
                                                                throws Exception {
        // Set up parameters as required by the web service -- See WSDL document.
        final java.util.Vector param = getParameters();
        param.clear();	// Remove old parameters, if any.
        param.add(new Parameter("ToAddress", String.class, to, null));
        param.add(new Parameter("FromAddress", String.class, from, null));
        param.add(new Parameter("ASubject", String.class, subject, null));
        param.add(new Parameter("MsgBody", String.class, message, null));

        // Stereotypical code
        final Call      call = new Call(getOperationNamespace(), getOperationName(),
                                        param, null, getEncodingStyle());
        final Response  response = call.invoke(new java.net.URL(getEndpoint()),
                                                                getAction());
        final Fault     fault = response.getFault();

        if (fault == null) {
            return response.getReturnValue().getValue().toString();
        }
        else {
            return fault.toString();
        }
    }
}