<!--
  ~ 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.
  -->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
  "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
  <meta http-equiv="content-type" content=""/>
  <title>Apache Axis2 JSON and REST with Spring Boot User's Guide</title>
</head>

<body dir="ltr" lang="en-US">
<a name="_Toc96697849" id="_Toc96697849"></a>

<h1 align="center">Apache Axis2 JSON and REST with Spring Boot User's Guide</h1>

<p>This guide will help you get started with Axis2 and JSON via REST, using 
Spring Security with Spring Boot!  It gives a detailed description on how to write 
JSON based REST Web services and also Web service clients via JSON and Curl, how to 
write a custom login, and how to use them in a token based Web service that also helps 
prevent cross site scripting (XSS). 
</p>
<a name="Introduction"></a>

<h2>Introduction</h2>

<p>This user guide is written based on the Axis2 Standard Binary
Distribution. The Standard Binary Distribution can be directly <a
href="../download.cgi">downloaded</a> or built using
the Source Distribution. If
you choose the latter, then the <a href="installationguide.html">Installation
Guide</a> will instruct you on how to build Axis2 Standard Binary
Distribution using the source.</p>

<p>The source code for this guide provides a pom.xml for an entire demo application built by maven.
</p>

<p>Please note that Axis2 is an open-source effort. If you feel the code
could use some new features or fixes, please get involved and lend us a hand!
The Axis developer community welcomes your participation.</p>

<p>Let us know what you think! Send your feedback to "<a
href="mailto:java-user@axis.apache.org?subject=[Axis2]">java-user@axis.apache.org</a>".
(Subscription details are available on the <a href="../mail-lists.html">Axis2 site</a>.) Kindly
prefix the subject of the mail with [Axis2].</p>

<h2>Getting Started</h2>

<p>This user guide explains how to write and deploy a
new JSON and REST based Web Service using Axis2, and how to write a Web Service client 
using JSON with Curl.
</p>

<p>All the sample code mentioned in this guide is located in
the <b>"samples/userguide/src/springbootdemo"</b> directory of <a
href="../download.cgi">Axis2 standard binary
distribution</a>.</p>
<p>
This quide supplies a pom.xml for building an exploded WAR with Spring Boot - 
however this WAR does not have an embedded web server such as Tomcat. 
</p>
<p>
The testing was carried out on Wildfly, by installing the WAR in its app server. 
</p>
<p>Please deploy the result of the maven build via 'mvn clean install', axis2-json-api.war, into your servlet container and ensure that it installs without any errors.</p>

<h2>Creating a New Web Service</h2>

<p>
Areas out of scope for this guide are JWT and JWE for token generation and validation, 
since they require elliptic curve cryptography. A sample token that is not meant for 
production is generated in this demo - with the intent that the following standards
should be used in its place. This demo merely shows a place to implement these
standards.
</p>
<p>
https://datatracker.ietf.org/doc/html/rfc7519
https://datatracker.ietf.org/doc/html/rfc7516
</p>
<p>
Tip: com.nimbusds is recommended as an open-source Java implementation of these 
standards, for both token generation and validation.
</p>
<p>
DB operations are also out of scope. There is a minimal DAO layer for authentication. 
Very limited credential validation is done. 
</p>
<p>
The NoOpPasswordEncoder Spring class included in this guide is meant for demos
and testing only. Do not use this code as is in production.
</p>
<p>
This guide provides two JSON based web services, LoginService and TestwsService.
</p>
<p>
The login, if successful, will return a simple token not meant for anything beyond demos.
The intent of this guide is to show a place that the JWT and JWE standards can be 
implemented.
</p>
<p>
Axis2 JSON support is via POJO Objects. LoginRequest and LoginResponse are coded in the LoginService as the names would indicate. 
</p>
<p>
Also provided is a test service, TestwsService. It includes two POJO Objects as would
be expected, TestwsRequest and TestwsResponse. This service attempts to return 
a String with some Javascript, that is HTML encoded by Axis2 and thereby
eliminating the possibility of a Javascript engine executing the response i.e. a 
reflected XSS attack. 
</p>
<p>
Concerning Spring Security and Spring Boot, the Axis2Application class that 
extends SpringBootServletInitializer as typically done utilizes 
List<SecurityFilterChain> as a binary choice; A login url will match, otherwise invoke 
JWTAuthenticationFilter. All URL's to other services besides the login, will proceed 
after JWTAuthenticationFilter verifies the token.
</p>
<p>
The JWTAuthenticationFilter class expects a token from the web services JSON client in 
the form of "Authorization: Bearer mytoken".
</p>
<p>
The Axis2WebAppInitializer class supplied in this guide, is the config class 
that registers AxisServlet with spring boot.
</p>
<p>
Axis2 web services are installed via a WEB-INF/services directory that contains
files with an .aar extention for each service. These aar files are similar to
jar files, and contain a services.xml that defines the web service behavior. 
The pom.xml supplied in this guide generates these files.
</p>
<p>
Tip: don't expose methods in your web services that are not meant to be exposed, 
such as getters and setters. Axis2 determines the avaliable methods by reflection.
For JSON, the message name at the start of the JSON received by the Axis2 server 
defines the Axis2 operation to invoke.  It is recommended that only one method per 
class be exposed as a starting point. The place to add method exclusion is the 
services.xml file: 
</p>
<pre>
    &lt;message name="requestMessage"&gt;
    &lt;excludeOperations&gt;
        &lt;operation>setMyVar&lt;</operation&gt;
    &lt;/excludeOperations&gt;
