SOA Practice 01 - 521H0476

Dự án REST API sử dụng Jersey framework với các chức năng quản lý sinh viên và tính toán thời gian.

Yêu cầu hệ thống

• Java 8 hoặc cao hơn
• Maven 3.6 hoặc cao hơn
• Apache Tomcat 8.5 hoặc cao hơn (nếu deploy riêng)

Cài đặt và Chạy Dự án

Bước 1: Chuẩn bị môi trường

Kiểm tra Java 8

Mở Command Prompt hoặc PowerShell và chạy:

java -version

Kết quả mong đợi: openjdk version "1.8.0_xxx"

Kiểm tra Maven

# Thiết lập PATH cho Maven cục bộ (nếu cần)
$env:PATH = "$HOME\.maven\apache-maven-3.9.9\bin;$env:PATH"
mvn -version

Bước 2: Build dự án

# Di chuyển vào thư mục dự án
cd "C:\...\521H0476_Solution1"

# Build và chạy test
mvn clean test package

# Kiểm tra WAR file đã tạo
ls target\*.war

Bước 3: Chạy dự án

Cách 1: Chạy nhúng với Maven (Khuyến nghị - Nhanh nhất)

# Chạy dự án nhúng (không cần cài Tomcat riêng)
mvn tomcat7:run

Sau khi chạy thành công, truy cập: http://localhost:8080/SOA_Practice_01_521H0476/

Cách 2: Deploy lên Tomcat

1. Tải Tomcat 8.5.98

   • Truy cập: https://tomcat.apache.org/download-80.cgi
   • Tải file: apache-tomcat-8.5.98.zip (Core)

2. Cài đặt và chạy

   # Giải nén vào C:\apache-tomcat-8.5.98
   
   # Copy WAR file vào webapps
   copy target\SOA_Practice_01_521H0476.war C:\apache-tomcat-8.5.98\webapps\
   
   # Khởi động Tomcat
   C:\apache-tomcat-8.5.98\bin\startup.bat
   
   # Kiểm tra Tomcat đã chạy: http://localhost:8080

3. Truy cập ứng dụng

   • Trang chủ: http://localhost:8080/SOA_Practice_01_521H0476/
   • API Documentation: Xem phần API Endpoints bên dưới

API Endpoints

Calculator API

Lấy thời gian theo timezone

Method: GET Endpoint: /api/calc/GetDateTime Parameters: location (optional, default: UTC)

Ví dụ sử dụng:

curl "http://localhost:8080/SOA_Practice_01_521H0476/api/calc/GetDateTime?location=UTC"
curl "http://localhost:8080/SOA_Practice_01_521H0476/api/calc/GetDateTime?location=Asia/Ho_Chi_Minh"

Student API

Kiểm tra sinh viên tồn tại

• Method: GET
• Endpoint: /api/students/exists
• Parameters: id

Tìm kiếm sinh viên

• Method: GET
• Endpoint: /api/students/search
• Parameters: id

Lấy thông tin sinh viên

• Method: GET
• Endpoint: /api/students/{id}
• Parameters: id (path param)

Cập nhật tên sinh viên

• Method: POST
• Endpoint: /api/students/changeName
• Parameters: id, name (form data)

Cập nhật giới tính

• Method: POST
• Endpoint: /api/students/changeGender
• Parameters: id, gender (form data)

Cập nhật ngành học

• Method: POST
• Endpoint: /api/students/changeMajor
• Parameters: id, major (form data)

Echo sinh viên (JSON)

• Method: POST
• Endpoint: /api/students
• Parameters: JSON body

Ví dụ sử dụng:

# Kiểm tra sinh viên tồn tại
curl "http://localhost:8080/SOA_Practice_01_521H0476/api/students/exists?id=S001"

# Lấy thông tin sinh viên
curl "http://localhost:8080/SOA_Practice_01_521H0476/api/students/S001"

# Cập nhật tên sinh viên
curl -X POST "http://localhost:8080/SOA_Practice_01_521H0476/api/students/changeName" -d "id=S001" -d "name=Nguyen Van A"

# Cập nhật giới tính (1=Nam, 0=Nữ)
curl -X POST "http://localhost:8080/SOA_Practice_01_521H0476/api/students/changeGender" -d "id=S001" -d "gender=1"

# Cập nhật ngành học
curl -X POST "http://localhost:8080/SOA_Practice_01_521H0476/api/students/changeMajor" -d "id=S001" -d "major=Computer Science"

