Author: veithen
Date: Wed May 23 21:50:01 2012
New Revision: 1342071
URL: http://svn.apache.org/viewvc?rev=1342071&view=rev
Log:
AXIS2-5158: Updated the documentation to explain how to configure an Axis2
service for use with Mapped JSON.
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=1342071&r1=1342070&r2=1342071&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:50:01 2012
@@ -60,10 +60,6 @@
<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
@@ -92,50 +88,51 @@
</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
+ type. <tt>application/json</tt> (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
+ "http://www.ietf.org/rfc/rfc4627.txt";>JSON RFC</a>),
+ <tt>text/javascript</tt> and
+ <tt>text/json</tt> are some of the commonly
+ used content types for JSON. Fortunately, in Axis2, the user
+ has the freedom of specifying the content type to use.</p>
+ <subsection name="Configuring axis2.xml">
+ <p>First of all, you need to map the appropriate message
formatters and builders to the
+ content type you are using in the <tt>axis2.xml</tt> file.
This applies both the to
+ client side and the server side.</p>
+ <p>E.g., 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
+ type <tt>application/json</tt>, add the following
declaration:</p>
+<pre><![CDATA[
+ <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>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>
+ content type <tt>text/javascript</tt>, add:</p>
+<pre><![CDATA[
+ <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>
+ <messageBuilders>
+ <messageBuilder contentType="text/javascript"
+ class="org.apache.axis2.json.JSONBadgerfishOMBuilder"/>
+ <!-- more message builders -->
+ </messageBuilders>
+]]></pre>
</subsection>
- <subsection name="Step 2">
+ <subsection name="Client-side configuration">
<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>
@@ -146,15 +143,13 @@
..........
ServiceClient sender = new ServiceClient(configurationContext, null);
</pre>
- </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);
+ options.setProperty(Constants.Configuration.MESSAGE_TYPE,
"application/json");
//more options
//...................
@@ -181,6 +176,26 @@ Constants.Configuration.HTTP_METHOD_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>
</subsection>
+ <subsection name="Server-side configuration">
+ <p>Since Badgerfish defines a 1-to-1 transformation between
JSON and XML, no additional configuration
+ is required on the server side if that convention is used. Any
service deployed into Axis2 will work
+ out of the box.</p>
+ <p>On the other hand, if the Mapped JSON convention is used,
then Axis2 needs to know the mappings
+ between XML namespaces and JSON "namespaces" in order to
translate messages from JSON
+ into XML representations and vice-versa. To use the Mapped
convention with a service deployed into Axis2,
+ add a <tt>xmlToJsonNamespaceMap</tt> property with these
mappings to the <tt>services.xml</tt> file for that service, as
+ shown in the following example:</p>
+<pre><![CDATA[
+<service name="...">
+ ...
+ <parameter name="xmlToJsonNamespaceMap">
+ <mapping xmlNamespace="http://example.org/foo"; jsonNamespace=""/>
+ <mapping xmlNamespace="http://example.org/bar"; jsonNamespace="bar"/>
+ </parameter>
+ ...
+</service>
+]]></pre>
+ </subsection>
</section>
<section name="Tests and Samples">
<subsection name="Integration Test">
@@ -188,7 +203,7 @@ HTTP/1.1</code>
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
+ used to return the incoming OMSourcedElement 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>
