cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > JSON Support
Date Sat, 15 Aug 2009 01:19:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/CXF20DOC/JSON+Support">JSON
Support</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~dkulp">Daniel
Kulp</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <h1><a name="JSONSupport-JSONOverview"></a>JSON Overview</h1>
<p>JSON is a textual data format for data exchange. JSON stands for Javascript Object
Notation and, as the name implies, is itself Javascript. Here is a small sample:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
{
  <span class="code-quote">"customer"</span> : {
    <span class="code-quote">"name"</span> : <span class="code-quote">"Jane
Doe"</span>,
    <span class="code-quote">"company"</span> : <span class="code-quote">"Acme
Enterprises"</span>
}
</pre>
</div></div>

<p>One of the advantages of JSON is that is very easy for Javascript developers to use
- it simply needs to be evaluated and it immediately becomes a javascript object. For more
information on this see the <a href="http://json.org" rel="nofollow">JSON website</a>.</p>

<p>JSON is supported in CXF through <a href="http://jettison.codehaus.org" rel="nofollow">Jettison</a>.
Jettison is a StAX implementation that reads and writes JSON. Jettison intercepts calls to
read/write XML and instead read/writes JSON. </p>

<h1><a name="JSONSupport-JSON%2FXMLConventions"></a>JSON/XML Conventions</h1>
<p>To understand how to create a JSON service, you first need to understand how your
XML structures will be converted into the JSON format. JSON does not have many concepts found
in XML such as namespaces, attributes or entity references. Because of this we must adopt
<em>conventions</em> on how to convert between the two.</p>

<p>Jettison supports two conventions currently. These are explained in more detail in
the <a href="http://jettison.codehaus.org/User%27s+Guide" rel="nofollow">Jettison user's
guide</a>, but a quick summary of each follows.<br/>
1. The "mapped" convention. In this convention namespaces are mapped to json prefixes. For
instance, if you have a namespace "http://acme.com" you could map it to the "acme" prefix.
This means that the element &lt;customer xmlns="http://acme.com"&gt; would be mapped
to the "acme.customer" JSON tag.<br/>
2. The <a href="http://badgerfish.ning.com" rel="nofollow">BadgerFish</a> convention.
This convention provides a mapping of the full XML infoset to JSON. Attributes are represented
with an @ sign - i.e. "@attributeName" : "value". Textual data is represented with the "$"
as the tag. Example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
{ <span class="code-quote">"customer"</span> : { <span class="code-quote">"name"</span>
: { <span class="code-quote">"$"</span> : <span class="code-quote">"Jane
Doe"</span> } } }
</pre>
</div></div>

<h1><a name="JSONSupport-ConfiguringJettison"></a>Configuring Jettison</h1>
<p>Creating a Jettison service is like creating any other service, except that you set
a couple extra properties on your service's endpoint. First you'll want to create a service
and make sure it is working with XML before continuing here. Currently its recommended that
you use the <a href="/confluence/display/CXF20DOC/HTTP+Binding" title="HTTP Binding">HTTP
Binding</a> for your JSON endpoints as javascript developers will be more familiar with
the RESTful style of interaction. It is also easier for javascript developers as they will
not have to formulate a request for ever interaction.</p>

<h2><a name="JSONSupport-UsingServerFactoryBeans"></a>Using ServerFactoryBeans</h2>
<p>This example shows how to set up Jettison using a ServerFactoryBean, such as the
JaxWsServerFactoryBean. First you must create a properties HashMap and set the StAX XMLInputFactory
and XMLOutputFactory:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Map&lt;<span class="code-object">String</span>,<span class="code-object">Object</span>&gt;
properties = <span class="code-keyword">new</span> HashMap&lt;<span class="code-object">String</span>,<span
class="code-object">Object</span>&gt;();

<span class="code-comment">// Create a mapping between the XML namespaces and the JSON
prefixes.
</span><span class="code-comment">// The JSON prefix can be "" to specify that
you don't want any prefix.
</span>HashMap&lt;<span class="code-object">String</span>, <span
class="code-object">String</span>&gt; nstojns = <span class="code-keyword">new</span>
HashMap&lt;<span class="code-object">String</span>,<span class="code-object">String</span>&gt;();
nstojns.put(<span class="code-quote">"http:<span class="code-comment">//customer.acme.com"</span>,
<span class="code-quote">"acme"</span>);
</span>
MappedXMLInputFactory xif = <span class="code-keyword">new</span> MappedXMLInputFactory(nstojns);
properties.put(XMLInputFactory.class.getName(), xif);

MappedXMLOutputFactory xof = <span class="code-keyword">new</span> MappedXMLOutputFactory(nstojns);
properties.put(XMLOutputFactory.class.getName(), xof);
</pre>
</div></div>
<p>You must also tell CXF which Content-Type you wish to serve:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// Tell CXF to use a different Content-Type <span class="code-keyword">for</span>
the JSON endpoint
</span><span class="code-comment">// This should probably be application/json,
but text/plain allows
</span><span class="code-comment">// us to view easily in a web browser.
</span>properties.put(<span class="code-quote">"Content-Type"</span>, <span
class="code-quote">"text/plain"</span>);
</pre>
</div></div>
<p>Last, you'll want to actually create your service:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// Build up the server factory bean
</span>JaxWsServerFactoryBean sf = <span class="code-keyword">new</span>
JaxWsServerFactoryBean();
sf.setServiceClass(CustomerService.class);
<span class="code-comment">// Use the HTTP Binding which understands the Java Rest Annotations
</span>sf.setBindingId(HttpBindingFactory.HTTP_BINDING_ID);
sf.setAddress(<span class="code-quote">"http:<span class="code-comment">//localhost:8080/json"</span>);
</span>sf.setServiceBean(<span class="code-keyword">new</span> CustomerServiceImpl());

sf.setProperties(properties);

sf.create();
</pre>
</div></div>
     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/CXF20DOC/JSON+Support">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=33122&revisedVersion=5&originalVersion=4">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/CXF20DOC/JSON+Support?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message