SYS-CON MEDIA Authors: Gilad Parann-Nissany, Cloud Ventures

Related Topics: Java

Java: Article

Building a J2ME Multimedia Messaging Service Client

Host your own MMS content server and more

The Wireless Messaging API (WMA) reference implementation supports short message service (SMS) text and binary messages, but leaves the implementation of the hot area of multimedia messaging untouched. This article will demonstrate how to build a Multimedia Messaging Service (MMS) client using J2ME so you can get started writing new applications using this technology. By doing your own J2ME client implementation, you can bypass carrier lock-in of the content server or Multimedia Messaging Service Center (MMSC), as well as build your own server-side MMS applications, which you couldn't do before outside of the carrier network.

Software Requirements
A number of software requirements are needed to test the MMS client application. To run the basic emulation environment, make sure you have Sun's Wireless Toolkit 2.1 and JDK 1.4.2 or higher, both downloadable at Download and compile the latest source code for the MMS Client and tools, available at Next, set up either a Web or application server to act as the content server for the multimedia messages. Finally, you'll need to download the Nokia Mobile Internet Toolkit 4.0 from

MMS Notification and Retrieval
The push registry maintains a list of inbound connections to mobile devices. It's one of the most exciting and least used features of the MIDP 2.0 spec. Under MIDP 1.0, a network-based application needed to constantly establish a connection and poll an application server for events. This ate up airtime and cost the user money, making network-based J2ME applications infeasible in many cases.

You can register inbound connections in the push registry by adding the connection information to the JAD file or by explicitly invoking the registerConnection static method on the PushRegistry class. In the J2SE world, registration is equivalent to opening a ServerSocket connection and waiting for a connection. The snippet below shows how we can register the connections in the JAD.

MIDlet-Push-1: serversocket://:1236, org.jvending.messaging.mmclient.MmsMidlet, *
MIDlet-Push-2: datagram://:1235, org.jvending.messaging.mmclient.MmsMidlet, *
MIDlet-Push-3: sms://:1234, org.jvending.messaging.mmclient.MmsMidlet, *

Why would you need to register so many push connections? There are a number of different ways to push the message notification, depending on the carrier network. You may need to set up push interfaces to cover push-over TCP (serversocket), WDP/UDP (datagram), and SMS. For instance, if we have an active GPRS or CSD connection, the server application may decide to send the MMS notification on the datagram connection, without failing over to the SMS connection. This means our MMS message is effectively lost.

Let's show how notification works in a carrier environment. Prior to the recipient MMS user agent retrieving an MMS message, the network must notify the user agent that the message is awaiting retrieval. There are a number of different ways for this notification to take place. The most common are SMS or WDP/UDP. If the user does not have a data session established, the notification will come over an SMS bearer. If a session has been established, the server just needs to push the request to the device over WDP/UDP (WAP 1.2+) or TCP (WAP 2.0).

Figure 1 shows a typical configuration within a carrier network for connectionless (asynchronous) notification through SMS. In step 1, the MMSC contacts the Push Proxy Gateway (PPG), which handles the pushing of messages to the mobile device. Next, the PPG contacts the Short Message Service Center (SMSC). In steps 3 and 4, the SMS is delivered over the GPRS network to the mobile device. If the MIDlet is not active, the application management software (AMS) detects that an SMS is destined, say, for port 1234. The AMS starts an instance of MmsMidlet, which extracts the MMS notification message from the body of the SMS message to find the MMS content location. In step 5, our application on the mobile device initiates an HTTP/GET connection to the content server.

Keep in mind that in most networks the connection is over the Wireless Session Protocol (WSP), which has an encoding that the content server does not understand. For steps 6 and 7, the network routes the HTTP request to the WAP gateway. The WAP gateway translates the WSP binary encoded HTTP headers into normal HTTP headers and forwards the request (step 8) onto the content server. The content server now delivers the WSP encapsulated MMS message over HTTP back to the mobile device. The MmsMidlet receives the MMS message, decodes it, and displays the graphical content to the user.

