Mô Tả Vấn Đề

Khi triển khai các ứng dụng dựa trên Spring Boot hoặc sử dụng các thư viện ORM phổ biến lên máy chủ TongWeb phiên bản 7, người quản trị có thể gặp phải hàng loạt ngoại lệ gây cản trở quy trình khởi động. Các lỗi điển hình bao gồm việc không thể tải các chuẩn Java EE như EJB, JPA, CDI hay JavaMail.

Dưới đây là một ví dụ về vết xếp chồng (stack trace) thường thấy:

Caused by: com.tongweb.tongebj.OpenEJBException: 
  Không thể khởi tạo bộ quét chú thích cho mô-đun web: null
    at com.tongweb.tongebj.config.DeploymentLoader.addWebModule(...)
    ...
Caused by: java.lang.IllegalArgumentException
    at com.tongweb.xbean.asm5.ClassReader.<init>(...)

Bên cạnh đó, hệ thống đôi khi báo lỗi thiếu tài nguyên:

Caused by: java.util.MissingResourceException:
  Không tìm thấy gói LocalStrings cho com.tongweb.xml.messaging.saaj.soap

Tổng hợp các dấu hiệu này thường dẫn đến thất bại khi ứng dụng cố gắng nhúng các component EJB hoặc xử lý JPA.

Nguyên Nhân Cốt Lõi

Vấn đề này nảy sinh do sự giao thoa trong cơ chế tải lớp (Class Loading). Các ứng dụng hiện đại thường đóng gói sẵn các thư viện như Hibernate, EclipseLink, Spring Data JPA hoặc Hibernate Validator vào trong WAR/JAR của chúng. Trong khi đó, TongWeb tích hợp sẵn đầy đủ các đặc tả Java EE 6 (bao gồm JPA, Validation, CDI, EJB...).

Khi cả hai đều cố gắng kiểm soát cùng một lớp (class) từ thư mục khác nhau, xung đột xảy ra khiến trình tải lớp của TongWeb không thể giải mã đúng định nghĩa lớp, dẫn đến lỗi khởi tạo bộ quét chú thích (Annotation Scanner).

Phương Pháp Khắc Phục

Để giải quyết tình trạng này, giải pháp tối ưu là cấu hình lại TongWeb nhằm tách biệt môi trường thực thi. Cụ thể, hãy kích hoạt chế độ chỉ chứa Web Container bằng cách thêm tham số JVM tùy chỉnh.

1. Truy cập vào thư mục cài đặt TongWeb của bạn.
2. Mở tập tin cấu hình tại đường dẫn: ${TW_HOME}/bin/external.vmoptions.
3. Thêm dòng lệnh sau vào cuối tập tin:

Lưu ý quan trọng: Sau khi lưu thay đổi, bạn bắt buộc phải khởi động lại toàn bộ dịch vụ TongWeb để các tùy chọn JVM mới được áp dụng.

Hướng Dẫn Kỹ Thuật Và Lời Khuyên

Việc áp dụng cờ WebModuleOnly sẽ vô hiệu hóa các tính năng quản lý container của TongWeb đối với Java EE, chuyển nó sang hoạt động như một Servlet Container thuần túy. Hãy cân nhắc kỹ trước khi áp dụng dựa trên kiến trúc ứng dụng.

Trường Hợp Nên Áp Dụng:

• Ứng dụng xây dựng hoàn toàn trên nền tảng Spring Boot (các phiên bản 2.x hoặc 3.x).
• Gặp phải lỗi xung đột tên lớp liên quan đến JPA, Validation hoặc CDI trong quá trình triển khai.
• Không yêu cầu sử dụng EJB Stateful/Stateless hoặc quản lý giao dịch do Server cung cấp.
• Cần cải thiện tốc độ khởi động mà không cần các tính năng Enterprise nặng nề.

Trường Hợp Không Nên Sử Dụng:

• Ứng dụng phụ thuộc trực tiếp vào khả năng quản lý giao dịch JPA của TongWeb.
• Sử dụng các thành phần EJB truyền thống được tích hợp trong môi trường TongWeb.
• Đang tận dụng tính năng tích hợp JSF (Mojarra) do TongWeb cung cấp.