Files

Ken Yasue 1f949579b3 add unified test scripts for all services

2025-12-05 11:41:36 +01:00

16 KiB

Raw Blame History

API Documentation

Overview

This project provides JAX-WS SOAP web services for a loan approval system. The system includes customer registration, loan application processing with credit score evaluation, and a simple Hello World demonstration service.

Version: 1.0 Base URL: http://localhost:8080/jaxws-hello-world Protocol: SOAP 1.1 / HTTP Data Format: XML

Services Overview
Hello World Service
Loan Approval Service
Data Models
Database Schema
Error Handling
Testing

Services Overview

Service Name	Endpoint	WSDL	Description
HelloWorldService	`/hello`	WSDL	Simple demonstration service
LoanApprovalService	`/loan`	WSDL	Customer registration and loan processing

Hello World Service

Service Information

Endpoint: http://localhost:8080/jaxws-hello-world/hello
WSDL: http://localhost:8080/jaxws-hello-world/hello?wsdl
Namespace: http://service.example.com/

Methods

getHelloWorld

Returns a personalized greeting message.

Operation: getHelloWorld

Input Parameters:

Parameter	Type	Required	Description
name	string	Yes	Name to include in greeting

Returns: string - Greeting message in format "Hello World, {name}!"

SOAP Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ser="http://service.example.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getHelloWorld>
         <arg0>John</arg0>
      </ser:getHelloWorld>
   </soapenv:Body>
</soapenv:Envelope>

SOAP Response Example:

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:getHelloWorldResponse xmlns:ns2="http://service.example.com/">
         <return>Hello World, John!</return>
      </ns2:getHelloWorldResponse>
   </S:Body>
</S:Envelope>

Loan Approval Service

Service Information

Endpoint: http://localhost:8080/jaxws-hello-world/loan
WSDL: http://localhost:8080/jaxws-hello-world/loan?wsdl
Namespace: http://service.example.com/
Database: SQLite (loan_app.db)

Methods

1. registerNewCustomer

Registers a new customer in the system with optional blacklist status.

Operation: registerNewCustomer

Input Parameters:

Parameter	Type	Required	Description
request	CustomerRegistrationRequest	Yes	Customer registration details
└─ customerName	string	Yes	Customer's full name
└─ blacklisted	boolean	No	Blacklist status (default: false)

Returns: string - Registration status message

Possible Return Values:

"Registration Successful" - Customer registered successfully
"Error: Customer already exists" - Customer name already in database

SOAP Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ser="http://service.example.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:registerNewCustomer>
         <arg0>
            <customerName>John Doe</customerName>
            <blacklisted>false</blacklisted>
         </arg0>
      </ser:registerNewCustomer>
   </soapenv:Body>
</soapenv:Envelope>

SOAP Response Example (Success):

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:registerNewCustomerResponse xmlns:ns2="http://service.example.com/">
         <return>Registration Successful</return>
      </ns2:registerNewCustomerResponse>
   </S:Body>
</S:Envelope>

SOAP Response Example (Duplicate):

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:registerNewCustomerResponse xmlns:ns2="http://service.example.com/">
         <return>Error: Customer already exists</return>
      </ns2:registerNewCustomerResponse>
   </S:Body>
</S:Envelope>

Business Rules:

Customer names must be unique
Customer name cannot be null or empty
Blacklist status is optional (defaults to false)
Registration time is automatically recorded

2. processLoanApplication

Processes a loan application with credit score-based approval logic.

Operation: processLoanApplication

Input Parameters:

Parameter	Type	Required	Description
request	LoanRequest	Yes	Loan application details
└─ applicantName	string	Yes	Applicant's full name
└─ requestedAmount	int	Yes	Loan amount requested (must be > 0)
└─ creditScore	int	No	Credit score (system may use default)

Returns: LoanResponse - Loan decision result

SOAP Request Example:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ser="http://service.example.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:processLoanApplication>
         <arg0>
            <applicantName>John Doe</applicantName>
            <requestedAmount>50000</requestedAmount>
            <creditScore>720</creditScore>
         </arg0>
      </ser:processLoanApplication>
   </soapenv:Body>
</soapenv:Envelope>

SOAP Response Example (Approved):

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:processLoanApplicationResponse xmlns:ns2="http://service.example.com/">
         <return>
            <approved>true</approved>
            <approvedRate>3.5</approvedRate>
            <rejectionReason></rejectionReason>
            <message>Loan approved with excellent rate</message>
         </return>
      </ns2:processLoanApplicationResponse>
   </S:Body>
