Skip Top Navigation
Developers Partners
North America [change region] Products Solutions Purchasing Support

Using WBXML Parsing to Send Data to Wireless Devices

Rohit Gupta, Research In Motion

The growing popularity and corporate usage of BlackBerry means that an increasing number of organizations are providing wireless access to corporate data for their mobile workers. Although this can have productivity benefits, the cost of transmitting information wirelessly is a consideration when organizations decide which applications and information to make available to their BlackBerry users.

XML is useful for representing complex data in a simplified way that can be displayed in any application. Unfortunately, XML is not always practical to use in wireless environments because XML files tend to be large documents. Transmitting large documents over wireless networks can be costly and time-consuming for users who are downloading information on a wireless device. Wireless binary XML (WBXML) offers a cost-saving alternative to XML documents. WBXML replaces the customized XML tags with a binary value, which significantly decreases the file size. WBXML incorporates the advantages of XML without the disadvantages of the large file size.

Topics within this section include:

Understanding XML

XML is designed to provide more flexible and adaptable information identification. It is extensible because it is not a fixed format like HTML. Instead, XML is a meta language - a language for describing other languages - that allows you to design your own customized markup language for different types of documents.

Advantages of using XML to code data

With XML, application developers can represent complex data in a simple manner. They can completely define their data in XML because it provides fully customized tags. There are no pre-defined or hard-coded tags like HTML. Some of the advantages of using XML to represent data include:

  • XML, like Java, is viewed as open source. This means that any application can open an XML document and display its contents.
  • XML is as easy to read and write as HTML.
  • XML files take approximately the same amount of time to render as HTML files.
  • XML provides developers with more customization options and access to more tools than HTML.
  • XML seamlessly integrates with multiple applications, making XML a standard type for data definition documents.

Limitations of using XML in wireless application development

XML documents can be large, which reduces its value for sending data to users’ wireless devices. An optimal solution involves sending rich data using the quickest and most cost efficient method possible. Wireless binary XML is one solution that helps to reduce the file size and save organizations transmission time and costs.

Understanding WBXML

WBXML provides a way to send documents quickly and more cost effectively while maintaining the advantages of using XML. WBXML is a compact representation of XML and is part of the presentation logic in Wireless Application Protocol (WAP). WBXML significantly improves the efficiency of transmitting XML over narrow bandwidth networks where data size is of paramount importance.

Most of the WBXML format is not human readable; it contains bytes or octets in raw (non-textual or non-encoded) and hexadecimal form. Two hexadecimal numbers represent 1 byte.

Binary form Hexadecimal form
0100 1000 0x48
1100 1110 0111 1101 0xCE 0x7D

Advantages of using WBXML to send data wirelessly

Using WBXML for sending data wirelessly offers the following advantages:

  • Because the tags in WBXML are represented as a binary value, you can save transmission time when sending the document to a wireless device.
  • Binary XML documents are considerably smaller than XML documents. This reduces the amount of airtime it takes to send a WBXML document wirelessly, which may result in a lower cost to transmit it.
  • Binary XML parsing is about half the size of an XML parsing. The BlackBerry MDS Services creates a WBXML document by taking an XML document and creating two additional corresponding files: a binary XML file and a codebook.

Note: Refer to the BlackBerry MDS Services log (ZIP) for an example of a codebook.

About codebooks

The codebook is used after the BlackBerry device receives the binary XML document. A codebook holds the table value for the binary tags. It is usually stored on the device since it is lightweight and the values are matched once the binary document is received. A codebook contains the following three types of tables:

table type
Tag table Defines the element values
Start table Defines the name of the attributes
Value table Defines the value of the attribute

Codebook creation

Certain conditions must be met before the BlackBerry MDS Services can successfully create a codebook from an existing XML document.

  • The XML document needs an external DTD/XSD document because the codebook is generated from the DTD/XSD and the binary XML file is generated from the XML itself.
  • The address for the XML document must be referred to in URL format.
  • The address in the XML document pointing to the DTD/XSD must be in URL format, not as a local file path.