Testing Message Notification and Retrieval over an SMS Bearer
Let's test out retrieving an MMS message. First we need to set up a content server, which is merely an application or Web server that stores the MMS content. You can find sample MMS files in the Nokia Mobile Toolkit. Place marketupdate.nosmil.mms on the application server at, say, http://localhost:8080/ ROOT/marketupdate.nos mil.mms.

Now we need to generate an MMS message notification package. Do this by instantiating the .mms.MNotificationGenerator class, with parameters filename and content URL location (http://localhost:8080/ ROOT/marketupdate.nosmil.mms), which points to the location of the MMS message on the content server. You now have an MMS notification message stored on your local file system.

Next, open the WMA console within the Wireless Toolkit utilities tool. Make sure you're using version 2.1, since version 2.0 has a problem binary encoding characters within the 128-159 range. Click the "Send SMS" button followed by the Binary SMS tab. Import the contents of the MMS message that you generated with the MNotificationGenerator and type in port number 1234 within the text field.

Open up the emulator and click the MmsMidlet. You'll get a message asking if it's okay to receive text (or SMS) messages. Click OK. Go back to the WMA console and click "Send". This sends the binary SMS that contains the MMS notification to the recipient MMS user agent. Look at the package structure in Figure 2; the SMS body contains the MMS headers.

The MMS client application decodes this message and determines that it is an MMS notification message. The client reads the content URL location, opens an HTTP connection to the content server, pulls down the MMS message containing the mymessage.mms (see Figure 3), and displays the content on the mobile device. I'll explain exactly how to do this in the next sections.

Decoding the Multimedia Message
The MultimediaParser instance has a parse method that takes a PeekInputStream instance and a multimedia message object as parameters. A multimedia message object consists of two primary parts: the MMS headers and the MIME body (see Figure 3). The MultimediaParser instance delegates construction of the multimedia message object to two other objects, the HeaderFieldParser and the MimeParser.

The HeaderFieldParser's primary responsibility is to hand off the PeekInputStream object to an instance of WspTokenizer, which tokenizes the input stream into header fields according to the WSP spec. WSP encoding is a compact binary form that reduces the size of the headers.

The way this works is that if the first octet (or byte) is in the range of 32-127, the header is a text string, which ends with a 0 or null octet. If the first octet is in the range of 128-255, the header is binary encoded. For instance, if the value is 151, this maps to a TO field, which is subsequently followed by an encoded string. The less common values that begin in the range 0-31 are of variable length and center largely around date values.

This type of encoding makes tokenizing of the multimedia messaging surprisingly simple. You can decompose MMS into one of the following tokens: Text-String, Quoted-String, Extension-media, Short-integer, Multi-octet-integer, and Unitvar-Integer. The last two are integers of variable length, not something we have to deal with very often within the Java world. Essentially, they are just 128 base numbers and can be handled accordingly. See the source code to see how to encode/decode multi-octets. (The source code can be downloaded from

With the exception of octets in the range of 0-31, the WspTokenizer object can determine the exact token and how to read the header based on the first octet. If the value is less than 32, however, the tokenizer peeks ahead one octet to determine the path that it needs to tokenize the header (see Listing 1).

After tokenization, the HeaderFieldParser object passes those tokens to an instance of the HeaderFieldAssembler, which takes the tokens and assembles them into easily readable Field objects to store within the target MultimediaMessage object.

Now that the HeaderFieldParser object has finished decoding the MMS headers, the MultimediaParser passes control to an instance of MimeParser, provided that the message contains a Content-Type field. The MimeParser object now assembles the MultipartEntry objects for the various MIME types and places them within the instance of MultimediaMessage. Our target MultimediaMessage object is now complete and ready to pass to the MessageConnection object, covered in the next section.

Extending the Wireless Message API
The wireless message API consists of five interfaces:

  1. BinaryMessage
  2. Message
  3. MessageConnection
  4. MessageListener
  5. TextMessage
The BinaryMessage and TextMessage classes extend the Message interface. For this article, we add an additional class, MultimediaMessage, which also extends the message interface.

The javax.wireless.messaging. MessageConnection class has its own implementation on the mobile devices. Modifying this implementation to return MultimediaMessage objects would require recompiling core MIDP 2.0 classes. Thus, the MMS client has its own implementation called org.jvending.messaging.MessageConnection, which functions in the same way with the same API. Look at the receive method of org.jvending.messaging.MessageConnection. This implementation accepts two kinds of connections: HTTP and SMS, both of which return a Message object of type MultimediaMessage.

If the URL connection is HTTP based, invoking the receive method on the MessageConnection instance results in the mobile device initiating an HTTP connection to the content server and pulling down an MMS message. The MessageConnection object casts the connection as an HttpConnection and invokes the openInputStream method to obtain an InputStream object. This does not involve the WMA messaging functionality

If the connection is SMS, we leverage the WMA by casting the connection as javax.wireless.messaging.MessageConnection and receiving a BinaryMessage. We now need to get it into an InputStream object since this type is required to pass into the instance of MultimediaParser. This requires invoking the getPayloadData() method on the BinaryMessage and feeding this in as a parameter to an instance of ByteArrayInputStream.

Finally, the MessageConnection object creates an instance of PeekInputStream and then invokes the parse method on the MultimediaParser object. The target MultimediaMessage object is now filled with all the MMS headers and MIME entries. Note that the MessageConnection is not concerned with the type of MMS message or how to handle notification and retrieval flow. The MmsMidlet client handles this logic (see Listing 2).

The MMS Client
The org.jvending.messaging. mmsclient package contains two classes: the MmsMidlet, which contains the logic for instantiating MessageConnection classes; and the MultimediaViewer class, which handles the display of the headers and media types. The first thing the MmsMidlet does is open an SMS connection and then wait to receive a MultimediaMessage on port 1234 (of course, in the actual source code this is threaded).

When the MMS notification comes over the SMS bearer, the MmsMidlet strips out the body and confirms that it is an M_NOTIFICATION message type. The MmsMidlet object takes the content URL location from the MMS notification and uses it as a parameter when invoking the open method on the Connector class. As discussed in the previous section, invoking the receive method on the MessageConnection returns a MultimediaMessage object containing the MIME entries. Next the MmsMidlet passes the MultimediaObject to an instance of MultimediaViewer that will, in turn, display the media content on the user's device (see Listing 3).

In the wireless data area, innovation and development are often difficult because carriers tightly couple device applications and server-side services. When you use J2ME and J2EE together to build client and server applications, it enables you to bypass many of these constraints. All it takes is access to basic SMS and HTTP protocols.

This article illustrates this flexibility by showing how building a J2ME MMS client allows developers to host their own MMS content server. This article also covers the basics of MMS retrieval and notification. The source code contains an MMS encoder that allows the user to send MMS messages. When combined with the Mobile Media API (JSR 135), this provides the ability to create a lot of interesting applications. You can find the latest updates and complete source code at


  • Le Bodic, G. (2003). Mobile Messaging Technologies and Services. Wiley.
  • Metsker, S.J. (2001). Building Parsers with Java. Addison-Wesley.
  • now.sms:
  • Open Mobile Alliance, OMA-MMS-ENC-v1_1-20021030-C: Multimedia Messaging Service Encapsulation Protocol version 1.1, October 2002.
  • WAP Forum, WAP-230-WSP: Wireless Application Protocol, Wireless Session Protocol Specification Version 5, July 2001
  • More Stories By Shane Isbell

    Shane Isbell works as a software architect at a wireless carrier.

    Comments (0)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.