Author: amilas
Date: Sat Sep  8 16:08:29 2012
New Revision: 1382325

URL: http://svn.apache.org/viewvc?rev=1382325&view=rev
Log:
adding new json documentation

Added:
    axis/axis2/java/core/trunk/src/site/xdoc/docs/json_gson_user_guide.xml
    axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support_gson.xml
Modified:
    axis/axis2/java/core/trunk/src/site/xdoc/docs/toc.xml

Added: axis/axis2/java/core/trunk/src/site/xdoc/docs/json_gson_user_guide.xml
URL: 
http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/src/site/xdoc/docs/json_gson_user_guide.xml?rev=1382325&view=auto
==============================================================================
--- axis/axis2/java/core/trunk/src/site/xdoc/docs/json_gson_user_guide.xml 
(added)
+++ axis/axis2/java/core/trunk/src/site/xdoc/docs/json_gson_user_guide.xml Sat 
Sep  8 16:08:29 2012
@@ -0,0 +1,115 @@
+<?xml version="1.0"?>
+<!--
+  ~ 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.
+  -->
+<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>How to configure Native approach and XML Stream API base 
approach</title>
+   </properties>
+
+    <body>
+        <h1>How to configure Native approach and XML Stream API base 
approach</h1>
+
+        <section name="How to use Native JSON support" id="native_approach" >
+            <p>If you need to expose your POJO services to support pure JSON 
requests as well as SOAP requests, then you
+                need to go through the following process to do that with this 
new feature introduced into Axis2 JSON
+                support.</p>
+
+            <p>Step 1 : Set in-out message receiver and in-only message 
receiver</p>
+
+            <p>You need to set 
<code>org.apache.axis2.json.gson.rpc.JsonRpcMessageReceiver</code> with
+                <code>http://www.w3.org/ns/wsdl/in-out</code> message exchange 
pattern. Also with <code>http://www.w3.org/ns/wsdl/in-only</code>
+                message exchange pattern, set 
<code>org.apache.axis2.json.gson.rpc.JsonInOnlyRPCMessageReceiver</code>.  </p>
+
+            <p>eg.</p>
+            <pre><![CDATA[
+            <messageReceivers>
+                <messageReceiver mep="http://www.w3.org/ns/wsdl/in-out";
+                                 
class="org.apache.axis2.json.gson.rpc.JsonRpcMessageReceiver"/>
+                <messageReceiver mep="http://www.w3.org/ns/wsdl/in-only";
+                                 
class="org.apache.axis2.json.gson.rpc.JsonInOnlyRPCMessageReceiver"/>
+            </messageReceivers>
+            ]]></pre>
+            <p>Step 2: Set message builder and message formatter</p>
+
+            <p>you need to edit axis2.xml in <code>[AXIS2_HOME]/conf/ 
</code>directory, to set <code>org.apache.axis2.json.gson.JsonBuilder</code>
+                as message builder with application/json contentType to handle 
JSON requests and
+                <code>org.apache.axis2.json.gson.JsonFormatter</code> as 
message formatter with application/json
+                contentType to write response to wire as JSON format.</p>
+
+            <p>eg.</p>
+            <pre><![CDATA[
+                  <messageBuilder contentType="application/json"
+                                  
class="org.apache.axis2.json.gson.JsonBuilder" />
+
+                  <messageFormatter contentType="application/json"
+                                    
class="org.apache.axis2.json.gson.JsonFormatter" />
+           ]]></pre>
+        </section>
+
+        <section name="How to use XML stream API based approach" 
id="xml_stream_api_base_approach" >
+
+            <p>You can use this XML Stream API based approach with databinding 
services like ADB and xmlbeans as well
+                as with normal POJO services. Follow the steps mentioned below 
to use this new feature introduced into
+                Axis2 JSON support.</p>
+
+            <p>Step 1 : Set message builder and message formatter</p>
+
+            <p>You need to edit axis2.xml in <code>[AXIS2_HOME]/conf/</code> 
directory, to set <code>org.apache.axis2.json.gson.JsonBuilder</code>
+                as message builder with <code>application/json</code> 
contentType to handle JSON requests and,
+                <code>org.apache.axis2.json.gson.JsonFormatter</code> as 
message formatter with <code>application/json</code> contentType to
+                write response to wire as JSON format.</p>
+
+            <p>eg.</p>
+            <pre><![CDATA[
+                <messageBuilder contentType="application/json"
+                                class="org.apache.axis2.json.gson.JsonBuilder" 
/>
+
+                <messageFormatter contentType="application/json"
+                                  
class="org.apache.axis2.json.gson.JsonFormatter" />
+                        ]]>
+            </pre>
+
+            <p>Step 2: Set inflow handlers</p>
+
+            <p>Remove RequestURIOperationDispatcher handler from dispatch 
phase and place it as the last handler in
+                transport phase. Now add new JSONMessageHandler after the 
RequestURIOperationDispatcher. Finally
+                transport phase would be like following,</p>
+
+            <pre><![CDATA[
+            <phaseOrder type="InFlow">
+                <!--  System predefined phases  -->
+                <phase name="Transport">
+                    -------------
+                    <handler name="RequestURIOperationDispatcher"
+                             
class="org.apache.axis2.dispatchers.RequestURIOperationDispatcher"/>
+                    <handler name="JSONMessageHandler"
+                             
class="org.apache.axis2.json.gson.JSONMessageHandler" />
+                </phase>
+                ------------
+            </phaseOrder>
+                    ]]>
+            </pre>
+
+        </section>
+
+    </body>
+</document>