For example, use: http://localhost:8000/content/text.dtd

... instead of c:/sample/text.dtd

Note: The codebook is returned from the BlackBerry MDS Services in a 64-bit string type. You must put that string in a 64bit array before you can manipulate it.

Codebook storage

There are two options for storing the codebook. It can either be persistently stored on the device, or it can be created each time the application is invoked by the user. Do not use the second scenario unless the memory on the device is close to being full. Creating a redundant codebook and sending it every time breaks down the function of WBXML, since the amount of airtime used is not significantly lowered.

The net.rim.device.api.xml.jaxp API

The net.rim.device.api.xml.jaxp is a new API found in the BlackBerry Java Development Environment (JDE) v4.0. The classes found in this API are described in the following table.

Class Description
DomInternalRepresentation Represents an XML document and is used to implement the W3C DOM
SAXParserImpl Using the specified default handler uses this class to parse the content of a given Input Stream instance as XML
WBXMLCodeBookCreationHandler Extends the default handler and deals with the content of a codebook after it is created
WBXMLParser Handles all WBXML documents and their attributes
WBXMLWriter Extends the default handler and implements an XML writer as a SAX parser handler. The main purpose of this class is to handle the WBXML document once it has been parsed
XMLParser Handles all XML documents that need to be parsed and their attributes
XMLWriter Same as WBXMLWriter but handles XML documents

Development steps for using WBXML

The following steps guide you through the process of creating an application that can be parsed using WBXML. Refer to the code sample (ZIP) for clarification as you move through the steps.

Step 1: Make sure that the XML file is up to code and fully valid

This step includes verifying that the corresponding DTD/XSD files are created correctly and that the code in the XML file is also correct. There are multiple third-party software products available that can build a DTD on its own after the XML is validated. The XML and its corresponding DTD/XSD must be stored on a web server. The BlackBerry MDS Services needs a URL to find the WBXML file. The address in the XML that points to the DTD/XSD must be a URL in order for the BlackBerry MDS Services to find the codebook.

Note: If you get a SAX parser exception, make sure the XML document is valid.

Step 2: Build object classes

These classes include all object references that are found in the XML document. In the sample, there is only one object called Contact. Building object classes makes it easier to control the data that is shown on the BlackBerry device and makes it easier to add and subtract data types. A well-formed XML document contains, at most, one or two major object types and multiple attributes and minor objects within them. For example, in the sample, there is one object type with multiple attributes in it.

Object Element Example
Name First name
Last name
John Doe
Phone number Area code
Remaining digits
of phone number

These object classes make the rest of the development easier and less confusing.

Step 3: Handle the parsed file

The default handler dictates what to do with the data after it is parsed and provides a place where the SAX parser can store the parsed data. The default handler is a public class, but it responds like an interface because most of its important functions return null values. You must construct a class that extends the default handler. You can use one of the given classes, like WBXMLWriter, but it has limitations. It does not have enough functions to produce correct output or to correctly handle the parsed data for the sample application. The default handler class can be developed in multiple ways, but the two main functions are startElement() and endElement(). Their default value is to return null but this is where the finding of the data can be done. The function startElement() does something at the start of a tag or element; the endElement() function does something at the end of a tag.

In the sample, at the start of each of the elements, you set the type of data so that you know which data to get and then store under the appropriate setting in the object class. The method characters() returns the data value of an element, including its white space and empty characters. It is important to use the trim method so that white space and empty characters are not collected and displayed. In the sample, the data was extracted and displayed, leaving the class small in size.

Note: The default handler has more functionality than used in the sample. See the BlackBerry API v4.0 for more information.

Step 4: Persistent storage of the codebook