</pre>
<p>
The axis2.xml file can define Moshi or GSON as the JSON engine. GSON was the original 
however development has largely ceased. Moshi is very similar and is widely considered 
to be the superior implementation in terms of performance. GSON will likely continue to
be supported in Axis2 because it is helpful to have two JSON implementations to compare 
with for debugging.  
</p>
<p>
JSON based web services in the binary distribution of axis2.xml are not enabled by 
default. See the supplied axis2.xml of this guide, and note the places were it has 
"moshi". Just replace "moshi" with "gson" as a global search and replace to switch to 
GSON. 
</p>
<p>
Axis2 web services that are JSON based must be invoked from a client that sets an
HTTP header as "Content-Type: application/json". In order for axis2 to properly
handle JSON requests, this header behavior needs to be defined in the file
WEB-INF/conf/axis2.xml.
</p>
<pre>
    &lt;message name="requestMessage"&gt;
        &lt;messageFormatter contentType="application/json"
                          class="org.apache.axis2.json.moshi.JsonFormatter"/&gt;
</pre>
<p>
Other required classes for JSON in the axis2.xml file include JsonRpcMessageReceiver,
JsonInOnlyRPCMessageReceiver, JsonBuilder, and JSONMessageHandler.
</p>
<p>
Invoking the client for a login that returns a token can be done as follows:
</p>
<p>
curl -v -H "Content-Type: application/json" -X POST --data @/home/myuser/login.dat http://localhost:8080/axis2-json-api/services/loginService
</p>
<p>
Where the contents of /home/myuser/login.dat are:
</p>
<p>
{"doLogin":[{"arg0":{"email":java-dev@axis.apache.org,"credentials":userguide}}]}
</p>
<p>
Response: 
</p>
<p>
{"response":{"status":"OK","token":"95104Rn2I2oEATfuI90N","uuid":"99b92d7a-2799-4b20-b029-9fbd6108798a"}}
</p>
<p>
Invoking the client for a Test Service that validates a sample token can be done as 
follows:
</p>
<p>
curl -v -H "Authorization: Bearer I2SpAHWrU5gYbGNwNNKg" -H "Content-Type: application/json" -X POST --data @/root/test.dat http://localhost:8080/axis2-json-api/services/testws'
</p>
<p>
Where the contents of /home/myuser/test.dat are below. arg0 is the var name 
and is used by Axis2 as part of the reflection based code:
</p>
<p>
{"doTestws":[{"arg0":{"messagein":hello}}]}
</p>
<p>
Response, HTML encoded to prevent XSS. For the escaped results see ./src/site/xdoc/docs/json-springboot-userguide.xml.
</p>
<p>
{"response":{"messageout":"&lt;script xmlns=\"http://www.w3.org/1999/xhtml\"&gt;alert('Hello');&lt;/script&gt; \"&gt;","status":"OK"}}
</p>
</body>
</html>