v1.5beta1/modules/documentation/xdocs/@axis2_version_dir@/json_support.xml - axis-axis2-java-core - Git at Google

 <!--
   ~ 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>
	<!--
	~ 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"><root><test>json
	object</test></root> ==
	{{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 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>
	<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 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>