</S:Envelope>

SOAP Response Example (Rejected - Blacklisted):

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:processLoanApplicationResponse xmlns:ns2="http://service.example.com/">
         <return>
            <approved>false</approved>
            <approvedRate>0.0</approvedRate>
            <rejectionReason>Applicant is blacklisted</rejectionReason>
            <message>Loan application rejected</message>
         </return>
      </ns2:processLoanApplicationResponse>
   </S:Body>
</S:Envelope>

SOAP Response Example (Rejected - Low Credit):

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <ns2:processLoanApplicationResponse xmlns:ns2="http://service.example.com/">
         <return>
            <approved>false</approved>
            <approvedRate>0.0</approvedRate>
            <rejectionReason>Credit score too low</rejectionReason>
            <message>Loan application rejected</message>
         </return>
      </ns2:processLoanApplicationResponse>
   </S:Body>
</S:Envelope>

Credit Score Approval Logic:

Credit Score Range	Approval Status	Interest Rate	Message
>= 700	Approved	3.5%	Loan approved with excellent rate
600 - 699	Approved	5.5%	Loan approved with standard rate
500 - 599	Approved	8.5%	Loan approved with high risk rate
< 500	Rejected	N/A	Credit score too low
Blacklisted	Rejected	N/A	Applicant is blacklisted

Business Rules:

Blacklisted applicants are automatically rejected
Applicant name cannot be null or empty
Requested amount must be greater than 0
Credit score is retrieved from CreditScoreService (default: 700)
All loan applications are logged to loan_history table
System records: applicant name, amount, approval status, rate, rejection reason, and timestamp

Data Models

CustomerRegistrationRequest

Request model for customer registration.

Fields:

Field	Type	Required	Description
customerName	string	Yes	Customer's full name (must be unique)
blacklisted	boolean	No	Whether customer is blacklisted (default: false)

Java Example:

CustomerRegistrationRequest request = new CustomerRegistrationRequest();
request.setCustomerName("John Doe");
request.setBlacklisted(false);

LoanRequest

Request model for loan application.

Fields:

Field	Type	Required	Description
applicantName	string	Yes	Applicant's full name
requestedAmount	int	Yes	Loan amount in currency units (must be > 0)
creditScore	int	No	Credit score (0-850 scale)

Java Example:

LoanRequest request = new LoanRequest();
request.setApplicantName("John Doe");
request.setRequestedAmount(50000);
request.setCreditScore(720);

LoanResponse

Response model for loan application result.

Fields:

Field	Type	Description
approved	boolean	Whether the loan was approved
approvedRate	double	Interest rate if approved (0.0 if rejected)
rejectionReason	string	Reason for rejection (null if approved)
message	string	Human-readable status message

Java Example:

LoanResponse response = loanService.processLoanApplication(request);
if (response.isApproved()) {
    System.out.println("Approved at " + response.getApprovedRate() + "%");
} else {
    System.out.println("Rejected: " + response.getRejectionReason());
}

Database Schema

The service uses SQLite database (loan_app.db) with the following schema:

customers

Stores registered customer information.

Column	Type	Constraints	Description
customer_name	TEXT	PRIMARY KEY	Customer's unique name
is_blacklisted	INTEGER	DEFAULT 0	Blacklist status (0=false, 1=true)
registered_at	TEXT		Registration timestamp (ISO 8601)

Indexes:

Primary key on customer_name

loan_history

Stores all loan application records.

Column	Type	Constraints	Description
id	INTEGER	PRIMARY KEY AUTOINCREMENT	Unique record ID
applicant_name	TEXT		Applicant's name
requested_amount	INTEGER		Loan amount requested
approved	INTEGER		Approval status (0=rejected, 1=approved)
approved_rate	REAL		Interest rate if approved
rejection_reason	TEXT		Reason for rejection (null if approved)
processed_at	TEXT		Processing timestamp (ISO 8601)

Indexes:

Primary key on id

Error Handling

SOAP Faults

The service returns SOAP faults for validation errors and invalid requests.

Common SOAP Fault Example:

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <S:Body>
      <S:Fault>
         <faultcode>S:Server</faultcode>
         <faultstring>Customer name cannot be null or empty</faultstring>
      </S:Fault>
   </S:Body>
</S:Envelope>

Validation Rules

registerNewCustomer