Added: axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support_gson.xml
URL: 
http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support_gson.xml?rev=1382325&view=auto
==============================================================================
--- axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support_gson.xml (added)
+++ axis/axis2/java/core/trunk/src/site/xdoc/docs/json_support_gson.xml Sat Sep 
 8 16:08:29 2012
@@ -0,0 +1,191 @@
+<?xml version="1.0"?>
+<!--
+  ~ 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.
+  -->
+<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>New JSON support in Apache Axis2</title>
+   </properties>
+
+    <body>
+        <h1>New JSON support in Apache Axis2</h1>
+        <p>This documentation explains how the existing JSON support in Apache 
Axis2 have been improved with two new
+            methods named, Native approach and XML stream API based approach. 
Here it initially explains about the
+            drawbacks of the old JSON support, how to overcome those drawbacks 
with the new approaches and, how to use
+            those approaches to send pure JSON objects without converting it 
to any XML representations. XML Stream API
+            based approach addresses the namespace problem with pure JSON 
support, and provides a good solution for
+            that.</p>
+
+        <section name="Introduction">
+
+            <p>Apache Axis2 is an efficient third generation SOAP processing 
web services engine. JSON (JavaScript
+                Object Notation) is a lightweight data-interchange format and, 
an alternative for XML which is easily
+                human readable and writable as well as it can be parsed and 
generated easily for machines.</p>
+
+            <p>The existing JSON implementation in Apache Axis2/Java supports 
badgerfish format of the JSON object,
+                which is an XML representation of JSON object. With this 
approach, it first completely converts the
+                badgerfish JSON string to the relevant XML format in the 
server side and, treats it as a normal SOAP
+                message. The current JSON implementation also supports Mapped 
JSON, which is another XML representation
+                of the JSON object, if we set xmlToJsonNamespaceMap parameter 
in the services.xml file of the service.
+                The main problem with Mapped JSON format is, at the client 
side it is not aware of the namespaces which
+                is used in server side to validate the request. Therefore with 
current implementation, it is required
+                to do modifications to the existing services to use this 
mapped format support. The current JSON
+                implementations of Axis2 are slower than the existing SOAP 
support too. Therefore the existing JSON
+                support doesn't expose its advantages at all.</p>
+
+            <p>However this JSON support can be improved to support pure JSON 
objects without using any format to
+                convert it into a XML, as JSON is a light weighted alternative 
to XML. Thre are two new approaches
+                have been used with google-gson library, a rich library to 
convert a JSON string to a Java object
+                and vice-versa, in order to improve the existing JSON support 
in Apache Axis2/java.</p>
+
+            <p>Gson[1] is a Java library that can be used to convert Java 
Objects into their JSON representation.
+                It can be also used to convert a JSON string to an equivalent 
Java object. Gson can work with arbitrary
+                Java objects including pre-existing objects for which you do 
not have the source code.</p>
+
+            <p>There are a few open source projects, capable of converting 
Java objects into JSON. However, most of
+                them require to place Java annotations in all classes; 
something that cannot be done if we do not have
+                access to the source code. Most of them also do not fully 
support the use of Java Generics. Gson has
+                considered both of these facts as very important design goals 
and, the following are some of the
+                advantages of using Gson to convert JSON into Java objects and 
vice-versa.</p>
+
+            <ul>
+                <li>It provides simple toJSON() and fromJSON() methods to 
convert Java objects into JSON objects and
+                    vice-versa.</li>
+                <li>It allows pre-existing unmodifiable objects to be 
converted into/from JSON objects.</li>
+                <li>It has the extensive support of Java Generics.</li>
+                <li>It allows custom representations for objects.</li>
+                <li>It supports arbitrarily complex objects (with deep 
inheritance hierarchies and extensive use of
+                    generic types).</li>
+            </ul>
+
+            <p>As mentioned above, these two new approaches have been 
introduced to overcome the above explained
+                problems in the existing JSON implementation (Badgerfish and 
Mapped) of Axis2. The first one, the
+                Native approach, has been implemented with completely pure 
JSON support throughout the axis2 message
+                processing process while with the second approach which is XML 
stream API based approach, an
+                XMLStreamReader/XMLStreamWriter implementation using 
google-gson with the help of XMLSchema is being
+                implemented. The detailed description on the two approaches is 
given out in the next sections of the
+                documentation.</p>
+        </section>
+
+        <section name="Native Approach" id="native_approach" >
+
+            <p>With this approach you can expose your POJO service to accept 
pure JSON request other than converting to
+                any representation or format. You just need to send a valid 
JSON string request to the service url and,
+                in the url you should have addressed the operation as well as 
the service. Because in this scenario Axis2
+                uses URI based operation dispatcher to dispatch the correct 
operation. in
+                <a href="json_gson_user_guide.html#native_approach">here</a> 
you can
+                find the complete user guide for this native approach.</p>
+
+            <p>The Native approach is being implemented to use pure JSON 
throughout the axis2 message processing
+                process. In Axis2 as the content-type header is used to 
specify the type of data in the message body,
+                and depending on the content type, the wire format varies. 
Therefore, we need to have a mechanism to
+                format the message depending on content type. We know that any 
kind of message is represented in Axis2
+                using AXIOM, and when we serialize the message, it needs to be 
formatted based on content type.
+                MessageFormatters exist to do that job for us. We can specify 
MessageFormatters along with the content
+                type in axis2.xml. On the other hand, a message coming into 
Axis2 may or may not be XML, but for it to
+                go through Axis2, an AXIOM element needs to be created. As a 
result, MessageBuilders are employed to
+                construct the message depending on the content type.</p>
+
+            <p>After building the message it gets pass through AXIS2 execution 
chain to execute the message. If the
+                message has gone through the execution chain without having 
any problem, then the engine will hand over
+                the message to the message receiver in order to do the 
business logic invocation. After this, it is up
+                to the message receiver to invoke the service and send the 
response. So according to the Axis2
+                architecture to accomplish this approach it is required to 
implement three main components, a
+                MessageBuilder, a MessageReceiver and a MessageFormatter, 
where in this Native implementation those are
+                JSONBuilder, JSONRPCMessageReceiver and JSONFomatter, to 
handle the pure JSON request and invoke the
+                service and return a completely pure JSON string as a 
response. In the builder, it creates and returns
+                a dummy SOAP envelop to process over execution chain, while 
storing input json stream and a boolean
+                flag IS_JSON_STREAM as a property of input MessageContext. The 
next one is JSONRPCMessageReceiver which
+                is an extended subclass of RPCMessageReceiver. In here it 
checks IS_JSON_STREAM property value, if it is
+                'true' then it processes InputStream stored in input 
MessageContext, using JsonReader in google-gson API.
+                Then it invokes request service operation by Gson in 
google-gson API which uses Java reflection to invoke
+                the service. To write the response to wire, it stores the 
returned object and return java bean type, as
+                properties of output MessageContext. If IS_JSON_STREAM is 
'false' or null then it is handed over to its
+                super class RPCMessageReceiver, in order to handle the 
request. This means, using JSONRPCMessageReceiver
+                as the message receiver of your service you can send pure JSON 
messages as well as SOAP requests too.
+                There is a JSONRPCInOnly-MessageReceiver which extends 
RPCInOnlyMessageReceiver class, to handle In-Only
+                JSON requests too. In JSONformatter it gets return object and 
the java bean type, and writes response as
+                a pure JSON string to the wire using JsonWriter in google-gson 
API. The native approach doesn’t support
+                namespaces. If you need namespace support with JSON then go 
through XML Stream API based approach.</p>
+
+
+        </section>
+
+        <section name="XML Stream API Base Approach" 
id="xml_stream_api_base_approach" >
+
+
+            <p> As you can see the native approach can only be used with POJO 
services but if you need to expose your
+                services which is generated by using ADB or xmlbeans 
databinding then you need to use this XML Stream
+                API based approach. With this approach you can send pure JSON 
requests to the relevant services.
+                Similar to the native approach you need to add operation name 
after the service name to use uri based
+                operation dispatch to dispatch the request operation.
+                <a 
href="json_gson_user_guide.html#xml_stream_api_base_approach">Here</a> you can 
see the user guide
+                for this XML Stream API based approach.</p>
+
+            <p>As mentioned in Native approach, Apache Axis2 uses AXIOM to 
process XML. If it can be implement a way to
+                represent JSON stream as an AXIOM object which provides 
relevant XML infoset while processing JSON
+                stream on fly, that would be make JSON, in line with Axis2 
architecture and will support the services
+                which have written on top of xmlstream API too.</p>
+
+            <p>There are a few libraries like jettison , Json-lib etc. which 
already provide this
+                XMLStreaReader/XMLStreamWriter interfaces for JSON. There is 
no issue in converting JSON to XML, as we
+                can use jettison for that, but when it comes to XML to JSON 
there is a problem. How could we identify
+                the XML element which represent JSON array type? Yes we can 
identify it if there is two or more
+                consecutive XML elements as jettison does, but what happen if 
the expected JSON array type has only one
+                value? Then there is only one XML element. If we use Json-lib 
then xml element should have an attribute
+                name called "class" value to identify the type of JSON. As you 
can see this is not a standard way and
+                we cannot use this with Axis2 as well. Hence we can't use 
above libraries to convert XML to JSON
+                accurately without distort expected JSON string even it has 
one value JSON array type.</p>
+
+            <p>Therefore with this new improvement Axis2 have it's own way to 
handle incoming JSON requests and
+                outgoing JSON responses. It uses GsonXMLStreamReader and 
GsonXMLStreamWriter which are implementations
+                of XMLStreamReader/XMLStreamWriter, to handle this requests 
and responses. To identify expected request
+                OMElement structure and namespace uri, it uses XmlSchema of 
the request and response operations. With
+                the XmlSchema it can provide accurate XML infoset of the JSON 
message. To get the relevant XMLSchema
+                for the operation, it uses element qname of the message. At 
the MessageBuilder level Axis2 doesn't know
+                the element qname hence it can't get the XmlSchema of the 
operation. To solve this issue Axis2 uses a
+                new handler call JSONMessageHandler, which executes after the 
RequestURIOperationDispatcher handler.
+                In the MessageBuilder it creates GsonXMLStreamReader parsing 
JsonReader instance which is created using
+                inputStream and stores it in input MessageContext as a message 
property and returns a default SOAP
+                envelop. Inside the JSONMessageHandler it checks for this 
GsonXMLStreamReader property, if it is not
+                null and messageReceiver of the operation is not an instance 
of JSONRPCMessageReceiver, it gets the
+                element qname and relevant XMLSchema list from the input 
MessageContext and pass it to
+                GsonXMLStreamReader. After that it creates StAXOMBuilder 
passing this GsonXMLStreamReader as the
+                XMLStreamReader and get the document element. Finally set this 
document element as child of default
+                SOAP body. If Axis2 going to process XMLSchema for every 
request this would be a performance issue.
+                To solve this, Axis2 uses an intermediate 
representation(XmlNode) of operation XmlSchema list and store
+                it inside the ConfigurationContext with element qname as a 
property to use it for a next request
+                which will come to the same operation. Hence it only processes 
XmlSchema only once for each operation.</p>
+
+            <p>Same thing happens in the JsonFormatter, as it uses 
GsonXMLStreamWriter to write response to wire and
+                uses intermediate representation to identify the structure of 
outgoing OMElement. As we know the
+                structure here we can clearly identify expected JSON response. 
Even expected JSON string have a JSON
+                Array type which has only one value. </p>
+
+            <p>In addition, XML Stream API based approach supports namespace 
uri where it get namespaces from the
+                operation XMLSchema and provides it when it is asked. </p>
+
+
+
+        </section>
+
+
+    </body>
+</document>
\ No newline at end of file

