eNode Clients for Web Services

Table of Contents

Markup Tutorial

Interfacing with Java™

Web Services

EMail Client

Translation Client

A Simple SOAP-based Fax 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 FaxSender. Also see Security Advisories.

Structure of the Fax Client

Just like the email client, the fax 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.

Also, as in the email client, 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 Fax Client

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

The faxSender 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 Fax Service.

<?xml version="1.0"?>
<resource xmlns="http://www.enode.com/xalt" xmlns:xlink="http://www.w3.org/1999/xlink">
    <reserve>
        <object id="faxSender" class="com.enode.xalt.services.FaxSender">
            <property key="mediator">
                <object class="com.enode.xalt.services.FaxMediator">
                    <property key="fromField">
                        <textField id="from" columnCount="48"/>
                    </property>
                    <property key="toField">
                        <textField id="to" columnCount="48"/>
                    </property>
                    <property key="faxNumberField">
                        <textField id="faxNumber" columnCount="48"/>
                    </property>
                    <property key="messageField">
                        <textArea id="message" lineWrap="true" wrapStyle="word"/>
                    </property>
                </object>
            </property>
            <property key="operation">
                <message operationNamespace="urn:OneOutBox"
                    operationName="SendFreeFAX"
                    action="urn:OneOutBox#SendFreeFAX"
                    endpoint="http://www.OneOutBox.com:80/cgi-bin/soap/outbox.cgi"
                    class="com.enode.xalt.services.Fax"/>
            </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="faxMenuBar">
            <menu title="File">
                <menuItem title="Send" action="#faxSender"/>
                <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 FaxSender" xlink:href="http://www.enode.com/x/1_1/faxsender/"/>
                <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://www.OneOutBox.com/wsdl/FreeFaxService.wsdl"/>
            </menu>
        </menuBar>
    </reserve>
    <frame id="faxFrame" title="Fax" menuBar="#faxMenuBar" onClose="exit" visible="false">
        <panel>
            <borderLayout/>
            <box orientation="vertical" constraints="North">
                <panel>
                    <flowLayout horizontalAlignment="trailing"/>
                    <label title="Sender's eMail:"/>
                    <textFieldRef xlink:href="#from"/>
                </panel>
                <panel>
                    <flowLayout horizontalAlignment="trailing"/>
                    <label title="Receiver's Name:"/>
                    <textFieldRef xlink:href="#to"/>
                </panel>
                <panel>
                    <flowLayout horizontalAlignment="trailing"/>
                    <label title="Fax Number:"/>
                    <textFieldRef xlink:href="#faxNumber"/>
                </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 fax is strictly prohibited."/>
                <button title="Show Coverage Area" xlink:href="http://www.tpc.int/fax_cover_auto.html"/>
                <button title="Send" action="#faxSender"/>
            </panel>
        </panel>
    </frame>
</resource>

The Controller Class

The controller com.enode.xalt.services.FaxSender is a JavaBean class that extends javax.swing.AbstractAction. Its actionPerformed() method activates the fax 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 Fax 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 FaxSender extends javax.swing.AbstractAction {
    public FaxSender() {
        // Java beans must have a default public constructor
    }

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

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

    // Message that encapsulates a fax operation
    public void setOperation(com.enode.xalt.services.Fax op) {
        operation = op;
    }

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

    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.fax(
                    mediator.getFrom(),         // email address of sender
                    mediator.getTo(),           // name of recipient
                    mediator.getFaxNumber(),    // fax number of recipient
                    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] : "faxSender.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.Fax             operation = null;
    private com.enode.xalt.services.FaxMediator     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.FaxMediator 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 FaxMediator {
    public FaxMediator() {
        // 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 name
    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 recipient's fax number
    public void setFaxNumberField(javax.swing.text.JTextComponent component) {
        faxNumber = component;
    }

    public javax.swing.text.JTextComponent getFaxNumberField() {
        return faxNumber;
    }

    public String getFaxNumber() {
        return (faxNumber == null) ? "" : faxNumber.getText();
    }

    // Component that is used to provide body of the 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 faxNumber = null;
    private javax.swing.text.JTextComponent message = null;
}

The Message Class

Finally, com.enode.xalt.services.Fax 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 a fax operation
public class Fax extends com.enode.Message {
    public Fax() {
        super();    // Java beans must have a default public constructor
    }

    public String fax(String from, String to, String faxNumber, 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("Sender", String.class, from, null));
        param.add(new Parameter("ToNum", String.class, faxNumber, null));
        param.add(new Parameter("Name", String.class, to, null));
        param.add(new Parameter("Text", 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();
        }
    }
}