# Gửi JSON sinh viên
curl -X POST "http://localhost:8080/SOA_Practice_01_521H0476/api/students" -H "Content-Type: application/json" -d "{\"id\":\"S999\",\"name\":\"Test Student\",\"gender\":1,\"major\":\"IT\"}"

Chạy Tests

# Chạy tất cả tests
mvn test

# Chạy test cụ thể
mvn test -Dtest=CalculatorResourceTest
mvn test -Dtest=StudentResourceTest

Cấu trúc dự án

src/
├── main/
│   ├── java/com/soa/SOA_Practice_01_521H0476/
│   │   ├── api/           # REST Controllers
│   │   │   ├── CalculatorResource.java
│   │   │   └── StudentResource.java
│   │   ├── model/         # Data Models
│   │   │   └── Student.java
│   │   └── repo/          # Data Repository
│   │       └── StudentRepository.java
│   ├── resources/
│   │   └── mock/          # Mock Data
│   │       └── students.json
│   └── webapp/
│       ├── index.html     # Trang chủ
│       └── WEB-INF/
│           └── web.xml    # Web Configuration
└── test/
    └── java/com/soa/SOA_Practice_01_521H0476/
        └── api/           # Unit Tests
            ├── CalculatorResourceTest.java
            └── StudentResourceTest.java

Công nghệ sử dụng

• Java 8
• Maven 3.9.9
• Jersey 2.46 (JAX-RS implementation)
• Jackson (JSON processing)
• Joda-Time 2.12.7 (Date/Time handling)
• JUnit 4.13.2 (Testing)
• Apache Tomcat 8.5.98 (Servlet Container)

Xử lý lỗi thường gặp

Lỗi "Could not find or load main class org.apache.maven.wrapper.MavenWrapperMain"

# Sử dụng Maven cục bộ thay vì mvnw
$env:PATH = "$HOME\.maven\apache-maven-3.9.9\bin;$env:PATH"
mvn clean package

Lỗi "Input length = 1" khi build

• Đã được sửa trong pom.xml với useIncrementalCompilation=false

Lỗi "InjectionManagerFactory not found"

• Đã được sửa bằng cách thêm jersey-hk2 dependency

Port 8080 đã được sử dụng

# Thay đổi port trong pom.xml
<configuration>
  <port>8081</port>  <!-- Thay 8080 thành 8081 -->
  <path>/SOA_Practice_01_521H0476</path>
</configuration>

Lỗi 404 Not Found

• Kiểm tra context path: http://localhost:8080/SOA_Practice_01_521H0476/
• Đảm bảo WAR file đã được deploy đúng cách
• Kiểm tra log Tomcat để xem lỗi cụ thể

Lỗi 500 Internal Server Error

• Kiểm tra log Tomcat: C:\apache-tomcat-8.5.98\logs\localhost*.log
• Đảm bảo tất cả dependencies đã được thêm vào pom.xml
• Kiểm tra cấu hình web.xml

Ghi chú quan trọng

• Dữ liệu sinh viên được load từ src/main/resources/mock/students.json
• API trả về JSON format
• Timezone hỗ trợ theo chuẩn IANA (ví dụ: UTC, Asia/Ho_Chi_Minh)
• Dự án sử dụng package com.soa.SOA_Practice_01_521H0476
• Context path của ứng dụng là /SOA_Practice_01_521H0476

Lệnh chạy nhanh

# Build và chạy trong 1 lệnh
mvn clean package && mvn tomcat7:run

# Truy cập: http://localhost:8080/SOA_Practice_01_521H0476/

Kiểm tra ứng dụng hoạt động

1. Truy cập trang chủ: http://localhost:8080/SOA_Practice_01_521H0476/
2. Test API thời gian: http://localhost:8080/SOA_Practice_01_521H0476/api/calc/GetDateTime?location=UTC
3. Test API sinh viên: http://localhost:8080/SOA_Practice_01_521H0476/api/students/exists?id=S001

Dừng ứng dụng

Nếu chạy với Maven Tomcat plugin:

• Nhấn Ctrl+C trong terminal

Nếu chạy với Tomcat riêng:

C:\apache-tomcat-8.5.98\bin\shutdown.bat

Xem log lỗi

# Log Tomcat chính
Get-Content "C:\apache-tomcat-8.5.98\logs\catalina*.log" -Tail 50

# Log ứng dụng cụ thể
Get-Content "C:\apache-tomcat-8.5.98\logs\localhost*.log" -Tail 50