jaxwsdemo/README.md

# JAX-WS Hello World Project

A simple JAX-WS web service boilerplate project that returns "Hello World" messages.

## Project Structure

```
jaxws-hello-world/
├── pom.xml
├── Dockerfile
├── docker-compose.yml
├── src/
│   └── main/
│       ├── java/
│       │   └── com/
│       │       └── example/
│       │           └── service/
│       │               ├── HelloWorldService.java
│       │               └── HelloWorldServiceImpl.java
│       └── webapp/
│           └── WEB-INF/
│               ├── web.xml
│               └── sun-jaxws.xml
└── scripts/
    ├── test_hello_world.py
    ├── simple_test.py
    ├── requirements.txt
    └── README.md
```

## Files Overview

### Core Files
- **pom.xml**: Maven configuration with JAX-WS dependencies
- **HelloWorldService.java**: Web service interface with @WebService annotation
- **HelloWorldServiceImpl.java**: Implementation of the web service
- **web.xml**: Web application deployment descriptor
- **sun-jaxws.xml**: JAX-WS endpoint configuration

### Docker Files
- **Dockerfile**: Multi-stage Docker build configuration
- **docker-compose.yml**: Docker Compose orchestration file
- **tomcat-users.xml**: Tomcat manager user configuration

### Test Scripts
- **scripts/test_hello_world.py**: Interactive Python test client with automated tests
- **scripts/simple_test.py**: Simple automated test script for CI/CD
- **scripts/requirements.txt**: Python dependencies
- **scripts/README.md**: Detailed test script documentation

## Quick Start with Docker (Recommended)

The easiest way to test this application is using Docker. No need to install Java, Maven, or Tomcat!

### Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows/Mac/Linux)
- OR [Docker Engine](https://docs.docker.com/engine/install/) (Linux)

### Running with Docker Compose

**1. Start the application:**
```bash
docker-compose up -d
```

**1. Start the application ( when you changed code ):**
```bash
docker-compose up -d --build
```

**2. Wait for the application to start (about 30-40 seconds), then access:**
- **WSDL**: http://localhost:8080/jaxws-hello-world/hello?wsdl
- **Tomcat Manager**: http://localhost:8080/manager (username: `admin`, password: `admin123`)

**3. View logs:**
```bash
docker-compose logs -f
```

**4. Stop the application:**
```bash
docker-compose down
```

### Running with Docker (without Docker Compose)

**1. Build the Docker image:**
```bash
docker build -t jaxws-hello-world .
```

**2. Run the container:**
```bash
docker run -d -p 8080:8080 --name jaxws-service jaxws-hello-world
```

**3. View logs:**
```bash
docker logs -f jaxws-service
```

**4. Stop and remove the container:**
```bash
docker stop jaxws-service
docker rm jaxws-service
```

### Testing the Docker Deployment

Once the container is running, test the service:

```bash
# Check if WSDL is accessible
curl http://localhost:8080/jaxws-hello-world/hello?wsdl

# Test with a SOAP request
curl -X POST http://localhost:8080/jaxws-hello-world/hello \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: " \
  -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.example.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getHelloWorld>
         <arg0>Docker</arg0>
      </ser:getHelloWorld>
   </soapenv:Body>
</soapenv:Envelope>'
```

## Testing with Python Scripts

Python test scripts are provided in the [scripts/](scripts/) folder for easy testing of the JAX-WS service.

### Prerequisites

- Python 3.6 or higher
- pip (Python package installer)

### Setup

**Install Python dependencies:**

Windows:
```cmd
cd scripts
pip install -r requirements.txt
```

Linux/Mac:
```bash
cd scripts
pip3 install -r requirements.txt
```

### Available Test Scripts

#### 1. Simple Test Script

Quick automated test with a single name:

```bash
# Test with default name "World"
python scripts/simple_test.py

# Test with custom name
python scripts/simple_test.py "Your Name"
```

**Example Output:**
```
Checking service availability...
[OK] WSDL is accessible

Calling service with: 'Your Name'
Response: Hello World, Your Name!

[PASS] Test PASSED!
```

#### 2. Interactive Test Script

Full-featured test client with automated tests and interactive mode:

```bash
python scripts/test_hello_world.py
```

**Features:**
- Checks WSDL availability
- Runs automated tests with predefined names
- Interactive mode for manual testing
- Pretty-prints SOAP requests and responses

**Example Session:**
```
============================================================
JAX-WS Hello World Service Test Client
============================================================

1. Checking WSDL availability...
   WSDL is accessible

2. Testing Hello World Service...

   Calling service with name: 'World'
   Response: Hello World, World!

   Calling service with name: 'Python Client'
   Response: Hello World, Python Client!

3. Interactive Mode
   --------------------------------------------------------
   Enter a name (or 'quit' to exit): John
   Response: Hello World, John!

   Enter a name (or 'quit' to exit): quit
```

### Using the HelloWorldClient Class

You can also use the `HelloWorldClient` class in your own Python scripts:

```python
from scripts.test_hello_world import HelloWorldClient

# Create client
client = HelloWorldClient()

# Check service availability
is_available, message = client.check_wsdl()
print(message)

# Call the service
response = client.call_hello_world("Developer")
print(response)  # Output: Hello World, Developer!
```

### Troubleshooting Python Tests

**Service Not Available:**
- Ensure Docker container is running: `docker ps | grep jaxws`
- Check service URL: `curl http://localhost:8080/jaxws-hello-world/hello?wsdl`

**Module Not Found:**
- Make sure you're in the project root directory
- Install dependencies: `pip install -r scripts/requirements.txt`

**Python Command Not Found:**
- Windows: Use `python` or `py`
- Linux/Mac: Use `python3`

---

## Environment Setup

### Windows Setup

#### 1. Install Java Development Kit (JDK)

**Option A: Using Installer**
1. Download JDK 8 or higher from [Oracle](https://www.oracle.com/java/technologies/downloads/) or [OpenJDK](https://adoptium.net/)
2. Run the installer (e.g., `jdk-8u351-windows-x64.exe`)
3. Follow the installation wizard
4. Set JAVA_HOME environment variable:
   ```cmd
   setx JAVA_HOME "C:\Program Files\Java\jdk1.8.0_351"
   setx PATH "%PATH%;%JAVA_HOME%\bin"
   ```

**Option B: Using Chocolatey**
```cmd
choco install openjdk
```

**Verify Installation:**
```cmd
java -version
javac -version
```

#### 2. Install Apache Maven

**Option A: Manual Installation**
1. Download Maven from [Apache Maven](https://maven.apache.org/download.cgi)
2. Extract to `C:\Program Files\Apache\maven`
3. Set environment variables:
   ```cmd
   setx MAVEN_HOME "C:\Program Files\Apache\maven"
   setx PATH "%PATH%;%MAVEN_HOME%\bin"
   ```

**Option B: Using Chocolatey**
```cmd
choco install maven
```

**Verify Installation:**
```cmd
mvn -version
```

#### 3. Install Apache Tomcat

**Option A: Manual Installation**
1. Download Tomcat 9+ from [Apache Tomcat](https://tomcat.apache.org/download-90.cgi)
2. Extract to `C:\Program Files\Apache\Tomcat`
3. Set CATALINA_HOME:
   ```cmd
   setx CATALINA_HOME "C:\Program Files\Apache\Tomcat"
   ```

**Option B: Using Chocolatey**
```cmd
choco install tomcat
```

**Start Tomcat:**
```cmd
cd C:\Program Files\Apache\Tomcat\bin
startup.bat
```

**Stop Tomcat:**
```cmd
cd C:\Program Files\Apache\Tomcat\bin
shutdown.bat
```

#### 4. Configure Tomcat Manager (Optional)

Edit `C:\Program Files\Apache\Tomcat\conf\tomcat-users.xml`:
```xml
<tomcat-users>
  <role rolename="manager-gui"/>
  <role rolename="manager-script"/>
  <user username="admin" password="admin123" roles="manager-gui,manager-script"/>
</tomcat-users>
```

Access at: `http://localhost:8080/manager`

---

### Linux Setup

#### 1. Install Java Development Kit (JDK)

**Ubuntu/Debian:**
```bash
# Update package index
sudo apt update

# Install OpenJDK 8
sudo apt install openjdk-8-jdk -y

# OR Install OpenJDK 11
sudo apt install openjdk-11-jdk -y

# Set JAVA_HOME
echo 'export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64' >> ~/.bashrc
echo 'export PATH=$PATH:$JAVA_HOME/bin' >> ~/.bashrc
source ~/.bashrc
```

**RHEL/CentOS/Fedora:**
```bash
# Install OpenJDK 8
sudo yum install java-1.8.0-openjdk-devel -y

# OR Install OpenJDK 11
sudo dnf install java-11-openjdk-devel -y

# Set JAVA_HOME
echo 'export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk' >> ~/.bashrc
echo 'export PATH=$PATH:$JAVA_HOME/bin' >> ~/.bashrc
source ~/.bashrc
```

**Verify Installation:**
```bash
java -version
javac -version
```

#### 2. Install Apache Maven

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install maven -y
```

**RHEL/CentOS/Fedora:**
```bash
sudo yum install maven -y
# OR
sudo dnf install maven -y
```

**Manual Installation (All Distributions):**
```bash
# Download Maven
cd /opt
sudo wget https://dlcdn.apache.org/maven/maven-3/3.9.5/binaries/apache-maven-3.9.5-bin.tar.gz
sudo tar xzf apache-maven-3.9.5-bin.tar.gz
sudo ln -s apache-maven-3.9.5 maven

# Set environment variables
echo 'export MAVEN_HOME=/opt/maven' >> ~/.bashrc
echo 'export PATH=$PATH:$MAVEN_HOME/bin' >> ~/.bashrc
source ~/.bashrc
```

**Verify Installation:**
```bash
mvn -version
```

#### 3. Install Apache Tomcat

**Using Package Manager (Ubuntu/Debian):**
```bash
sudo apt update
sudo apt install tomcat9 -y

# Start Tomcat
sudo systemctl start tomcat9
sudo systemctl enable tomcat9

# Check status
sudo systemctl status tomcat9
```

**Manual Installation (All Distributions):**
```bash
# Download Tomcat
cd /opt
sudo wget https://dlcdn.apache.org/tomcat/tomcat-9/v9.0.80/bin/apache-tomcat-9.0.80.tar.gz
sudo tar xzf apache-tomcat-9.0.80.tar.gz
sudo ln -s apache-tomcat-9.0.80 tomcat

# Set permissions
sudo chmod +x /opt/tomcat/bin/*.sh

# Set environment variable
echo 'export CATALINA_HOME=/opt/tomcat' >> ~/.bashrc
source ~/.bashrc

# Start Tomcat
/opt/tomcat/bin/startup.sh

# Stop Tomcat
/opt/tomcat/bin/shutdown.sh
```

#### 4. Configure Tomcat Manager (Optional)

Edit `/opt/tomcat/conf/tomcat-users.xml` or `/etc/tomcat9/tomcat-users.xml`:
```bash
sudo nano /opt/tomcat/conf/tomcat-users.xml
```

Add:
```xml
<tomcat-users>
  <role rolename="manager-gui"/>
  <role rolename="manager-script"/>
  <user username="admin" password="admin123" roles="manager-gui,manager-script"/>
</tomcat-users>
```

Restart Tomcat:
```bash
# If using systemd
sudo systemctl restart tomcat9

# If manual installation
/opt/tomcat/bin/shutdown.sh
/opt/tomcat/bin/startup.sh
```

Access at: `http://localhost:8080/manager`

---

### Verify Complete Setup

**Check all installations:**

Windows:
```cmd
java -version
javac -version
mvn -version
echo %CATALINA_HOME%
```

Linux:
```bash
java -version
javac -version
mvn -version
echo $CATALINA_HOME
curl http://localhost:8080
```

If all commands return valid output, your environment is ready!

## Building the Project

```bash
mvn clean package
```

This will create a WAR file in the `target/` directory.

## Deploying

Deploy the generated WAR file to a servlet container like:
- Apache Tomcat 9+
- Jetty
- GlassFish
- WildFly

## Testing the Service

Once deployed, the service will be available at:

**WSDL URL**: `http://localhost:8080/jaxws-hello-world/services/hello?wsdl`

**Service Endpoint**: `http://localhost:8080/jaxws-hello-world/services/hello`

### Using SOAP UI or similar tool:

Send a SOAP request like:
```xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.example.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getHelloWorld>
         <arg0>World</arg0>
      </ser:getHelloWorld>
   </soapenv:Body>
</soapenv:Envelope>
```

Response:
```xml
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getHelloWorldResponse xmlns:ns2="http://service.example.com/">
         <return>Hello World, World!</return>
      </ns2:getHelloWorldResponse>
   </soap:Body>
</soap:Envelope>
```

## Requirements

### Option 1: Using Docker (Recommended)
- Docker Desktop or Docker Engine
- Docker Compose (usually included with Docker Desktop)

### Option 2: Traditional Setup
- Java 8 or higher
- Maven 3.6+
- Servlet container (Tomcat 9+, etc.)