SOAP Fault: Customer name is null or empty
Response: "Error: Customer already exists" (not a fault, returned as normal response)

processLoanApplication

SOAP Fault: Applicant name is null or empty
SOAP Fault: Requested amount is 0 or negative
Normal Response: Rejection due to blacklist or low credit score

HTTP Status Codes

Status Code	Description
200 OK	Request processed successfully (including business logic rejections)
500 Internal Server Error	SOAP fault or server error

Testing

Using Python Test Scripts

The project includes Python test clients for easy testing:

Unified Test Script (Recommended)

Test all services with a single comprehensive script:

cd scripts
python test_all_services.py

This script includes:

Automated test suite with 20+ test cases
Tests all three service operations
Interactive mode for manual testing
Clear pass/fail indicators with summary

Individual Service Tests

Test specific services:

# Test Hello World Service
python test_hello_world.py

# Test Customer Registration
python test_register_customer.py

Using cURL

Test Hello World Service

curl -X POST http://localhost:8080/jaxws-hello-world/hello \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: " \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ser="http://service.example.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getHelloWorld>
         <arg0>Test</arg0>
      </ser:getHelloWorld>
   </soapenv:Body>
</soapenv:Envelope>'

Register Customer

curl -X POST http://localhost:8080/jaxws-hello-world/loan \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: " \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ser="http://service.example.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:registerNewCustomer>
         <arg0>
            <customerName>John Doe</customerName>
            <blacklisted>false</blacklisted>
         </arg0>
      </ser:registerNewCustomer>
   </soapenv:Body>
</soapenv:Envelope>'

Process Loan Application

curl -X POST http://localhost:8080/jaxws-hello-world/loan \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: " \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ser="http://service.example.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:processLoanApplication>
         <arg0>
            <applicantName>John Doe</applicantName>
            <requestedAmount>50000</requestedAmount>
            <creditScore>720</creditScore>
         </arg0>
      </ser:processLoanApplication>
   </soapenv:Body>
</soapenv:Envelope>'

Using SoapUI

Create a new SOAP project
Import WSDL:
- HelloWorldService: http://localhost:8080/jaxws-hello-world/hello?wsdl
- LoanApprovalService: http://localhost:8080/jaxws-hello-world/loan?wsdl
SoapUI will automatically generate request templates
Fill in the parameters and execute requests

Checking the Database

After testing, you can inspect the SQLite database:

# View all customers
sqlite3 loan_app.db "SELECT * FROM customers;"

# View loan history
sqlite3 loan_app.db "SELECT * FROM loan_history;"

# View blacklisted customers
sqlite3 loan_app.db "SELECT * FROM customers WHERE is_blacklisted = 1;"

Production Considerations

Security

Authentication: No authentication is currently implemented (add WS-Security for production)
HTTPS: Use HTTPS in production environments
Input Validation: All inputs are validated for null/empty values
SQL Injection: Using PreparedStatements to prevent SQL injection

Database

Location: loan_app.db in project root (Docker volume mounted)
Persistence: Database persists between container restarts
Backup: Regular backups recommended for production

Performance

Connection Pooling: Consider adding connection pooling for production
Caching: Credit score service can be cached
Monitoring: Add logging and monitoring for production use

Configuration

Credit Score Service: Currently returns fixed value (700), integrate with real credit bureau API for production
Interest Rates: Rates are hardcoded, should be configurable
Database Path: Configurable via environment variable for different environments

Support

For issues and feature requests, please refer to the project README.md.

Project Repository: See README.md for deployment instructions Docker Support: Fully containerized with Docker Compose Test Scripts: Located in scripts/ directory

16 KiB Raw Blame History

API Documentation

Overview

Table of Contents

Services Overview

Hello World Service

Service Information

Methods

getHelloWorld

Loan Approval Service

Service Information

Methods

1. registerNewCustomer

2. processLoanApplication

Data Models

CustomerRegistrationRequest

LoanRequest

LoanResponse

Database Schema

customers

loan_history

Error Handling

SOAP Faults

Validation Rules

registerNewCustomer

processLoanApplication

HTTP Status Codes

Testing

Using Python Test Scripts

Unified Test Script (Recommended)

Individual Service Tests

Using cURL

Test Hello World Service

Register Customer

Process Loan Application

Using SoapUI

Checking the Database

Production Considerations

Security

Database

Performance

Configuration

Support

16 KiB

Raw Blame History