This is an automated email from the ASF dual-hosted git repository.
robertlazarski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/axis-axis2-java-core.git
The following commit(s) were added to refs/heads/master by this push:
new 6d030a7 re-add json-springboot-userguide.xml that got dropped somehow
6d030a7 is described below
commit 6d030a7ccccfbe648c5dd5c0922a62ea0e6a8067
Author: Robert Lazarski <robertlazar...@gmail.com>
AuthorDate: Wed Jul 28 13:13:35 2021 -0400
re-add json-springboot-userguide.xml that got dropped somehow
---
src/site/xdoc/docs/json-springboot-userguide.xml | 228 +++++++++++++++++++++++
1 file changed, 228 insertions(+)
diff --git a/src/site/xdoc/docs/json-springboot-userguide.xml
b/src/site/xdoc/docs/json-springboot-userguide.xml
new file mode 100644
index 0000000..4c43144
--- /dev/null
+++ b/src/site/xdoc/docs/json-springboot-userguide.xml
@@ -0,0 +1,228 @@
+<!--
+ ~ 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-u...@axis.apache.org?subject=[Axis2]";>java-u...@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>
+ <message name="requestMessage">
+ <excludeOperations>
+ <operation>setMyVar<</operation>
+ </excludeOperations>
+</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>
+ <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, 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-...@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":"<script
xmlns=\"http://www.w3.org/1999/xhtml\">alert('Hello');</script>
\">","status":"OK"}}
+</p>
+</body>
+</html>
