<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements. See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership. The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License. You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied. See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
<meta http-equiv="content-type" content=
"text/html; charset=us-ascii" />
<title></title>
<meta name="AUTHOR" content="Isuru Suriarachchi" />
<meta name="CREATED" content="20070203;331600" />
<meta name="CHANGEDBY" content="Isuru Suriarachchi" />
<meta name="CHANGED" content="20070208;12031400" />
<style type="text/css">
/*<![CDATA[*/
        <!--
@page { size: 8.5in 11in; margin: 0.79in }
P { margin-bottom: 0.08in }
-->

/*]]>*/
</style>
</head>
<body>
<h1 class="title">JSON Support in Axis2</h1>
<p>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.</p>
<h3>What is JSON?</h3>
<p><a href="http://www.json.org/">JSON</a> (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.</p>
<p><font size="3">e.g. <font size="2">&lt;root&gt;&lt;test&gt;json
object&lt;/test&gt;&lt;/root&gt; ==
{{json object}}</font></font></p>
<p>When it comes to converting XML to JSON and vice versa, there
are two major conventions, one named "<a href=
"http://badgerfish.ning.com/">Badgerfish</a>" and the other,
Mapped. The main difference
between these two conventions exists in the way they map XML
namespaces into JSON.</p>
<p><font size="3">e.g. <font size="2">&lt;xsl:root
xmlns:xsl="http://foo.com"&gt;&lt;data&gt;my json
string&lt;/data&gt;&lt;/xsl:root&gt;</font></font></p>
<p>This XML string can be converted into JSON as follows.</p>
<p><b>Using Badgerfish</b></p>
<p><font size=
"2">{"xsl:root":{"@xmlns":{"xsl":"http://foo.com"},"data":{"$":"my
json string"}}}</font></p>
<p><b>Using Mapped</b></p>
<p>If we use the namespace mapping as http://foo.com -&gt; foo</p>
<p><font size="2">{"foo.root":{"data":"my json string"}}</font></p>
<p>JSON support is a new feature in <a href=
"http://ws.apache.org/axis2/">Apache Axis2/Java</a>. It will become
a crucial improvement in the future with applications like
JavaScript Web services.</p>
<h2>Why JSON Support for Axis2?</h2>
<p><a href="http://ws.apache.org/axis2/">Apache Axis2</a> 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?</p>
<p>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.</p>
<p>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.</p>
<p>For more details of this implementation architecture, refer to
the article <a href="http://wso2.org/library/768">"JSON Support for
Apache Axis2"</a></p>
<h2>How to use JSON in Axis2</h2>
<p>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 <a href=
"http://www.ietf.org/rfc/rfc4627.txt?number=4627">JSON RFC</a> ),
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.</p>
<h3>Step 1</h3>
<p>Map the appropriate MessageFormatter and OMBuilder with the
content type you are using in the axis2.xml file.</p>
<p>e.g.1: If you are using the
Mapped convention with the content
type application/json</p>
<pre>
        &lt;messageFormatters&gt;        
                &lt;messageFormatter contentType="application/json"
                                 class="org.apache.axis2.json.JSONMessageFormatter"/&gt;
                &lt;!-- more message formatters --&gt;
        &lt;/messageFormatters&gt;   
    
        &lt;messageBuilders&gt;
                &lt;messageBuilder contentType="application/json"
                                 class="org.apache.axis2.json.JSONOMBuilder"/&gt;
                &lt;!-- more message builders --&gt;
        &lt;/messageBuilders&gt;
</pre>
<p>e.g.2: If you are using the
Badgerfish convention with the
content type text/javascript</p>
<pre>
        &lt;messageFormatters&gt;        
                &lt;messageFormatter contentType="text/javascript"
                                 class="org.apache.axis2.json.JSONBadgerfishMessageFormatter"/&gt;
                &lt;!-- more message formatters --&gt;
        &lt;/messageFormatters&gt; 

        &lt;messageBuilders&gt;
                &lt;messageBuilder contentType="text/javascript"
                                 class="org.apache.axis2.json.JSONBadgerfishOMBuilder"/&gt;
                &lt;!-- more message builders --&gt;
        &lt;/messageBuilders&gt;
</pre>
<h3>Step 2</h3>
<p>On the client side, make the ConfigurationContext by reading the
axis2.xml in which the correct mappings are given.</p>
<p>e.g.</p>
<pre>
        File configFile = new File("test-resources/axis2.xml");
        configurationContext = ConfigurationContextFactory
                        .createConfigurationContextFromFileSystem(null, configFile.getAbsolutePath());
        ..........        
        ServiceClient sender = new ServiceClient(configurationContext, null);
</pre>
<h3>Step 3</h3>
<p>Set the <i>MESSAGE_TYPE</i> option with exactly the same content
type you used in the axis2.xml.</p>
<p>e.g. If you use the content type
application/json,</p>
<pre>
        Options options = new Options();        
        options.setProperty(Constants.Configuration.MESSAGE_TYPE, application/json);
        //more options
        //...................        

        ServiceClient sender = new ServiceClient(configurationContext, null);        
        sender.setOptions(options);
</pre>
<p>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.</p>
<p>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.</p>
<p>e.g.
<code>options.setProperty(Constants.Configuration.HTTP_METHOD,
Constants.Configuration.HTTP_METHOD_GET);</code></p>
<p>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.</p>
<p>e.g. Sample JSON request through HTTP GET. The JSON message is
encoded and sent.</p>
<p><code>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</code></p>
<h2>Tests and Samples</h2>
<h3>Integration Test</h3>
<p>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.</p>
<h3>Yahoo-JSON Sample</h3>
<p>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.</p>
<p>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.</p>
</body>
</html>