You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-commits@axis.apache.org by ro...@apache.org on 2021/07/29 14:58:25 UTC
[axis-axis2-java-core] branch master updated: doc updates
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 8d06122 doc updates
8d06122 is described below
commit 8d06122cc3511561e9c628f36ad22649fd49967e
Author: Robert Lazarski <ro...@gmail.com>
AuthorDate: Thu Jul 29 04:57:50 2021 -1000
doc updates
---
src/site/xdoc/docs/json-springboot-userguide.xml | 55 +++----
src/site/xdoc/docs/spring.xml | 173 +++--------------------
src/site/xdoc/index.xml | 26 +++-
3 files changed, 71 insertions(+), 183 deletions(-)
diff --git a/src/site/xdoc/docs/json-springboot-userguide.xml b/src/site/xdoc/docs/json-springboot-userguide.xml
index a56878b..3edf00f 100644
--- a/src/site/xdoc/docs/json-springboot-userguide.xml
+++ b/src/site/xdoc/docs/json-springboot-userguide.xml
@@ -31,10 +31,11 @@
<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).
+<a href="https://spring.io/projects/spring-security">Spring Security</a> with
+<a 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</a> and <a href="
@@ -84,7 +85,7 @@ 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>
+<h2>Creating secure Web Services</h2>
<p>
Areas out of scope for this guide are JWT and JWE for token generation and validation,
@@ -129,12 +130,14 @@ 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
-a List of 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.
+extends <a href="https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/SecurityFilterChain.html">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">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
@@ -159,13 +162,13 @@ 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
+The axis2.xml file can define <a href= "https://github.com/google/gson">GSON</a> or <a 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
@@ -195,40 +198,40 @@ JsonInOnlyRPCMessageReceiver, JsonBuilder, and JSONMessageHandler.
<p>
Invoking the client for a login that returns a token can be done as follows:
</p>
-<p>
+<pre>
curl -v -H "Content-Type: application/json" -X POST --data @/home/myuser/login.dat http://localhost:8080/axis2-json-api/services/loginService
-</p>
+</pre>
<p>
Where the contents of /home/myuser/login.dat are:
</p>
-<p>
+<pre>
{"doLogin":[{"arg0":{"email":java-dev@axis.apache.org,"credentials":userguide}}]}
-</p>
+</pre>
<p>
Response:
</p>
-<p>
+<pre>
{"response":{"status":"OK","token":"95104Rn2I2oEATfuI90N","uuid":"99b92d7a-2799-4b20-b029-9fbd6108798a"}}
-</p>
+</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>
- 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'
-</p>
-<p>
-Where the contents of /home/myuser/test.dat are below. arg0 is the var name
+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>
-<p>
+<pre>
{"doTestws":[{"arg0":{"messagein":hello}}]}
-</p>
+</pre>
<p>
-Response, HTML encoded to prevent XSS. For the results with encoding see ./src/site/xdoc/docs/json-springboot-userguide.xml.
+Response, HTML encoded to prevent XSS. For the results with encoding see src/site/xdoc/docs/json-springboot-userguide.xml.
</p>
-<p>
+<pre>
{"response":{"messageout":"<script xmlns=\"http://www.w3.org/1999/xhtml\">alert('Hello');</script> \">","status":"OK"}}
-</p>
+</pre>
</body>
</html>
diff --git a/src/site/xdoc/docs/spring.xml b/src/site/xdoc/docs/spring.xml
index 240c70f..156cc22 100644
--- a/src/site/xdoc/docs/spring.xml
+++ b/src/site/xdoc/docs/spring.xml
@@ -30,6 +30,28 @@
<p>This document is a guide on how to use Axis2 with the Spring Framework</p>
+<p>
+For users of JSON and <a href="https://spring.io/projects/spring-boot">Spring Boot</a>
+- or anyone interesed in a complete Spring Boot example that includes Spring Security -
+see the sample application in the <a href=
+"json-springboot-userguide.html">JSON and Spring Boot User's Guide.</a>
+</p>
+
+<p>
+Update: Spring inside the AAR is no longer supported. See this commit:
+</p>
+
+<pre>
+commit 9e392c0ae1f0abab3d4956fbf4c0818c9570021e
+Author: Andreas Veithen <veithen@apache.org>
+Date: Sat May 6 22:21:10 2017 +0000
+
+ AXIS2-3919: Remove the alternate class loading mechanism:
+ - It degrades performance.
+ - There is no test coverage for it.
+ - With r1794157 in place, in most cases, no temporary files will be created and there is no need for a fallback mechanism.
+</pre>
+
<h2>Content</h2>
<ul>
<li><a href="#1">Introduction</a></li>
@@ -40,14 +62,6 @@
<li><a href="#23">With a ServletContext</a></li>
<li><a href="#24">Without a ServletContext</a></li>
<li><a href="#25">Putting it All Together</a></li>
- <li><a href="#26">Spring Inside an AAR </a>
- <ul>
- <li><a href="#261">The Spring Inside an AAR Layout</a></li>
- <li><a href="#262">The Spring Inside an AAR init Class</a></li>
- <li><a href="#263">Known Issues Running Spring Inside the
- AAR</a></li>
- </ul>
- </li>
</ul>
</li>
</ul>
@@ -350,148 +364,5 @@ minimum requirements are spring-core, spring-beans, spring-context, and
spring-web. When running the client, you should see this output:</p>
<pre>Response: <example1:string xmlns:example1="http://springExample.org/example1"
xmlns:tns="http://ws.apache.org/axis2">Spring, emerge thyself</example1:string></pre>
-<a name="26"></a>
-
-<h3>Spring Inside an AAR</h3>
-
-<p>Axis2 users frequently want to run Spring inside the AAR. Here we show you
-how it is done. There are four points to be aware of:</p>
-
-<p>(A) You need to configure Spring to use the Axis2 Service Classloader. See
-the <a href="#263">Known issues running Spring inside the AAR</a> area.</p>
-
-<p>(B) It's up to you to load Spring, though we give an example below.</p>
-
-<p>(C) For reasons such as classloader isolation, the
-SpringAppContextAwareObjectSupplier is the best choice.</p>
-
-<p>(D) The springframework .jar and axis2-spring-*.jar will be placed inside
-the AAR under the lib directory. Please <strong>move</strong> the
-axis2-spring-*.jar from WEB-INF/lib to inside the AAR, as shown below - it
-will <strong>not</strong> work otherwise.</p>
-<ul>
- <li><strong><a name="261"></a>The Spring inside an AAR layout</strong></li>
-</ul>
-<pre>./springExample.aar
-./META-INF
-./META-INF/MANIFEST.MF
-./META-INF/services.xml
-./applicationContext.xml
-./lib
-./lib/axis2-spring-1.4.jar
-./lib/spring.jar
-./spring
-./spring/MyBean.class
-./spring/MyBeanImpl.class
-./spring/SpringAwareService.class
-./spring/SpringInit.class </pre>
-<p>As explained in the <a href="#24">Without a ServletContext</a> section,
-the 'Spring inside an AAR' config needs to hook Axis2 and Spring together via
-a Spring bean. Place the following in your Spring config file:</p>
-<pre> <!-- Configure spring to give a hook to axis2 without a ServletContext -->
- <bean id="applicationContext"
- class="org.apache.axis2.extensions.spring.receivers.ApplicationContextHolder" /></pre>
-<ul>
- <li><strong><a name="262"></a>The Spring inside an AAR init
- class</strong></li>
-</ul>
-
-<p>One way to initialize Spring inside the AAR is to use the
-org.apache.axis2.engine.ServiceLifeCycle interface. Here we give an
-example:</p>
-<pre>package spring;
-
-import org.apache.axis2.engine.ServiceLifeCycle;
-import org.apache.axis2.context.ConfigurationContext;
-import org.apache.axis2.description.AxisService;
-import org.springframework.context.support.ClassPathXmlApplicationContext;
-
-public class SpringInit implements ServiceLifeCycle {
-
- /**
- * This will be called during the deployement time of the service.
- * irrespective
- * of the service scope this method will be called
- */
- public void startUp(ConfigurationContext ignore, AxisService service) {
-
- try {
- System.out.println("Starting spring init");
- ClassLoader classLoader = service.getClassLoader();
- ClassPathXmlApplicationContext appCtx = new
- ClassPathXmlApplicationContext(new String[] {"applicationContext.xml"}, false);
- appCtx.setClassLoader(classLoader);
- appCtx.refresh();
- System.out.println("spring loaded");
- } catch (Exception ex) {
- ex.printStackTrace();
- }
- }
-
- /**
- * This will be called during the system shut down time.
- * irrespective
- * of the service scope this method will be called
- */
- public void shutDown(ConfigurationContext ctxIgnore, AxisService ignore) {
- }
-}</pre>
-<p>Here's the services.xml that now includes SpringInit and the
-SpringAwareService shown above. There is also the composite parameter which
-is needed when loading Spring in the AAR - see the <a href="#263">Known
-issues running Spring inside the AAR</a> area.</p>
-<pre><serviceGroup>
- <!-- Invoke SpringInit on server startup and shutdown -->
- <service name="SpringAwareService" class="spring.SpringInit">
- <description>
- simple spring example - inside the AAR
- </description>
- <!-- need the TCCL param when using spring inside the AAR -->
- <parameter name="ServiceTCCL">composite</parameter>
- <parameter name="ServiceObjectSupplier">org.apache.axis2.extensions.spring.receivers.SpringAppContextAwareObjectSupplier</parameter>
- <parameter name="SpringBeanName">springAwareService</parameter>
- <operation name="getValue">
- <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
- </operation>
- </service>
-</serviceGroup></pre>
-<ul>
- <li><strong><a name="263"></a>Known issues running Spring inside the
- AAR</strong></li>
-</ul>
-
-<p>By default, the Axis2 classloader strategy does not permit Spring to run
-inside the AAR. To allow Spring to run inside the AAR, the 'composite'
-parameter is used in the services.xml as shown in the example above. There
-was default behavior of 'composite' in the development cycle in between 1.0
-and 1.1, but it resulted in the JIRA issue AXIS2-1214 -problems with getting
-an initContext.lookup() handle inside the AAR. Spring users typically have
-little desire to use initContext.lookup(), as they get their Datasources via
-org.springframework.jdbc.datasource.DriverManagerDataSource in an XML file or
-with annotations. For EJB home references and the like, Spring provides
-JndiObjectFactoryBean. </p>
-
-<p>A common requirement is to run Hibernate along with Spring with Axis2 web services.
-It is easier to run Hibernate as well as Spring outside the AAR as shown in the
-ServletContext example, ie, place the Spring and Hibernate jars in WEB-INF/lib and
-the hibernate config files under WEB-INF/classes. With that advisement, Spring provides
-an API that allows Spring to load Hibernate under the contraints of an AAR. </p>
-
-<p>Hibernate by default looks for its config files in the classpath. By running Hibernate
-inside the AAR, Hibernate won't be able to find its config files. The way to get
-around this limitation is either to expand the AAR or place the hibernate config
-files in a specific directory under WEB-INF/classes - and then use
-<a href="http://www.springframework.org/docs/api/org/springframework/orm/hibernate/LocalSessionFactoryBean.html#setMappingDirectoryLocations(org.springframework.core.io.Resource[])">Spring's setMappingDirectoryLocations</a> for several options. </p>
-
-<p>By placing Spring into DEBUG mode you can look at the logs to see where Spring will look
-for your jar / class locations. Use the wildcards in the following example to list your mapping
-locations as shown: </p>
-
-<pre><bean id="mySessionFactory" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">
- <property name="mappingLocations">
- <value>classpath*:**/MyEntity.hbm.xml</value>
- </property>
- ...
-</bean> </pre>
</body>
</html>
diff --git a/src/site/xdoc/index.xml b/src/site/xdoc/index.xml
index 0eef1ba..f59f661 100644
--- a/src/site/xdoc/index.xml
+++ b/src/site/xdoc/index.xml
@@ -24,7 +24,7 @@
</properties>
<body>
<h1>Welcome to Apache Axis2/Java</h1>
-<p>Apache Axis2™ is a Web Services / SOAP / WSDL engine, the successor to the
+<p>Apache Axis2™ is a Web Services JSON / SOAP / WSDL engine, the successor to the
widely used <a href=
"http://ws.apache.org/axis/">Apache Axis</a> SOAP stack.
There are two implementations
@@ -50,11 +50,16 @@ also has integrated support for the widely popular <a href=
services</a>. The same business logic implementation can offer both
a WS-* style interface as well as a REST/POX style interface
simultaneously.</p>
+<p>Apache Axis2 over time has expanded to contemporary JSON
+(JavaScript Object Notation) web services, and that area
+is where new development is occuring. In addition to GSON
+for the Java serialization/deserialization of JSON, Moshi
+is now supported since GSON development has largely ceased.</p>
<p>Apache Axis2 is more efficient, more modular and more
-XML-oriented than the older version. It is carefully designed to
-support the easy addition of plug-in "modules" that extend their
-functionality for features such as security and reliability. The
-<a href="modules/index.html">Modules</a>
+XML-oriented / JSON-orientated than the older version. It is
+carefully designed to support the easy addition of plug-in "modules"
+that extend their functionality for features such as security and
+reliability. The <a href="modules/index.html">Modules</a>
currently available or under development include:</p>
<ul>
<li><a href=
@@ -68,7 +73,9 @@ core</li>
</ul>
<p>Apache Axis2 is built on <a href=
"http://ws.apache.org/axiom/">Apache AXIOM</a>, a
-new high performant, pull-based XML object model.</p>
+new high performant, pull-based XML object model - however for JSON
+based web services, Moshi (or GSON) takes its place and largely follows
+the same pull-based concepts.</p>
<p>Axis2 comes with many new features, enhancements and industry
specification implementations. The key features offered are as
follows:</p>
@@ -146,6 +153,13 @@ export machine-readable descriptions of your deployed services from
Axis2.</p>
</li>
<li>
+<p style="margin-bottom: 0in"><strong>JSON support</strong> - Axis2
+supports the creation of Web Services using JavaScript Object Notation, with <a href=
+"https://github.com/google/gson">GSON</a> and <a href=
+"https://github.com/square/moshi">Moshi</a>, which allows you to easily
+build POJO based services that receive and return JSON.</p>
+</li>
+<li>
<p style="margin-bottom: 0in"><strong>Composition and
Extensibility</strong> - Modules and phases improve support for
composability and extensibility. Modules support composability and