Modified: axis/axis2/java/core/trunk/src/site/xdoc/docs/toc.xml
URL: 
http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/src/site/xdoc/docs/toc.xml?rev=1382325&r1=1382324&r2=1382325&view=diff
==============================================================================
--- axis/axis2/java/core/trunk/src/site/xdoc/docs/toc.xml (original)
+++ axis/axis2/java/core/trunk/src/site/xdoc/docs/toc.xml Sat Sep  8 16:08:29 
2012
@@ -102,8 +102,18 @@ Transport</a></li>
 <li><a href="WS_policy.html">WS-Policy
 Support</a></li>
 <li><a href="rest-ws.html">REST Support</a></li>
-<li><a href="json_support.html">JSON
-Support</a></li>
+<li>JSON support
+    <ul>
+    <li>23.1<a href="json_support.html">JSON support with Mapped/Badgerfish 
formats</a></li>
+    <li>23.2<a href="json_support_gson.html">Pure JSON Support</a>
+    <ul>
+        <li><a href="json_support_gson.html#native_approach">Native 
Approach</a></li>
+        <li><a href="json_support_gson.html#xml_stream_api_base_approach">XML 
Stream API Base Approach</a></li>
+        <li><a href="json_gson_user_guide.html">User Guide</a></li>
+    </ul>
+    </li>
+</ul>
+</li>
 <li><a href="corba-deployer.html">Exposing CORBA Services as Web 
Services</a></li>
 <li><a href="ejb-provider.html">Guide to using
 EJB Provider in Axis2</a></li>


Reply via email to