axis2/java/core/docs/json-springboot-userguide.html - axis-site - Git at Google

 <!DOCTYPE html>


 <!--
  | Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/docs/json-springboot-userguide.xml at 2025-03-05
  | Rendered using Apache Maven Fluido Skin 2.0.0-M11
 -->
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
     <title>Apache Axis2 JSON and REST with Spring Boot 3 User&apos;s Guide – Apache Axis2</title>
     <link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M11.min.css" />
     <link rel="stylesheet" href="../css/site.css" />
     <link rel="stylesheet" href="../css/print.css" media="print" />
     <script src="../js/apache-maven-fluido-2.0.0-M11.min.js"></script>
 <meta http-equiv="content-type" content="" />  </head>
   <body>
     <div class="container-fluid container-fluid-top">
       <header>
         <div id="banner">
           <div class="pull-left"><div id="bannerLeft"><h1><a href="http://www.apache.org/"><img class="class java.lang.Object" src="http://www.apache.org/images/asf_logo_wide.png" /> Apache Axis2</a></h1></div></div>
           <div class="pull-right"><div id="bannerRight"><h1><a href=".././"><img class="class java.lang.Object" src="../images/axis.jpg" /></a></h1></div></div>
           <div class="clear"><hr/></div>
         </div>

         <div id="breadcrumbs">
           <ul class="breadcrumb">
         <li id="publishDate">Last Published: 2025-03-04<span class="divider">|</span>
 </li>
           <li id="projectVersion">Version: 2.0.0<span class="divider">|</span></li>
       <li><a href="http://www.apache.org" class="externalLink">Apache</a><span class="divider">/</span></li>
       <li><a href="../index.html">Axis2/Java</a><span class="divider">/</span></li>
     <li class="active">Apache Axis2 JSON and REST with Spring Boot 3 User&apos;s Guide</li>
           </ul>
         </div>
       </header>
       <div class="row-fluid">
         <header id="leftColumn" class="span2">
           <nav class="well sidebar-nav">
   <ul class="nav nav-list">
    <li class="nav-header">Axis2/Java</li>
     <li><a href="../index.html">Home</a></li>
     <li><a href="../download.html">Downloads</a></li>
     <li><a href="javascript:void(0)"><span class="icon-chevron-down"></span>Release Notes</a>
      <ul class="nav nav-list">
       <li><a href="../release-notes/1.6.1.html">1.6.1</a></li>
       <li><a href="../release-notes/1.6.2.html">1.6.2</a></li>
       <li><a href="../release-notes/1.6.3.html">1.6.3</a></li>
       <li><a href="../release-notes/1.6.4.html">1.6.4</a></li>
       <li><a href="../release-notes/1.7.0.html">1.7.0</a></li>
       <li><a href="../release-notes/1.7.1.html">1.7.1</a></li>
       <li><a href="../release-notes/1.7.2.html">1.7.2</a></li>
       <li><a href="../release-notes/1.7.3.html">1.7.3</a></li>
       <li><a href="../release-notes/1.7.4.html">1.7.4</a></li>
       <li><a href="../release-notes/1.7.5.html">1.7.5</a></li>
       <li><a href="../release-notes/1.7.6.html">1.7.6</a></li>
       <li><a href="../release-notes/1.7.7.html">1.7.7</a></li>
       <li><a href="../release-notes/1.7.8.html">1.7.8</a></li>
       <li><a href="../release-notes/1.7.9.html">1.7.9</a></li>
       <li><a href="../release-notes/1.8.0.html">1.8.0</a></li>
       <li><a href="../release-notes/1.8.1.html">1.8.1</a></li>
       <li><a href="../release-notes/1.8.2.html">1.8.2</a></li>
       <li><a href="../release-notes/2.0.0.html">2.0.0</a></li>
      </ul></li>
     <li><a href="../modules/index.html">Modules</a></li>
     <li><a href="../tools/index.html">Tools</a></li>
    <li class="nav-header">Documentation</li>
     <li><a href="../docs/toc.html">Table of Contents</a></li>
     <li><a href="../docs/installationguide.html">Installation Guide</a></li>
     <li><a href="../docs/quickstartguide.html">QuickStart Guide</a></li>
     <li><a href="../docs/userguide.html">User Guide</a></li>
     <li><a href="../docs/jaxws-guide.html">JAXWS Guide</a></li>
     <li><a href="../docs/pojoguide.html">POJO Guide</a></li>
     <li><a href="../docs/spring.html">Spring Guide</a></li>
     <li><a href="../docs/webadminguide.html">Web Administrator&apos;s Guide</a></li>
     <li><a href="../docs/migration.html">Migration Guide (from Axis1)</a></li>
    <li class="nav-header">Resources</li>
     <li><a href="../faq.html">FAQ</a></li>
     <li><a href="../articles.html">Articles</a></li>
     <li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink">Wiki</a></li>
     <li><a href="../refLib.html">Reference Library</a></li>
     <li><a href="../apidocs/index.html">Online Java Docs</a></li>
    <li class="nav-header">Get Involved</li>
     <li><a href="../overview.html">Overview</a></li>
     <li><a href="../git.html">Checkout the Source</a></li>
     <li><a href="../mail-lists.html">Mailing Lists</a></li>
     <li><a href="../release-process.html">Release Process</a></li>
     <li><a href="../guidelines.html">Developer Guidelines</a></li>
     <li><a href="../siteHowTo.html">Build the Site</a></li>
    <li class="nav-header">Project Information</li>
     <li><a href="../team-list.html">Project Team</a></li>
     <li><a href="../issue-tracking.html">Issue Tracking</a></li>
     <li><a href="https://github.com/apache/axis-axis2-java-core" class="externalLink">Source Code</a></li>
     <li><a href="../thanks.html">Acknowledgements</a></li>
    <li class="nav-header">Apache</li>
     <li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a></li>
     <li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsorship</a></li>
     <li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a></li>
     <li><a href="http://www.apache.org/security/" class="externalLink">Security</a></li>
   </ul>
           </nav>
           <div class="well sidebar-nav">
             <div id="poweredBy">
               <div class="clear"></div>
               <div class="clear"></div>
 <a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
             </div>
           </div>
         </header>
         <main id="bodyColumn" class="span10">
 <html>

 <a id="_Toc96697849"></a>

 <section><a id="Apache_Axis2_JSON_and_REST_with_Spring_Boot_3_User.27s_Guide"></a>
 <h1>Apache Axis2 JSON and REST with Spring Boot 3 User's Guide</h1>


 <p>This guide will help you get started with Axis2 and JSON via REST, using
 <a href="https://spring.io/projects/spring-security" class="externalLink">Spring Security</a> with
 <a href="https://spring.io/projects/spring-boot" class="externalLink">Spring Boot 3!</a>
 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>

 <p>More docs concerning Axis2 and JSON can be found in the <a href=" json_support_gson.html">Pure JSON Support documentation</a> and <a href=" json_gson_user_guide.html">JSON User Guide</a>
 </p>
 <a id="Introduction"></a>

 <section><a id="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 WAR 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 &quot;<a href="mailto:java-user@axis.apache.org?subject=[Axis2]" class="externalLink">java-user@axis.apache.org</a>&quot;.
 (Subscription details are available on the <a href="../mail-lists.html">Axis2 site</a>.) Kindly
 prefix the subject of the mail with [Axis2].</p>

 </section><section><a id="Getting_Started"></a>
 <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>&quot;samples/userguide/src/springbootdemo&quot;</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 3 -
 however this WAR does not have an embedded web server such as Tomcat.
 </p>

 <p>
 The testing was carried out on Wildfly 32 with Jakarta, 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>

 </section><section><a id="Creating_secure_Web_Services"></a>
 <h2>Creating secure Web Services</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
 </p>

 <p>
 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. A flag in the suupplied axis2.xml file, enableJSONOnly,
 disables Axis2 functionality not required for JSON and sets up the server to expect JSON.
 </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 3, the Axis2Application class that
 extends <a href="https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/web/servlet/support/SpringBootServletInitializer.html" class="externalLink">SpringBootServletInitializer</a> as typically
 done utilizes a List of <a href="https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/SecurityFilterChain.html" class="externalLink">SecurityFilterChain</a> 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 &quot;Authorization: Bearer mytoken&quot;.
 </p>

 <p>
 The Axis2WebAppInitializer class supplied in this guide, is the config class
 that registers AxisServlet with Spring Boot 3.
 </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 available 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;excludeOperations&gt;
         &lt;operation&gt;setMyVar&lt;/operation&gt;
     &lt;/excludeOperations&gt;
 </pre>


 <p>
 The axis2.xml file can define <a href="https://github.com/google/gson" class="externalLink">GSON</a> or <a href="https://github.com/square/moshi" class="externalLink">Moshi</a> 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
 &quot;moshi&quot;. Just replace &quot;moshi&quot; with &quot;gson&quot; 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 &quot;Content-Type: application/json&quot;. 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=&quot;requestMessage&quot;&gt;
         &lt;messageFormatter contentType=&quot;application/json&quot;
                           class=&quot;org.apache.axis2.json.moshi.JsonFormatter&quot;/&gt;
 </pre>

 <p>
 Other required classes for JSON in the axis2.xml file include JsonRpcMessageReceiver,
 JsonInOnlyRPCMessageReceiver, JsonBuilder, JSONBasedDefaultDispatcher and JSONMessageHandler.
 </p>

 <p>
 Invoking the client for a login that returns a token can be done as follows:
 </p>

 <pre>
 curl -v -H &quot;Content-Type: application/json&quot; -X POST --data @/home/myuser/login.dat http://localhost:8080/axis2-json-api/services/loginService
 </pre>

 <p>
 Where the contents of /home/myuser/login.dat are:
 </p>

 <pre>
 {&quot;doLogin&quot;:[{&quot;arg0&quot;:{&quot;email&quot;:java-dev@axis.apache.org,&quot;credentials&quot;:userguide}}]}
 </pre>

 <p>
 Response:
 </p>

 <pre>
 {&quot;response&quot;:{&quot;status&quot;:&quot;OK&quot;,&quot;token&quot;:&quot;95104Rn2I2oEATfuI90N&quot;,&quot;uuid&quot;:&quot;99b92d7a-2799-4b20-b029-9fbd6108798a&quot;}}
 </pre>

 <p>
 Invoking the client for a Test Service that validates a sample token can be done as
 follows:
 </p>

 <pre>
 curl -v -H &quot;Authorization: Bearer 95104Rn2I2oEATfuI90N&quot; -H &quot;Content-Type: application/json&quot; -X POST --data @/home/myuser/test.dat http://localhost:8080/axis2-json-api/services/testws'
 </pre>

 <p>
 Where the contents of /home/myuser/test.dat are below. arg0 is a var name
 and is used by Axis2 as part of its reflection based code:
 </p>

 <pre>
 {&quot;doTestws&quot;:[{&quot;arg0&quot;:{&quot;messagein&quot;:hello}}]}
 </pre>

 <p>
 Response, HTML encoded to prevent XSS. For the results with encoding see src/site/xdoc/docs/json-springboot-userguide.xml.
 </p>

 <pre>
 {&quot;response&quot;:{&quot;messageout&quot;:&quot;&lt;script xmlns=\&quot;http://www.w3.org/1999/xhtml\&quot;&gt;alert('Hello');&lt;/script&gt; \&quot;&gt;&quot;,&quot;status&quot;:&quot;OK&quot;}}
 </pre>
 </section>
 </html>        </main>
       </div>
     </div>
     <hr/>
     <footer>
       <div class="container-fluid">
         <div class="row-fluid">
             <p>©      2004–2025
 <a href="https://www.apache.org/">The Apache Software Foundation</a>
 </p>
         </div>
       </div>
     </footer>
   </body>
 </html>
	<!DOCTYPE html>


	<!--
	\| Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/xdoc/docs/json-springboot-userguide.xml at 2025-03-05
	\| Rendered using Apache Maven Fluido Skin 2.0.0-M11
	-->
	<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
	<head>
	<meta charset="UTF-8" />
	<meta name="viewport" content="width=device-width, initial-scale=1" />
	<meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" />
	<title>Apache Axis2 JSON and REST with Spring Boot 3 User's Guide – Apache Axis2</title>
	<link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M11.min.css" />
	<link rel="stylesheet" href="../css/site.css" />
	<link rel="stylesheet" href="../css/print.css" media="print" />
	<script src="../js/apache-maven-fluido-2.0.0-M11.min.js"></script>
	<meta http-equiv="content-type" content="" /> </head>
	<body>
	<div class="container-fluid container-fluid-top">
	<header>
	<div id="banner">
	<div class="pull-left"><div id="bannerLeft"><h1><a href="http://www.apache.org/"><img class="class java.lang.Object" src="http://www.apache.org/images/asf_logo_wide.png" /> Apache Axis2</a></h1></div></div>
	<div class="pull-right"><div id="bannerRight"><h1><a href=".././"><img class="class java.lang.Object" src="../images/axis.jpg" /></a></h1></div></div>
	<div class="clear"><hr/></div>
	</div>

	<div id="breadcrumbs">
	<ul class="breadcrumb">
	<li id="publishDate">Last Published: 2025-03-04<span class="divider">\|</span>
	</li>
	<li id="projectVersion">Version: 2.0.0<span class="divider">\|</span></li>
	<li><a href="http://www.apache.org" class="externalLink">Apache</a><span class="divider">/</span></li>
	<li><a href="../index.html">Axis2/Java</a><span class="divider">/</span></li>
	<li class="active">Apache Axis2 JSON and REST with Spring Boot 3 User's Guide</li>
	</ul>
	</div>
	</header>
	<div class="row-fluid">
	<header id="leftColumn" class="span2">
	<nav class="well sidebar-nav">
	<ul class="nav nav-list">
	<li class="nav-header">Axis2/Java</li>
	<li><a href="../index.html">Home</a></li>
	<li><a href="../download.html">Downloads</a></li>
	<li><a href="javascript:void(0)"><span class="icon-chevron-down"></span>Release Notes</a>
	<ul class="nav nav-list">
	<li><a href="../release-notes/1.6.1.html">1.6.1</a></li>
	<li><a href="../release-notes/1.6.2.html">1.6.2</a></li>
	<li><a href="../release-notes/1.6.3.html">1.6.3</a></li>
	<li><a href="../release-notes/1.6.4.html">1.6.4</a></li>
	<li><a href="../release-notes/1.7.0.html">1.7.0</a></li>
	<li><a href="../release-notes/1.7.1.html">1.7.1</a></li>
	<li><a href="../release-notes/1.7.2.html">1.7.2</a></li>
	<li><a href="../release-notes/1.7.3.html">1.7.3</a></li>
	<li><a href="../release-notes/1.7.4.html">1.7.4</a></li>
	<li><a href="../release-notes/1.7.5.html">1.7.5</a></li>
	<li><a href="../release-notes/1.7.6.html">1.7.6</a></li>
	<li><a href="../release-notes/1.7.7.html">1.7.7</a></li>
	<li><a href="../release-notes/1.7.8.html">1.7.8</a></li>
	<li><a href="../release-notes/1.7.9.html">1.7.9</a></li>
	<li><a href="../release-notes/1.8.0.html">1.8.0</a></li>
	<li><a href="../release-notes/1.8.1.html">1.8.1</a></li>
	<li><a href="../release-notes/1.8.2.html">1.8.2</a></li>
	<li><a href="../release-notes/2.0.0.html">2.0.0</a></li>
	</ul></li>
	<li><a href="../modules/index.html">Modules</a></li>
	<li><a href="../tools/index.html">Tools</a></li>
	<li class="nav-header">Documentation</li>
	<li><a href="../docs/toc.html">Table of Contents</a></li>
	<li><a href="../docs/installationguide.html">Installation Guide</a></li>
	<li><a href="../docs/quickstartguide.html">QuickStart Guide</a></li>
	<li><a href="../docs/userguide.html">User Guide</a></li>
	<li><a href="../docs/jaxws-guide.html">JAXWS Guide</a></li>
	<li><a href="../docs/pojoguide.html">POJO Guide</a></li>
	<li><a href="../docs/spring.html">Spring Guide</a></li>
	<li><a href="../docs/webadminguide.html">Web Administrator's Guide</a></li>
	<li><a href="../docs/migration.html">Migration Guide (from Axis1)</a></li>
	<li class="nav-header">Resources</li>
	<li><a href="../faq.html">FAQ</a></li>
	<li><a href="../articles.html">Articles</a></li>
	<li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink">Wiki</a></li>
	<li><a href="../refLib.html">Reference Library</a></li>
	<li><a href="../apidocs/index.html">Online Java Docs</a></li>
	<li class="nav-header">Get Involved</li>
	<li><a href="../overview.html">Overview</a></li>
	<li><a href="../git.html">Checkout the Source</a></li>
	<li><a href="../mail-lists.html">Mailing Lists</a></li>
	<li><a href="../release-process.html">Release Process</a></li>
	<li><a href="../guidelines.html">Developer Guidelines</a></li>
	<li><a href="../siteHowTo.html">Build the Site</a></li>
	<li class="nav-header">Project Information</li>
	<li><a href="../team-list.html">Project Team</a></li>
	<li><a href="../issue-tracking.html">Issue Tracking</a></li>
	<li><a href="https://github.com/apache/axis-axis2-java-core" class="externalLink">Source Code</a></li>
	<li><a href="../thanks.html">Acknowledgements</a></li>
	<li class="nav-header">Apache</li>
	<li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a></li>
	<li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsorship</a></li>
	<li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a></li>
	<li><a href="http://www.apache.org/security/" class="externalLink">Security</a></li>
	</ul>
	</nav>
	<div class="well sidebar-nav">
	<div id="poweredBy">
	<div class="clear"></div>
	<div class="clear"></div>
	<a href="https://maven.apache.org/" class="builtBy" target="_blank"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
	</div>
	</div>
	</header>
	<main id="bodyColumn" class="span10">
	<html>

	<a id="_Toc96697849"></a>

	<section><a id="Apache_Axis2_JSON_and_REST_with_Spring_Boot_3_User.27s_Guide"></a>
	<h1>Apache Axis2 JSON and REST with Spring Boot 3 User's Guide</h1>


	<p>This guide will help you get started with Axis2 and JSON via REST, using
	<a href="https://spring.io/projects/spring-security" class="externalLink">Spring Security</a> with
	<a href="https://spring.io/projects/spring-boot" class="externalLink">Spring Boot 3!</a>
	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>

	<p>More docs concerning Axis2 and JSON can be found in the <a href=" json_support_gson.html">Pure JSON Support documentation</a> and <a href=" json_gson_user_guide.html">JSON User Guide</a>
	</p>
	<a id="Introduction"></a>

	<section><a id="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 WAR 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]" class="externalLink">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>

	</section><section><a id="Getting_Started"></a>
	<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 3 -
	however this WAR does not have an embedded web server such as Tomcat.
	</p>

	<p>
	The testing was carried out on Wildfly 32 with Jakarta, 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>

	</section><section><a id="Creating_secure_Web_Services"></a>
	<h2>Creating secure Web Services</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
	</p>

	<p>
	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. A flag in the suupplied axis2.xml file, enableJSONOnly,
	disables Axis2 functionality not required for JSON and sets up the server to expect JSON.
	</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 3, the Axis2Application class that
	extends <a href="https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/web/servlet/support/SpringBootServletInitializer.html" class="externalLink">SpringBootServletInitializer</a> as typically
	done utilizes a List of <a href="https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/SecurityFilterChain.html" class="externalLink">SecurityFilterChain</a> 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 3.
	</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 available 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>
	<excludeOperations>
	<operation>setMyVar</operation>
	</excludeOperations>
	</pre>


	<p>
	The axis2.xml file can define <a href="https://github.com/google/gson" class="externalLink">GSON</a> or <a href="https://github.com/square/moshi" class="externalLink">Moshi</a> 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>
	<message name="requestMessage">
	<messageFormatter contentType="application/json"
	class="org.apache.axis2.json.moshi.JsonFormatter"/>
	</pre>

	<p>
	Other required classes for JSON in the axis2.xml file include JsonRpcMessageReceiver,
	JsonInOnlyRPCMessageReceiver, JsonBuilder, JSONBasedDefaultDispatcher and JSONMessageHandler.
	</p>

	<p>
	Invoking the client for a login that returns a token can be done as follows:
	</p>

	<pre>
	curl -v -H "Content-Type: application/json" -X POST --data @/home/myuser/login.dat http://localhost:8080/axis2-json-api/services/loginService
	</pre>

	<p>
	Where the contents of /home/myuser/login.dat are:
	</p>

	<pre>
	{"doLogin":[{"arg0":{"email":java-dev@axis.apache.org,"credentials":userguide}}]}
	</pre>

	<p>
	Response:
	</p>

	<pre>
	{"response":{"status":"OK","token":"95104Rn2I2oEATfuI90N","uuid":"99b92d7a-2799-4b20-b029-9fbd6108798a"}}
	</pre>

	<p>
	Invoking the client for a Test Service that validates a sample token can be done as
	follows:
	</p>

	<pre>
	curl -v -H "Authorization: Bearer 95104Rn2I2oEATfuI90N" -H "Content-Type: application/json" -X POST --data @/home/myuser/test.dat http://localhost:8080/axis2-json-api/services/testws'
	</pre>

	<p>
	Where the contents of /home/myuser/test.dat are below. arg0 is a var name
	and is used by Axis2 as part of its reflection based code:
	</p>

	<pre>
	{"doTestws":[{"arg0":{"messagein":hello}}]}
	</pre>

	<p>
	Response, HTML encoded to prevent XSS. For the results with encoding see src/site/xdoc/docs/json-springboot-userguide.xml.
	</p>

	<pre>
	{"response":{"messageout":"<script xmlns=\"http://www.w3.org/1999/xhtml\">alert('Hello');</script> \">","status":"OK"}}
	</pre>
	</section>
	</html> </main>
	</div>
	</div>
	<hr/>
	<footer>
	<div class="container-fluid">
	<div class="row-fluid">
	<p>© 2004–2025
	<a href="https://www.apache.org/">The Apache Software Foundation</a>
	</p>
	</div>
	</div>
	</footer>
	</body>
	</html>