The Simple Messaging Framework  

The Simple Messaging Framework

What Is The Simple Messaging Framework?

Author: Naresh Bhatia (nbhatia@sapient.com)
Created: July 2003
Version: $Revision: 1.1 $ ($Author: nbhatia $ / $Date: 2003/07/21 03:30:50 $)

Introduction

The Simple Messaging Framework provides an elegant way to create robust and flexible Web services. It is based on the document-style Web services paradigm that uses the full power of XML Schema. This approach enables you to expose arbitrarily complex business objects and services with ease.

Example

Let us look at a simple example to understand the benefits of the Simple Messaging Framework. Imagine that you were tasked to write a Web service that enabled your colleagues as well as customers to schedule meetings among themselves. Your company already has a calendar application that allows users to schedule meetings. All you need to do is to expose its MeetingService API as a Web service. This API is shown below.

MeetingService API
package org.calendarapp.meetingservice;
public interface MeetingService {
    public String createMeeting(Meeting meeting);
    public Meeting getMeeting(String meetingId);
    public void addAttendee(String meetingId, Attendee attendee);
    public void removeAttendee(String meetingId, String username);
    public void deleteMeeting(String meetingId);
}

The Meeting class used in this API is shown below. Notice that this class contains a map of attendees. This map associates usernames to Attendee objects.

Meeting Class
package org.calendarapp.businessobjects;
public class Meeting implements Serializable {
    private String meetingId;
    private String subject;
    private String location;
    private Date startTime;
    private Date endTime;
    private String organizer;
    private String body;
    private Map attendees;
    ...
}

Problem #1: Data Structure Limitations

Now suppose you use tools such as Java2Wsdl and WsdlToJava (provided by several SOAP toolkits) to generate your Web service. Such tools generally use one of two approaches to transmit maps:

  • Transmit the map as a single SOAP array, each element consisting of a key and a value.
  • Transmit the map as two SOAP arrays, one containing the keys and the other containing the values.

Realistically speaking, both approaches usually have some problems. Sometimes the solution is not interoperable with other toolkits. In other situations, the toolkit may force you to abandon maps, ignore them completely or even convert them to Java arrays! Now, as you know, the Java array is not a very flexible data structure. You waste a lot of time iterating through it, searching for objects. So what do you do? May be you can translate the object returned by the toolkit into a very similar one that uses maps. However that's more work for you, it is not very elegant and, since the translation must be done at run time, not very inefficient. The problem gets worse as the data structures become increasingly complex and the volume of data starts increasing. Is there a better way?

The Solution

An effective solution would be to completely take over the serialization/deserializtion of Java objects. This will allow you to map the objects to XML elements as you please and do the conversion efficiently in one shot! The Simple Messaging Framework allows you to do just that. It defines standard interfaces that you must implement to convert your Java objects in to XML elements and vice versa. In the Meeting example above, you can serialize the attendees map into multiple XML elements and later deserialize them directly in to a Map. You can use any XML parser/serializer you wish! Once you have implemented these interfaces, the framework automates the task of inserting/extracting your Java objects to and from SOAP messages.

The example below shows a Meeting object serialized as an XML element.

Meeting Object - XML Representation
<meeting>
  <meeting-id>1</meeting-id>
  <subject>Project kickoff</subject>
  <location>Room 203</location>
  <start-time>2003-07-08T22:02:15.603Z</start-time>
  <end-time>2003-07-08T22:02:15.603Z</end-time>
  <organizer>jdoe</organizer>
  <body>Let's get the ball rolling!</body>
  <attendee required="false" status="not_responded" username="phead"/>
  <attendee required="false" status="not_responded" username="thacker"/>
  <attendee required="false" status="not_responded" username="jsmith"/>
  <attendee required="false" status="accepted" username="jdoe"/>
</meeting>

Problem #2: Fine Grained Messages

To understand the second problem, assume that you have successfully exposed the MeetingService API as a Web service. Further assume that you have created a meeting on the server using the createMeeting() call. However now you want to update the meeting to add ten attendees and and remove two. What are your options? The easiest one, of course, is to make ten addAttendee() calls and two removeAttendee() calls. However, since making a connection to a Web service is expensive, making 12 connections to accomplish this would be very inefficient! Your other option is to extend (or modify) the MeetingService API to add two new calls, say, addAttendees() and removeAttendees(). Even then, you would have to make two separate calls to get the job done. And, by the way, the IT department just informed you that you are not allowed to make any modifications to the MeetingService API. What do you do now?

The Solution

The Simple Messaging Framework allows you to collect bunch of fine-grained messages into a single composite message, thus enabling you to send all your requests in one shot. It does so using the "Composite" pattern. The framework defines an abstract class called Message and a concrete class called CompositeMessage. You can extend the Message class to create fine-grained messages such as AddAttendeeMessage and RemoveAttendeeMessage. Once you have defined these fine-grained messages, you can send any combination using the CompositeMessage. The response to a CompositeMessage is another CompositeMessage containing the results of your request. In fact, you can nest messages to any depth and you may even extend the CompositeMessage to meet your specific needs.

The example below shows the XML representation of a CompositeMessage consisting of one AddAttendeeMessage and one RemoveAttendeeMessage.

CompositeMessage Example
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

 <soapenv:Body>

  <message xsi:type="CompositeMessage"
    xmlns="http://www.calendarapp.org/meeting-service"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <message xsi:type="AddAttendeeMessage">
      <meeting-id>1</meeting-id>
      <attendee required="true" status="not_responded" username="jsmith"/>
    </message>

    <message xsi:type="RemoveAttendeeMessage">
      <meeting-id>1</meeting-id>
      <username>jmagic</username>
    </message>

  </message>

 </soapenv:Body>
</soapenv:Envelope>

Where to go from here?

Now that you know what the Simple Messaging Framework has to offer, you have several options to explore it further. Here are a few suggestions.


Copyright © 2003, Sapient Corporation