| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 at 2022-07-14 |
| | Rendered using Apache Maven Fluido Skin 1.6 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="Date-Revision-yyyymmdd" content="20220714" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Apache Axis2 – Apache Axis2 JSON and REST with Spring Boot User's Guide</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script> |
| <meta http-equiv="content-type" content="" /> </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://www.apache.org/" id="bannerLeft"><img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Axis2"/></a></div> |
| <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/axis.jpg" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2022-07-14<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 1.8.2<span class="divider">|</span></li> |
| <li class=""><a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> |
| <li class=""><a href="../index.html" title="Axis2/Java">Axis2/Java</a><span class="divider">/</span></li> |
| <li class="active ">Apache Axis2 JSON and REST with Spring Boot User's Guide</li> |
| </ul> |
| </div> |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span2"> |
| <div class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header">Axis2/Java</li> |
| <li><a href="../index.html" title="Home"><span class="none"></span>Home</a> </li> |
| <li><a href="../download.html" title="Downloads"><span class="none"></span>Downloads</a> </li> |
| <li><a href="javascript:void(0)" title="Release Notes"><span class="icon-chevron-down"></span>Release Notes</a> |
| <ul class="nav nav-list"> |
| <li><a href="../release-notes/1.6.1.html" title="1.6.1"><span class="none"></span>1.6.1</a> </li> |
| <li><a href="../release-notes/1.6.2.html" title="1.6.2"><span class="none"></span>1.6.2</a> </li> |
| <li><a href="../release-notes/1.6.3.html" title="1.6.3"><span class="none"></span>1.6.3</a> </li> |
| <li><a href="../release-notes/1.6.4.html" title="1.6.4"><span class="none"></span>1.6.4</a> </li> |
| <li><a href="../release-notes/1.7.0.html" title="1.7.0"><span class="none"></span>1.7.0</a> </li> |
| <li><a href="../release-notes/1.7.1.html" title="1.7.1"><span class="none"></span>1.7.1</a> </li> |
| <li><a href="../release-notes/1.7.2.html" title="1.7.2"><span class="none"></span>1.7.2</a> </li> |
| <li><a href="../release-notes/1.7.3.html" title="1.7.3"><span class="none"></span>1.7.3</a> </li> |
| <li><a href="../release-notes/1.7.4.html" title="1.7.4"><span class="none"></span>1.7.4</a> </li> |
| <li><a href="../release-notes/1.7.5.html" title="1.7.5"><span class="none"></span>1.7.5</a> </li> |
| <li><a href="../release-notes/1.7.6.html" title="1.7.6"><span class="none"></span>1.7.6</a> </li> |
| <li><a href="../release-notes/1.7.7.html" title="1.7.7"><span class="none"></span>1.7.7</a> </li> |
| <li><a href="../release-notes/1.7.8.html" title="1.7.8"><span class="none"></span>1.7.8</a> </li> |
| <li><a href="../release-notes/1.7.9.html" title="1.7.9"><span class="none"></span>1.7.9</a> </li> |
| <li><a href="../release-notes/1.8.0.html" title="1.8.0"><span class="none"></span>1.8.0</a> </li> |
| </ul> |
| </li> |
| <li><a href="../modules/index.html" title="Modules"><span class="none"></span>Modules</a> </li> |
| <li><a href="../tools/index.html" title="Tools"><span class="none"></span>Tools</a> </li> |
| <li class="nav-header">Documentation</li> |
| <li><a href="../docs/toc.html" title="Table of Contents"><span class="none"></span>Table of Contents</a> </li> |
| <li><a href="../docs/installationguide.html" title="Installation Guide"><span class="none"></span>Installation Guide</a> </li> |
| <li><a href="../docs/quickstartguide.html" title="QuickStart Guide"><span class="none"></span>QuickStart Guide</a> </li> |
| <li><a href="../docs/userguide.html" title="User Guide"><span class="none"></span>User Guide</a> </li> |
| <li><a href="../docs/jaxws-guide.html" title="JAXWS Guide"><span class="none"></span>JAXWS Guide</a> </li> |
| <li><a href="../docs/pojoguide.html" title="POJO Guide"><span class="none"></span>POJO Guide</a> </li> |
| <li><a href="../docs/spring.html" title="Spring Guide"><span class="none"></span>Spring Guide</a> </li> |
| <li><a href="../docs/webadminguide.html" title="Web Administrator's Guide"><span class="none"></span>Web Administrator's Guide</a> </li> |
| <li><a href="../docs/migration.html" title="Migration Guide (from Axis1)"><span class="none"></span>Migration Guide (from Axis1)</a> </li> |
| <li class="nav-header">Resources</li> |
| <li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li> |
| <li><a href="../articles.html" title="Articles"><span class="none"></span>Articles</a> </li> |
| <li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki"><span class="none"></span>Wiki</a> </li> |
| <li><a href="../refLib.html" title="Reference Library"><span class="none"></span>Reference Library</a> </li> |
| <li><a href="../apidocs/index.html" title="Online Java Docs"><span class="none"></span>Online Java Docs</a> </li> |
| <li class="nav-header">Get Involved</li> |
| <li><a href="../overview.html" title="Overview"><span class="none"></span>Overview</a> </li> |
| <li><a href="../git.html" title="Checkout the Source"><span class="none"></span>Checkout the Source</a> </li> |
| <li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a> </li> |
| <li><a href="../release-process.html" title="Release Process"><span class="none"></span>Release Process</a> </li> |
| <li><a href="../guidelines.html" title="Developer Guidelines"><span class="none"></span>Developer Guidelines</a> </li> |
| <li><a href="../siteHowTo.html" title="Build the Site"><span class="none"></span>Build the Site</a> </li> |
| <li class="nav-header">Project Information</li> |
| <li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a> </li> |
| <li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a> </li> |
| <li><a href="http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/" class="externalLink" title="Source Code"><span class="none"></span>Source Code</a> </li> |
| <li><a href="../thanks.html" title="Acknowledgements"><span class="none"></span>Acknowledgements</a> </li> |
| <li class="nav-header">Apache</li> |
| <li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License"><span class="none"></span>License</a> </li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a> </li> |
| <li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li> |
| <li><a href="http://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a> </li> |
| </ul> |
| <hr /> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </div> |
| <div id="bodyColumn" class="span10" > |
| <html> |
| |
| <a name="a_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 |
| <a class="externalLink" href="https://spring.io/projects/spring-security">Spring Security</a> with |
| <a class="externalLink" href="https://spring.io/projects/spring-boot">Spring Boot!</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 name="Introduction"></a> |
| |
| <section> |
| <h2><a name="Introduction"></a>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 class="externalLink" 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> |
| |
| <section> |
| <h2><a name="Getting_Started"></a>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> |
| |
| <section> |
| <h2><a name="Creating_secure_Web_Services"></a>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. |
| </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 <a class="externalLink" href="https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/web/servlet/support/SpringBootServletInitializer.html">SpringBootServletInitializer</a> as typically |
| done utilizes a List of <a class="externalLink" href="https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/SecurityFilterChain.html">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. |
| </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> |
| |
| <div> |
| <pre> |
| <excludeOperations> |
| <operation>setMyVar</operation> |
| </excludeOperations> |
| </pre></div> |
| |
| |
| <p> |
| The axis2.xml file can define <a class="externalLink" href="https://github.com/google/gson">GSON</a> or <a class="externalLink" href="https://github.com/square/moshi">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> |
| |
| <div> |
| <pre> |
| <message name="requestMessage"> |
| <messageFormatter contentType="application/json" |
| class="org.apache.axis2.json.moshi.JsonFormatter"/> |
| </pre></div> |
| |
| <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> |
| |
| <div> |
| <pre> |
| curl -v -H "Content-Type: application/json" -X POST --data @/home/myuser/login.dat http://localhost:8080/axis2-json-api/services/loginService |
| </pre></div> |
| |
| <p> |
| Where the contents of /home/myuser/login.dat are: |
| </p> |
| |
| <div> |
| <pre> |
| {"doLogin":[{"arg0":{"email":java-dev@axis.apache.org,"credentials":userguide}}]} |
| </pre></div> |
| |
| <p> |
| Response: |
| </p> |
| |
| <div> |
| <pre> |
| {"response":{"status":"OK","token":"95104Rn2I2oEATfuI90N","uuid":"99b92d7a-2799-4b20-b029-9fbd6108798a"}} |
| </pre></div> |
| |
| <p> |
| Invoking the client for a Test Service that validates a sample token can be done as |
| follows: |
| </p> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <pre> |
| {"doTestws":[{"arg0":{"messagein":hello}}]} |
| </pre></div> |
| |
| <p> |
| Response, HTML encoded to prevent XSS. For the results with encoding see src/site/xdoc/docs/json-springboot-userguide.xml. |
| </p> |
| |
| <div> |
| <pre> |
| {"response":{"messageout":"<script xmlns=\"http://www.w3.org/1999/xhtml\">alert('Hello');</script> \">","status":"OK"}} |
| </pre></div> |
| |
| </html> |
| </div> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p>Copyright ©2004–2022 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved.</p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |