You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-commits@axis.apache.org by ve...@apache.org on 2012/05/23 23:21:25 UTC
svn commit: r1342053 -
/axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support.xml
Author: veithen
Date: Wed May 23 21:21:24 2012
New Revision: 1342053
URL: http://svn.apache.org/viewvc?rev=1342053&view=rev
Log:
Converted json_support.xml from pseudo-XDoc to XDoc.
Modified:
axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support.xml
Modified: axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support.xml
URL: http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support.xml?rev=1342053&r1=1342052&r2=1342053&view=diff
==============================================================================
--- axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support.xml (original)
+++ axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support.xml Wed May 23 21:21:24 2012
@@ -1,3 +1,4 @@
+<?xml version="1.0"?>
<!--
~ Licensed to the Apache Software Foundation (ASF) under one
~ or more contributor license agreements. See the NOTICE file
@@ -16,108 +17,94 @@
~ 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://www.sklar.com/badgerfish/">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=
-"../index.html">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="../index.html">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>
+<document xmlns="http://maven.apache.org/XDOC/2.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
+ <properties>
+ <title>JSON Support in Axis2</title>
+ </properties>
+ <body>
+ <h1>JSON Support in Axis2</h1>
+ <section name="Introduction">
+ <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>
+ </section>
+ <section name="What is JSON?">
+ <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://www.sklar.com/badgerfish/">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=
+ "../index.html">Apache Axis2/Java</a>. It will become
+ a crucial improvement in the future with applications like
+ JavaScript Web services.</p>
+ </section>
+ <section name="Why JSON Support for Axis2?">
+ <p><a href="../index.html">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>
+ </section>
+ <section name="How to use JSON in Axis2">
+ <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>
+ <subsection name="Step 1">
+ <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"
@@ -131,9 +118,9 @@ type application/json</p>
<!-- more message builders -->
</messageBuilders>
</pre>
-<p>e.g.2: If you are using the
-Badgerfish convention with the
-content type text/javascript</p>
+ <p>e.g.2: If you are using the
+ Badgerfish convention with the
+ content type text/javascript</p>
<pre>
<messageFormatters>
<messageFormatter contentType="text/javascript"
@@ -147,10 +134,11 @@ content type text/javascript</p>
<!-- 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>
+ </subsection>
+ <subsection name="Step 2">
+ <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
@@ -158,11 +146,12 @@ axis2.xml in which the correct mappings
..........
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>
+ </subsection>
+ <subsection name="Step 3">
+ <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);
@@ -172,48 +161,53 @@ application/json,</p>
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.
+ <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.</p>
<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
+Constants.Configuration.HTTP_METHOD_GET);</code>
+ <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>
+<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>
+HTTP/1.1</code>
+ </subsection>
+ </section>
+ <section name="Tests and Samples">
+ <subsection name="Integration Test">
+ <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>
+ </subsection>
+ <subsection name="Yahoo-JSON Sample">
+ <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>
+ </subsection>
+ </section>
+ </body>
+</document>