Get Involved

Project Information

JSON Support in Axis2

This document explains the JSON support implementation in Axis2.
It includes an introduction to JSON, an outline as to why JSON
support is useful to Axis2 and how it should be used. This document
also provides details on test cases and samples.

What is JSON?

JSON (Java Script Object
Notation) is another data exchangeable format like XML, but more
lightweight and easily readable. It is based on a subset of the
JavaScript language. Therefore, JavaScript can understand JSON, and
it can make JavaScript objects by using JSON strings. JSON is based
on key-value pairs and it uses colons to separate keys and values.
JSON doesn't use end tags, and it uses braces (curly brackets) to
enclose JSON Objects.

e.g. <root><test>json
object</test></root> ==
{{json object}}

When it comes to converting XML to JSON and vice versa, there
are two major conventions, one named "Badgerfish" and the other,
Mapped. The main difference
between these two conventions exists in the way they map XML
namespaces into JSON.

JSON support is a new feature in Apache Axis2/Java. It will become
a crucial improvement in the future with applications like
JavaScript Web services.

Why JSON Support for Axis2?

Apache Axis2 is a Web
services stack that delivers incoming messages into target
applications. In most cases, these messages are SOAP messages. In
addition, it is also possible to send REST messages through Axis2.
Both types of messages use XML as their data exchangeable format.
So if we can use XML as a format, why use JSON as another
format?

There are many advantages of implementing JSON support in Axis2.
Mainly, it helps the JavaScript users (services and clients written
in JavaScript) to deal with Axis2. When the service or the client
is in JavaScript, it can use the JSON string and directly build
JavaScript objects to retrieve information, without having to build
the object model (OMElement in Axis2). Also, JavaScript services
can return the response through Axis2, just as a JSON string can be
shipped in a JSONDataSource.

Other than for that, there are some extra advantages of using
JSON in comparison to XML. Although the conversation
XML or JSON? is still a hot topic,
many people accept the fact that JSON can be passed and built more
easily by machines than XML.

How to use JSON in Axis2

At the moment JSON doesn't have a standard and unique content
type. application/json (this is
the content type which is approved in the JSON RFC ),
text/javascript and
text/json are some of the commonly
used content types of JSON. Due to this problem, in Axis2, the user
has been given the freedom of selecting the content type.

Step 1

Map the appropriate MessageFormatter and OMBuilder with the
content type you are using in the axis2.xml file.

e.g.1: If you are using the
Mapped convention with the content
type application/json

If you are sending a request to a remote service, you have to
know the exact JSON content type that is used by that service, and
you have to use that content type in your client as well.

HTTP POST is used as the default method to send JSON messages
through Axis2, if the HTTP method is not explicitly set by the
user. But if you want to send JSON in HTTP GET method as a
parameter, you can do that by just setting an option on the client
side.

GET
/axis2/services/EchoXMLService/echoOM?query=%7B%22echoOM%22:%7B%22data%22:%5B%22my%20json%20string%22,%22my%20second%20json%20string%22%5D%7D%7D
HTTP/1.1

Tests and Samples

Integration Test

The JSON integration test is available under
test in the
json module of Axis2. It uses the
SimpleHTTPServer to deploy the service. A simple echo service is
used to return the incoming OMSourcedElementImpl object, which
contains the JSONDataSource. There are two test cases for two
different conventions and another one test case to send the request
in GET.

Yahoo-JSON Sample

This sample is available in the
samples module of Axis2. It is a
client which calls the Yahoo search API using the GET method, with
the parameter output=json. The
Yahoo search service sends the response as a
formatted JSON string with
the content type text/javascript.
This content type is mapped with the JSONOMBuilder in the
axis2.xml. All the results are shown in a GUI. To run the sample,
execute the ant script.

These two applications provide good examples of using JSON
within Axis2. By reviewing these samples, you will be able to
better understand Axis2's JSON support implementation.