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>
