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.
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.
e.g. <xsl:root xmlns:xsl="http://foo.com"><data>my json string</data></xsl:root>
This XML string can be converted into JSON as follows.
Using Badgerfish
{"xsl:root":{"@xmlns":{"xsl":"http://foo.com"},"data":{"$":"my json string"}}}
Using Mapped
If we use the namespace mapping as http://foo.com -> foo
{"foo.root":{"data":"my json string"}}
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.
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.
For more details of this implementation architecture, refer to the article "JSON Support for Apache 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.
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
<messageFormatters>
<messageFormatter contentType="application/json"
class="org.apache.axis2.json.JSONMessageFormatter"/>
<!-- more message formatters -->
</messageFormatters>
<messageBuilders>
<messageBuilder contentType="application/json"
class="org.apache.axis2.json.JSONOMBuilder"/>
<!-- more message builders -->
</messageBuilders>
e.g.2: If you are using the Badgerfish convention with the content type text/javascript
<messageFormatters>
<messageFormatter contentType="text/javascript"
class="org.apache.axis2.json.JSONBadgerfishMessageFormatter"/>
<!-- more message formatters -->
</messageFormatters>
<messageBuilders>
<messageBuilder contentType="text/javascript"
class="org.apache.axis2.json.JSONBadgerfishOMBuilder"/>
<!-- more message builders -->
</messageBuilders>
On the client side, make the ConfigurationContext by reading the axis2.xml in which the correct mappings are given.
e.g.
File configFile = new File("test-resources/axis2.xml");
configurationContext = ConfigurationContextFactory
.createConfigurationContextFromFileSystem(null, configFile.getAbsolutePath());
..........
ServiceClient sender = new ServiceClient(configurationContext, null);
Set the MESSAGE_TYPE option with exactly the same content type you used in the axis2.xml.
e.g. If you use the content type application/json,
Options options = new Options();
options.setProperty(Constants.Configuration.MESSAGE_TYPE, application/json);
//more options
//...................
ServiceClient sender = new ServiceClient(configurationContext, null);
sender.setOptions(options);
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.
e.g.
options.setProperty(Constants.Configuration.HTTP_METHOD,
Constants.Configuration.HTTP_METHOD_GET);
Here, the Axis2 receiving side (JSONOMBuilder) builds the OMElement by reading the JSON string which is sent as a parameter. The request can be made even through the browser.
e.g. Sample JSON request through HTTP GET. The JSON message is encoded and sent.
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
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.
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.