What Axis2 brings to Spring Boot

• Large JSON streaming (10MB–1GB+) — the streaming JSON formatter flushes HTTP/2 DATA frames every 64KB, keeping server memory flat regardless of response size. No reactive stack required.
• Native HTTP/2 with backpressure — the H2TransportSender provides connection multiplexing, flow control, and ALPN negotiation as a drop-in transport layer. See also the HTTP/2 overview.
• AI-ready services (MCP) — Axis2 auto-generates an MCP tool catalog from deployed services. AI assistants discover and call your services as tools without hand-authored definitions. See MCP examples for live demos.
• Response field selection — the ?fields= query parameter lets clients request only the fields they need, reducing payload size and AI token consumption at the serialization layer with zero application code.
• OpenAPI schemas from Hibernate mappings — the JPA/Hibernate schema generator produces read and write JSON Schemas directly from @Entity annotations or .hbm.xml files, including a batch CLI tool for large codebases. No hand-authored API contracts — the schema stays in sync with the database model by construction.
• Built-in pagination — the PaginatedResponse wrapper provides offset/limit pagination with server-enforced safety limits, totalCount for page controls, and hasMore for infinite scroll — mapping directly to JPA/Hibernate's setFirstResult/setMaxResults.
• SOAP + JSON from the same services — serve both SOAP/XML and JSON-RPC from the same Spring beans, selected by configuration. Useful for enterprises maintaining both legacy and modern clients.

This starter supports both WAR deployment to an external container (Tomcat 11, WildFly 32/39) and embedded Tomcat for local development. For embedded mode, set axis2.repo in application.properties to the exploded WAR directory from your build. See Deployment Model for details.

• 0. Deployment Model (WAR + Embedded)
• 1. Quick Start
• 2. How AxisServlet Works (SOAP vs JSON)
• 3. Configuration Properties
• 4. SOAP Mode vs JSON Mode
• 5. What Gets Autoconfigured
• 6. What Stays in Your Application
• 7. OpenAPI and MCP Support
• 8. Migration from Manual Configuration
• 9. Container Support
• 10. HTTP/2 and Streaming

External container (production)

For production, deploy as a WAR to an external servlet container. Your Spring Boot application must extend SpringBootServletInitializer and be packaged as a WAR. External containers provide operational advantages for long-running Axis2 deployments:

• Container-managed TLS, thread pools, and connection pools
• Hot-redeploy via exploded WAR without JVM restart
• Central certificate management (Tomcat's server.xml, WildFly's Elytron)
• HTTP/2 with ALPN (via container connector, not application code)

Embedded Tomcat (development)

