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
commit a1b414e4daadf156a81da7a2f29e29eea8895f1a Author: Robert Lazarski <[email protected]> AuthorDate: Mon Apr 6 03:00:43 2026 -1000 springbootdemo-tomcat11: add README documenting deployment, services, and context path gotcha Documents the critical Tomcat directory naming requirement (axis2-json-api not axis2-json-api.war), the full test flow, Axis2 JSON-RPC request format, and architectural differences from the WildFly springbootdemo module. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> --- .../userguide/springbootdemo-tomcat11/README.md | 151 +++++++++++++++++++++ 1 file changed, 151 insertions(+) diff --git a/modules/samples/userguide/src/userguide/springbootdemo-tomcat11/README.md b/modules/samples/userguide/src/userguide/springbootdemo-tomcat11/README.md new file mode 100644 index 0000000000..d671288472 --- /dev/null +++ b/modules/samples/userguide/src/userguide/springbootdemo-tomcat11/README.md @@ -0,0 +1,151 @@ +<!-- + ~ 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. + --> + +# springbootdemo-tomcat11 + +Axis2 JSON-RPC services deployed as a WAR in **Apache Tomcat 11**, using Spring Boot 3.x as a +configuration framework only — there is no embedded container. + +Tested with: **Tomcat 11.0.20** · **OpenJDK 21** · **Spring Boot 3.4.3** + +--- + +## Services + +| Service | Path | Auth | +|---------|------|------| +| `LoginService.login` | `POST /axis2-json-api/services/LoginService` | None (public) | +| `TestwsService.testws` | `POST /axis2-json-api/services/TestwsService` | Bearer token | +| `BigDataH2Service.processBigDataSet` | `POST /axis2-json-api/services/BigDataH2Service` | None (public) | +| OpenAPI spec (JSON) | `GET /axis2-json-api/openapi.json` | None | +| OpenAPI spec (YAML) | `GET /axis2-json-api/openapi.yaml` | None | +| Swagger UI | `GET /axis2-json-api/swagger-ui` | None | + +--- + +## Build + +```bash +cd modules/samples/userguide/src/userguide/springbootdemo-tomcat11 +mvn package +``` + +This produces an exploded WAR directory at `target/deploy/axis2-json-api/`. + +--- + +## Deploy to Tomcat 11 + +```bash +# Copy exploded WAR to Tomcat webapps +cp -r target/deploy/axis2-json-api /path/to/tomcat/webapps/ + +# Restart Tomcat +/path/to/tomcat/bin/shutdown.sh && /path/to/tomcat/bin/startup.sh +``` + +### CRITICAL: Directory naming and context path + +Tomcat strips the `.war` suffix when deploying a **packaged** `foo.war` file, giving context +path `/foo`. However, when deploying an **exploded directory**, Tomcat uses the directory name +as-is. A directory named `axis2-json-api.war/` deploys at context path `/axis2-json-api.war`, +**not** `/axis2-json-api`. + +The Maven build produces `target/deploy/axis2-json-api` (no `.war` suffix) for exactly this +reason. Do not rename the directory before copying to `webapps/`. + +--- + +## Test flow + +### 1. Verify OpenAPI docs + +```bash +curl http://localhost:8080/axis2-json-api/openapi.json +curl http://localhost:8080/axis2-json-api/openapi.yaml +# Interactive UI: +curl http://localhost:8080/axis2-json-api/swagger-ui +``` + +### 2. Login (get Bearer token) + +```bash +curl -s -X POST http://localhost:8080/axis2-json-api/services/LoginService \ + -H 'Content-Type: application/json' \ + -d '{"login":[{"request":{"email":"[email protected]","credentials":"password"}}]}' +``` + +Response: `{"loginResponse":{"token":"<JWT>","status":"OK"}}` + +### 3. Call protected service + +```bash +TOKEN="<JWT from step 2>" +curl -s -X POST http://localhost:8080/axis2-json-api/services/TestwsService \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer $TOKEN" \ + -d '{"testws":[{"request":{"name":"World"}}]}' +``` + +### 4. Call public BigData service + +```bash +curl -s -X POST http://localhost:8080/axis2-json-api/services/BigDataH2Service \ + -H 'Content-Type: application/json' \ + -d '{"processBigDataSet":[{"request":{"numRecords":1000}}]}' +``` + +--- + +## Axis2 JSON-RPC request format + +The top-level key is the **operation name**, and the body is wrapped in an array: + +```json +{ "operationName": [{ "request": { ...fields... } }] } +``` + +--- + +## Architecture notes + +- **No embedded container** — `Axis2Application` extends `SpringBootServletInitializer`, not + `SpringApplication.run()`. Spring Boot only provides configuration; Tomcat is the server. +- **No `DispatcherServlet`** — `@GetMapping` annotations are dead code in this module. OpenAPI + endpoints are served by `OpenApiServlet`, a plain `HttpServlet` registered directly in + `Axis2WebAppInitializer` at `/openapi.json`, `/openapi.yaml`, and `/swagger-ui`. +- **OpenAPI module** — `axis2-openapi-<version>.jar` is copied to + `WEB-INF/modules/openapi-<version>.mar` by the Maven build. It must be present for + `GET /openapi.*` and `GET /swagger-ui` to work. +- **Security** — three Spring Security filter chains: OpenApi (Order 2, unauthenticated), + Login (Order 3, unauthenticated), Token (remaining, requires Bearer JWT). + +--- + +## Relationship to `springbootdemo` (WildFly) + +`springbootdemo-tomcat11` is derived from `springbootdemo` (which targets WildFly). The two +modules share the same service logic but differ in: + +| Aspect | `springbootdemo` (WildFly) | `springbootdemo-tomcat11` | +|--------|---------------------------|--------------------------| +| Server | WildFly / embedded Undertow | Apache Tomcat 11 | +| Context path | `/axis2-json-api` | `/axis2-json-api` | +| OpenAPI routing | `OpenApiServlet` via `Axis2WebAppInitializer` | Same | +| H2 BigData service | Yes | Yes |
