xdocs/@axis2_version_dir@/json_support.html - axis-axis2-java-core - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
   <meta http-equiv="content-type" content="text/html; charset=UTF-8">
   <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">
         <!--
 @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 to it should be used. 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 it is more lightweight and
 easily readable. It is based on a subset of 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; == {“root”:{“test”:”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 implementation 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 not 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
 easily by machines than in the case of 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 method is used as the default to send JSON messages through
 Axis2, if the HTTP method is not 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
 “Mapped” 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 are good examples of using JSON support for Axis2.
 You can understand the architecture of JSON support implementation in Axis2
 by looking at these samples.</p>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>
	<head>
	<meta http-equiv="content-type" content="text/html; charset=UTF-8">
	<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">
	<!--
	@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 to it should be used. 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 it is more lightweight and
	easily readable. It is based on a subset of 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"><root><test>json
	object</test></root> == {“root”:{“test”:”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"><xsl:root
	xmlns:xsl="http://foo.com"><data>my json
	string</data></xsl:root></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 -> foo</p>

	<p><font size="2">{"foo.root":{"data":"my json string"}}</font></p>

	<p>JSON support implementation 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 not 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
	easily by machines than in the case of 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> <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></pre>

	<p>e.g.2: If you are using the “Badgerfish” convention with the content
	type “text/javascript”</p>
	<pre> <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></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 method is used as the default to send JSON messages through
	Axis2, if the HTTP method is not 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
	“Mapped” 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 are good examples of using JSON support for Axis2.
	You can understand the architecture of JSON support implementation in Axis2
	by looking at these samples.</p>
	</body>
	</html>