For local development and testing, the sample application supports Spring Boot's embedded Tomcat via a Maven profile. Axis2's WarBasedAxisConfigurator requires a filesystem layout (WEB-INF/conf/axis2.xml, WEB-INF/services/*.aar, WEB-INF/modules/*.mar) that embedded Tomcat does not provide from its temp docbase. The -Daxis2.repo system property tells the configurator where to find the exploded WAR from the build:

# Build first (creates the exploded WAR with services and modules)
mvn clean install -DskipTests

# Run with embedded Tomcat
mvn spring-boot:run -Pembedded \
  -Dspring-boot.run.arguments="--server.port=9090" \
  -Dspring-boot.run.jvmArguments="-Daxis2.repo=target/deploy/axis2-json-api/WEB-INF"

The sample application requires authentication. Log in first to obtain a token, then pass it as a Bearer token on subsequent requests:

# 1. Log in (sample credentials)
TOKEN=$(curl -s http://localhost:9090/services/loginService \
  -H 'Content-Type: application/json' \
  -d '{"doLogin":[{"arg0":{"email":"java-dev@axis.apache.org","credentials":"userguide"}}]}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['response']['token'])")

# 2. Call a service with the token
curl -s http://localhost:9090/services/FinancialBenchmarkService \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"portfolioVariance":[{"arg0":{"weights":[0.5,0.5],"covarianceMatrix":[[0.04,0.006],[0.006,0.09]]}}]}'

OpenAPI and MCP endpoints do not require authentication:

curl -s http://localhost:9090/openapi.json
curl -s http://localhost:9090/openapi-mcp.json

For production, external containers remain the recommended deployment:

• Container-managed thread pools, connection pools, and monitoring (Actuator/Micrometer)
• Hot-redeploy via exploded WAR without JVM restart
• Central TLS/certificate management (Tomcat's server.xml, WildFly's Elytron)
• Established operational tooling (WildFly CLI, Tomcat Manager, deployment scanners)

Which external containers?

Minimum JDK version: OpenJDK 17. Axis2 core and the starter compile and pass CI tests with -Dmaven.compiler.release=17. Spring Boot 3.x and Tomcat 11 both require Java 17 as a minimum. The sample applications target Java 21 source level but Axis2 itself imposes no version above 17.

Other Jakarta EE 9+ containers (WebSphere Liberty, Payara) should work but are not tested.

Embedded mode limitations

Embedded Tomcat requires a pre-built exploded WAR on the filesystem (pointed to by axis2.repo). This means you must run mvn install before mvn spring-boot:run so that the .aar service archives and axis2.xml are staged in the build output directory. Changes to service metadata (operations, message receivers, MCP descriptions) require a rebuild.

Note that the service code itself is a Spring @Component bean on the classpath — the .aar file contains only metadata (services.xml) that tells Axis2 which Spring bean to call, which operations to expose, and which message receivers to use. The SpringBeanName parameter in services.xml bridges Axis2 service dispatch to Spring's application context. A future improvement could scan for services.xml resources on the classpath, eliminating the filesystem requirement entirely.

AxisServlet Initialization Sequence

When AxisServlet starts (init()), it:

1. Creates a WarBasedAxisConfigurator
2. Locates the repository (WEB-INF/) using, in order:
   1. axis2.repository.path servlet init-parameter (if set explicitly)
   2. axis2.repository.url servlet init-parameter (if set explicitly)
   3. ServletContext.getRealPath("/WEB-INF") (automatic fallback)
3. Reads WEB-INF/conf/axis2.xml to configure the engine
4. Scans WEB-INF/services/*.aar to deploy services
5. Scans WEB-INF/modules/*.mar to load modules (e.g., OpenAPI)
6. Stores the ConfigurationContext in the ServletContext — this is how other servlets (OpenAPI, MCP) access the Axis2 engine

The starter sets axis2.repository.path eagerly at startup as a workaround for WildFly VFS timing issues where getRealPath() can return null during lazy servlet initialization.

JSON mode (axis2.mode=json, the default)

# application.properties
axis2.mode=json

Uses JsonRpcMessageReceiver, JSONBasedDefaultDispatcher, and enableJSONOnly=true. Choose this for new services, MCP/AI integration, and REST/OpenAPI consumers.

SOAP mode (axis2.mode=soap)

# application.properties
axis2.mode=soap

Uses RawXMLINOutMessageReceiver, the full SOAP dispatcher stack, and enableJSONOnly=false. Choose this for WSDL-first services, WS-Security, WS-Addressing, or interop with .NET/PHP SOAP clients. This is the classic Axis2 configuration that has been in use since version 1.0 (2006).

Custom axis2.xml

# application.properties
axis2.configuration-file=classpath:my-axis2.xml

Overrides both built-in templates. Use this when you need custom phases, modules, transport configurations, or any axis2.xml settings not covered by the built-in templates.

The starter only stages axis2.xml if WEB-INF/conf/axis2.xml does not already exist. If your Maven build pre-stages it (e.g., via maven-antrun-plugin), the starter will not overwrite it.

JSON-RPC / MCP (axis2.mode=json)

The starter was tested with the springbootdemo-tomcat11 sample application, replacing ~30 individual Axis2 dependencies with the single axis2-spring-boot-starter dependency and removing the hand-coded Axis2WebAppInitializer. All endpoints confirmed working over HTTPS/HTTP2 on Tomcat 11 with OpenJDK 25:

SOAP (axis2.mode=soap)

The SOAP axis2.xml template was validated by unit tests confirming correct message receivers (RawXMLINOutMessageReceiver, RawXMLINOnlyMessageReceiver), the full SOAP dispatcher stack (SOAPActionBasedDispatcher, RequestURIBasedDispatcher, SOAPMessageBodyBasedDispatcher, HTTPLocationBasedDispatcher), and enableJSONOnly=false. The SOAP template is based on the Axis2 configuration that has been in production since version 1.0 (2006) and is identical in structure to the configuration used by the legacy userguide example1 Echo service (MyService.echo() with RawXMLINOutMessageReceiver).

Unit test suite

The starter includes 9 unit tests covering:

• Both axis2.xml templates exist on the classpath
• JSON template correctness (enableJSONOnly=true, JSONBasedDefaultDispatcher, no SOAP receivers)
• SOAP template correctness (enableJSONOnly=false, RawXMLINOut receivers, full SOAP dispatcher stack, no JSON dispatcher)
• Default property values
• AutoConfiguration.imports contains all required classes

Container matrix

See Section 0 for the full container compatibility matrix covering WAR deployment (Tomcat 11, WildFly 32/39) and embedded Tomcat for local development.