Click here to close now.


Related Topics: Java IoT

Java IoT: 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.

    Latest Stories
    Too often with compelling new technologies market participants become overly enamored with that attractiveness of the technology and neglect underlying business drivers. This tendency, what some call the “newest shiny object syndrome,” is understandable given that virtually all of us are heavily engaged in technology. But it is also mistaken. Without concrete business cases driving its deployment, IoT, like many other technologies before it, will fade into obscurity.
    As the world moves towards more DevOps and microservices, application deployment to the cloud ought to become a lot simpler. The microservices architecture, which is the basis of many new age distributed systems such as OpenStack, NetFlix and so on, is at the heart of Cloud Foundry - a complete developer-oriented Platform as a Service (PaaS) that is IaaS agnostic and supports vCloud, OpenStack and AWS. In his session at 17th Cloud Expo, Raghavan "Rags" Srinivas, an Architect/Developer Evangeli...
    DevOps has often been described in terms of CAMS: Culture, Automation, Measuring, Sharing. While we’ve seen a lot of focus on the “A” and even on the “M”, there are very few examples of why the “C" is equally important in the DevOps equation. In her session at @DevOps Summit, Lori MacVittie, of F5 Networks, will explore HTTP/1 and HTTP/2 along with Microservices to illustrate why a collaborative culture between Dev, Ops, and the Network is critical to ensuring success.
    There are many considerations when moving applications from on-premise to cloud. It is critical to understand the benefits and also challenges of this migration. A successful migration will result in lower Total Cost of Ownership, yet offer the same or higher level of robustness. Migration to cloud shifts computing resources from your data center, which can yield significant advantages provided that the cloud vendor an offer enterprise-grade quality for your application.
    SYS-CON Events announced today that Sandy Carter, IBM General Manager Cloud Ecosystem and Developers, and a Social Business Evangelist, will keynote at the 17th International Cloud Expo®, which will take place on November 3–5, 2015, at the Santa Clara Convention Center in Santa Clara, CA.
    Docker is hot. However, as Docker container use spreads into more mature production pipelines, there can be issues about control of Docker images to ensure they are production-ready. Is a promotion-based model appropriate to control and track the flow of Docker images from development to production? In his session at DevOps Summit, Fred Simon, Co-founder and Chief Architect of JFrog, will demonstrate how to implement a promotion model for Docker images using a binary repository, and then show h...
    As a CIO, are your direct reports IT managers or are they IT leaders? The hard truth is that many IT managers have risen through the ranks based on their technical skills, not their leadership ability. Many are unable to effectively engage and inspire, creating forward momentum in the direction of desired change. Renowned for its approach to leadership and emphasis on their people, organizations increasingly look to our military for insight into these challenges.
    Today air travel is a minefield of delays, hassles and customer disappointment. Airlines struggle to revitalize the experience. GE and M2Mi will demonstrate practical examples of how IoT solutions are helping airlines bring back personalization, reduce trip time and improve reliability. In their session at @ThingsExpo, Shyam Varan Nath, Principal Architect with GE, and Dr. Sarah Cooper, M2Mi's VP Business Development and Engineering, will explore the IoT cloud-based platform technologies driv...
    Containers have changed the mind of IT in DevOps. They enable developers to work with dev, test, stage and production environments identically. Containers provide the right abstraction for microservices and many cloud platforms have integrated them into deployment pipelines. DevOps and containers together help companies achieve their business goals faster and more effectively. In his session at DevOps Summit, Ruslan Synytsky, CEO and Co-founder of Jelastic, will review the current landscape of...
    The IoT market is on track to hit $7.1 trillion in 2020. The reality is that only a handful of companies are ready for this massive demand. There are a lot of barriers, paint points, traps, and hidden roadblocks. How can we deal with these issues and challenges? The paradigm has changed. Old-style ad-hoc trial-and-error ways will certainly lead you to the dead end. What is mandatory is an overarching and adaptive approach to effectively handle the rapid changes and exponential growth.
    As-a-service models offer huge opportunities, but also complicate security. It may seem that the easiest way to migrate to a new architectural model is to let others, experts in their field, do the work. This has given rise to many as-a-service models throughout the industry and across the entire technology stack, from software to infrastructure. While this has unlocked huge opportunities to accelerate the deployment of new capabilities or increase economic efficiencies within an organization, i...
    The web app is agile. The REST API is agile. The testing and planning are agile. But alas, data infrastructures certainly are not. Once an application matures, changing the shape or indexing scheme of data often forces at best a top down planning exercise and at worst includes schema changes that force downtime. The time has come for a new approach that fundamentally advances the agility of distributed data infrastructures. Come learn about a new solution to the problems faced by software organ...
    Clutch is now a Docker Authorized Consulting Partner, having completed Docker's certification course on the "Docker Accelerator for CI Engagements." More info about Clutch's success implementing Docker can be found here. Docker is an open platform for developers and system administrators to build, ship and run distributed applications. With Docker, IT organizations shrink application delivery from months to minutes, frictionlessly move workloads between data centers and the cloud and achieve 2...
    Achim Weiss is Chief Executive Officer and co-founder of ProfitBricks. In 1995, he broke off his studies to co-found the web hosting company "Schlund+Partner." The company "Schlund+Partner" later became the 1&1 web hosting product line. From 1995 to 2008, he was the technical director for several important projects: the largest web hosting platform in the world, the second largest DSL platform, a video on-demand delivery network, the largest eMail backend in Europe, and a universal billing syste...
    There will be 20 billion IoT devices connected to the Internet soon. What if we could control these devices with our voice, mind, or gestures? What if we could teach these devices how to talk to each other? What if these devices could learn how to interact with us (and each other) to make our lives better? What if Jarvis was real? How can I gain these super powers? In his session at 17th Cloud Expo, Chris Matthieu, co-founder and CTO of Octoblu, will show you!