In most cases, the persistent classes are small and easy to create. Some developers include persistent classes in their main Java application class, but it is usually easier to create them as an external class. Because most applications involve persistent classes, not much detail is included here. The sample includes an object of a persistent object, which holds the same attributes as a codebook. Because codebooks are not persistent objects, they cannot be stored directly on the device, but must be instantiated as a persistent object. In most cases, this exact persistent class can be used in your development. Even with modifications, a persistent class is relatively simple to create.

Step 5: Develop the application

The main class

Now that you have taken care of the entire external element surrounding the development for WBXML, you are ready to develop the core Java application. This part of the development is similar to developing other applications, so only problematic issues are discussed.

Looking at the attached code, initially you can see all the member variables being defined, the main function is starting the application, and the constructor is setting the title, creating a screen and pushing it and instantiating the connection thread. This activity is all being done in the main class.

Note: Looking at the code, you can see that UiApplication.getUiApplication().invokeAndWait(new Runnable()) was used multiple times. Only one thread at a time can gain access to an interface component. If you are getting a UI exception check whether you are invoking any screen variables without using this function.

Converting 64-bit codebook to string

The function getCodeBookFromString takes a 64-bit string containing the codebook. Using the WBXML parser, it creates a codebook handler. This function can be reused in multiple applications that require a codebook. It was created as a standard function because the BlackBerry MDS Services will always have 64-bit string value of the codebook. It is easier to create a codebook handler than the codebook itself; the string is parsed using the WBXML parser. Remember that the WBXML parser takes an input stream containing a WBXML document and parses it to a default handler. In this case, the default handler is the codebook handler, so now you can use the codebook to parse data.

Adding contacts

The addContact function is customized for each parsing application. This function takes the object type Contact and outputs its relevant data. This function works in collaboration with the contact class. The contacts are being fetched from a vector array, which were stored in it by the default handler class Parser.

Creating a separate thread

The thread class makes the request to the BlackBerry MDS Services for the conversion of XML into WBXML and its corresponding codebook through an HTTP header request. If this is the first time the device is receiving the codebook, you can store it using persistent store. If the codebook already exists, you can reuse the stored codebookas shown in the IF and ELSE statement found in this class.

If the codebook does not exist, make the X-RIM-UseCodeBook true and embed. If the codebook exists, make it true. There is no check to see if the codebook is up to date, this is just a sample, that much detail is not necessary at this point.

From the CodebookHandler, retrieve the tables that are needed for SAX parser, parse the matching XML with the codebook, and retrieve the data. The other HTTP headers are setting the transcoded content to be XML, for the given document, BlackBerry MDS Services creates its WBXML and codebook. The other header is telling the BlackBerry MDS Services to accept the type of WBXML and the codebook documents. The last step involves doing the necessary functions to the data or displaying it.

Note: You must use all of the HTTP headers for the WBXML parsing to work. You can have more than the requirement header, but these headers are the minimum requirement.


There are two major constraints to sending data wirelessly: the time to render the document and the cost of sending it. With WBXML parsing, you can help minimize these two constraints while still transmitting all of the necessary data. Mobile workers can access critical data at a more cost-effective and faster rate than by using XML documents.

WBXML development does not have to be more difficult than XML or HTML development. Developers with skills in application development can quickly learn how to use WBXML to send data across wireless networks.

You can download the sample from the Developer Journal site to use as a guide in development, and can also enhance it when creating your own custom application.

Visit BlackBerry Developer Zone for more information about application development for BlackBerry. See the APIs for the BlackBerry JDE v4.0 for more information on additional functions that were not used or discussed for this sample but that might be helpful as you develop your own applications.

Please email your comments, suggestions and editorial submissions to

Top |  Table of Contents |  Journal in PDF Format |  Legal Disclaimer
 Home | Products | Solutions | Purchasing | Support | Developers | Worldwide | News | About Us | Contact Us | Site Map
 Legal | Copyright © 2008 Research In Motion Limited, unless otherwise noted.