JiBX 1.2, Phần 1: Từ mã Java thành lược đồ XML Cải thiện chất lượng lược đồ phép biến đổi tùy chỉnh mơ hình liệu Java thành tài liệu XML từ tài liệu XML Dennis Sosnoski, Nhà tư vấn, Sosnoski Software Solutions, Inc Tóm tắt: Các định nghĩa lược đồ XML sở cho nhiều kiểu trao đổi liệu, bao gồm hầu hết dạng dịch vụ web Nhưng lược đồ XML tiêu chuẩn phức tạp hầu hết công cụ để tạo sửa đổi định nghĩa lược đồ không đủ mạnh mẽ hay dễ sử dụng công cụ để làm việc với mã Java™ Các đặc tính JiBX 1.2 mà bạn tìm hiểu hướng dẫn — Phần loạt viết có hai phần — cho phép bạn mã Java dễ dàng tạo định nghĩa lược đồ có chất lượng khớp với cấu trúc liệu bạn Sau bạn sử dụng trực tiếp lược đồ này, dù bạn có sử dụng liên kết liệu JiBX hay không Trước bạn bắt đầu Về hướng dẫn JiBX công cụ để liên kết liệu XML với đối tượng Java Liên kết liệu JiBX biết đến từ lâu cách tiếp cận nhanh linh hoạt để liên kết mã Java tới XML Nhưng phức tạp định nghĩa liên kết JiBX hỗ trợ cịn hạn chế với định nghĩa lược đồ XML sử dụng ngày rộng rãi làm cho người dùng thất vọng nhiều lần May mắn thay, phiên 1.2 JiBX tiến bước dài theo hướng loại bỏ vấn đề Trong hướng dẫn này, bạn tìm hiểu việc sử dụng đặc tính JiBX 1.2 để tạo định nghĩa lược đồ XML cách dễ dàng từ mã Java có để đọc viết tài liệu khớp với định nghĩa lược đồ tạo — hồn tồn khơng cần phải vào chi tiết định nghĩa liên kết JiBX Phần trình bày nửa cịn lại vấn đề: định nghĩa lược đồ XML tạo mã Java Mục tiêu Hướng dẫn dẫn cho bạn trình sử dụng JiBX để tạo định nghĩa lược đồ XML từ mã Java Đầu tiên, bạn thấy làm để bắt đầu với mơ hình liệu Java đơn giản tạo lược đồ mặc định khớp với mơ hình Trên sở đó, bạn tìm hiểu cách làm để bạn dễ dàng áp dụng loạt tuỳ chỉnh để kiểm soát giá trị thực tế sử dụng lớp Java bạn cách làm để truy cập chúng, cho dù chúng cần phải có (required) hay tùy chọn (optional); để kiểm soát tên không gian tên (namespaces) sử dụng XML chí để kiểm sốt cấu trúc định nghĩa lược đồ tạo Đồng thời, bạn thấy JiBX tăng thêm giá trị cho lược đồ bạn tạo sử dụng công sức đầu tư bạn vào Javadocs để làm tài liệu định nghĩa lược đồ cách tự động Sau đọc hướng dẫn thực ví dụ cung cấp, bạn có khả sử dụng JiBX để tạo định nghĩa lược đồ XML có chất lượng từ lớp cấu trúc liệu Java riêng bạn Các điều kiện cần có trước Để hiểu hướng dẫn này, bạn nên có kiến thức mã Java XML Bạn không cần phải hiểu biết chi tiết định nghĩa lược đồ XML quen thuộc với lược đồ giúp bạn hiểu ví dụ tốt Các yêu cầu hệ thống Để chạy ví dụ này, bạn cần phải cài đặt:  Cả hai: o o  Sun's JDK 1.5.0_09 (hoặc hơn) Bộ dụng cụ nhà phát triển IBM cho công nghệ Java 1.5.0 SR3 Một phiên công cụ xây dựng Apache Ant Các hướng dẫn tải cài đặt JiBX có hướng dẫn Bắt đầu Trong phần này, bạn có nhìn tổng quan JiBX bạn cài đặt JiBX mã lệnh mẫu hướng dẫn Giới thiệu JiBX JiBX nhiều công cụ dùng để chuyển đổi cấu trúc liệu Java tài liệu XML (Tài nguyên) Cái làm nên khác biệt JiBX so với công cụ khác đặc tính linh hoạt hiệu Hiệu JiBX ln đánh giá vị trí cao lĩnh vực này, vượt hai lần so với hiệu công cụ phổ biến khác (như JAXB 2.0 chẳng hạn) JiBX linh hoạt hầu hết tất công cụ Java-XML khác, sử dụng định nghĩa liên kết để tách cấu trúc Java khỏi biểu diễn XML cho thay đổi độc lập với Với phát hành 1.2, JiBX bổ sung thêm đặc tính hỗ trợ định nghĩa lược đồ XML Bạn sử dụng công cụ kèm theo phát hành JiBX để tạo định nghĩa lược đồ khớp với mã Java bạn để tạo mã Java khớp với định nghĩa lược đồ bạn Dù cách nào, bạn nhận định nghĩa liên kết phép bạn sử dụng JiBX để chuyển đổi mã Java tài liệu XML khớp với định nghĩa lược đồ Trong hướng dẫn này, bạn thấy cách làm để áp dụng kiểu tạo mã đầu tiên: từ mã Java sinh định nghĩa lược đồ Cài đặt JiBX Bạn cần phải cài đặt JiBX trước tiếp tục thực hướng dẫn Hãy tải ZIP phân phối 1.2.x giải nén vào chỗ thuận tiện hệ thống bạn Xong việc, bạn nhận thư mục có tên jibx, có chứa tất tệp JiBX JAR, tài liệu hướng dẫn, ví dụ chí mã nguồn Cài đặt mã nguồn ví dụ hướng dẫn Bây tải mã mẫu, hướng dẫn này, cung cấp dạng tệp tin ZIP Cách dễ để cài đặt hệ thống bạn giải nén tệp tin ZIP vào thư mục gốc phân phối JiBX bạn (hoặc Windows®, chép thư mục dwcode1 từ bên tệp tin ZIP vào thư mục gốc phân phối JiBX bạn) Điều tạo thư mục dwcode1 thư mục jibx, với tệp tin ví dụ (bao gồm tệp tin build.xml, custom1.xml tệp tin khác) bên thư mục dwcode1 Mã mẫu bao gồm tệp tin xây dựng Ant Apache để tự động hố cho chạy cơng cụ JiBX xử lý bước khác có ví dụ Nếu bạn cài đặt mã mẫu trực tiếp vào thư mục cài đặt JiBX, công cụ xây dựng (build) truy cập tệp JiBX JAR mà khơng cần thêm cấu hình Nếu bạn cài đặt mã mẫu nơi khác, bạn sử dụng cơng cụ xây dựng Ant Trong trường hợp này, bạn cần thiết lập biến môi trường JIBX_HOME rõ đường dẫn đến cài đặt JiBX bạn Ngoài ra, cách khác bạn chỉnh sửa tệp tin build.xml-bên thư mục mã mẫu bỏ dấu thích đầu dịng phía tệp tin, nơi trực tiếp thiết lập thuộc tính jibxhome Tạo liên kết mặc định lược đồ từ mã Java Cách sử dụng cho trường hợp Java Mã ví dụ hướng dẫn sử dụng đặc tính bảng kê (enum) sưu tập có định kiểu Java 5, thân JiBX hồn tồn tương thích với phiên Java cũ Môi trường chạy JiBX tiêu chuẩn làm việc với JVM phiên 1.3 và xây dựng để tương thích với J2ME Hầu hết thành phần khác JiBX bao gồm BindGen, chạy JVM phiên 1.4.1 Tài liệu BindGen tải JiBX có ví dụ rõ cách tùy chỉnh để cung cấp cho BindGen thay tương đương sưu tập có định kiểu bạn sử dụng mã Java cũ phiên Java Thật dễ dàng để tạo định nghĩa liên kết JiBX định nghĩa lược đồ XML tương ứng từ mã Java Bạn tìm hiểu cách làm phần Giới thiệu mã ví dụ Java Như ví dụ, tơi bắt đầu với mã Java cho tập lớp theo phong cách bean (các trường liệu riêng-private phương thức set phương thức get chung-public) dùng để mô tả đơn hàng từ cửa hàng trực tuyến Listing hiển thị phiên mã rút gọn, bỏ qua hầu hết phương thức get/set Toàn mã mẫu hoàn chỉnh nằm thư mục src mã mẫu Listing Mã Java sở package org.jibx.starter; /** * Order information */ public class Order { private long orderNumber; private Customer customer; /** Billing address information */ private Address billTo; private Shipping shipping; /** Shipping address information If missing, the billing address is also used as the shipping address */ private Address shipTo; private List items; /** Date order was placed with server */ private Date orderDate; /** Date order was shipped This will be null if the order has not yet shipped */ private Date shipDate; private Float total; public long getOrderNumber() { return orderNumber; } } /** * Customer information */ public class Customer { private long customerNumber; /** Personal name */ private String firstName; /** Family name */ private String lastName; /** Middle name(s), if any */ private List middleNames; } /** * Address information */ public class Address { /** First line of street information (required) */ private String street1; /** Second line of street information (optional) */ private String street2; private String city; /** State abbreviation (required for the U.S and Canada, optional otherwise) */ private String state; /** Postal code (required for the U.S and Canada, optional otherwise) */ private String postCode; /** Country name (optional, U.S assumed if not supplied) */ private String country; } /** * Order line item information */ public class Item { /** Stock identifier This is expected to be 12 characters in length, with two leading alpha characters followed by ten decimal digits */ private String id; /** Text description of item */ private String description; /** Number of units ordered */ private int quantity; /** Price per unit */ private float price; } /** * Supported shipment methods The "INTERNATIONAL" shipment methods can only be used for * orders with shipping addresses outside the U.S., and one of these methods is required * in this case */ public enum Shipping { STANDARD_MAIL, PRIORITY_MAIL, INTERNATIONAL_MAIL, DOMESTIC_EXPRESS, INTERNATIONAL_EXPRESS } Tạo liên kết lược đồ mặc định Để tạo liên kết JiBX lược đồ XML từ số lớp Java, bạn cần phải biên dịch lớp, sau chạy cơng cụ org.jibx.binding.generator.BindGen có jibx-tools.jar từ phân phối JiBX Bạn chạy trực tiếp cơng cụ từ dịng lệnh gián tiếp thơng qua công cụ xây dựng Ant Trong tệp tải hướng dẫn có chứa kịch lệnh Ant build.xml với đích compile để biên dịch mã ví dụ đích bindgen để chạy chương trình BindGen mã biên dịch Để thử làm việc này, mở cửa sổ lệnh thư mục dwcode1 nơi cài đặt ví dụ tải gõ ant compile bindgen Nếu Ant cài đặt hệ thống bạn cài đặt mã tải xuống theo dẫn, bạn thấy kết tương tự hiển thị Hình 1: Address information. Sau biên dịch liên kết cách sử dụng tác vụ Ant bind, bạn kiểm tra điều cách sử dụng tác vụ run2 dùng tài liệu thử nghiệm data2.xml làm đầu vào tạo kết đầu out2.xml Bạn chạy tồn chuỗi tác vụ từ biên dịch đến kiểm thử với đích custom2 Listing 10 cho thấy tài liệu thử nghiệm: Listing 10 Tài liệu thử nghiệm khớp với tùy chỉnh 12345678 5678 John Smith 12345 Happy Lane Plunk USA PRIORITY_MAIL 333 River Avenue Kirkland So sánh Listing 10 với tài liệu thử nghiệm ban đầu, hiển thị Listing 3, để xem tùy chỉnh bạn làm thay đổi biểu diễn liệu XML (bao gồm việc thay đổi dạng dòng biểu diễn mục hàng thành phần tử rỗng, cách biểu diễn cô đọng nhiều so với tài liệu ban đầu) Kiểm sốt tên khơng gian tên Các tên Java thông thường sử dụng kiểu dáng “bướu lạc đà” (camelcase): tên hầu hết chữ thường chữ từ viết hoa Đối với tên trường tên thuộc tính, áp dụng viết chữ hoa ban đầu từ sau từ (dẫn đến tên có dạng postCode customerNumber) Các tên XML khơng tiêu chuẩn hóa có vài kiểu dáng khác thường sử dụng Trong gồm có kiểu dáng “bướu lạc đà” với chữ thường (giống kiểu dáng tên trường tên thuộc tính Java), kiểu dáng “bướu lạc đà” với chữ viết hoa (giống kiểu dáng tên lớp Java), kiểu dáng phân cách vạch ngang (các từ phân cách dấu gạch ngang), kiểu dáng phân cách dấu chấm (các từ phân cách dấu chấm) kiểu dáng phân cách gạch (các từ phân cách dấu gạch dưới) BindGen giả định dùng kiểu dáng bướu lạc đà cho tên XML theo mặc định, bạn dễ dàng thay đổi điều cách thiết lập thuộc tính name-style mức tùy chỉnh (phần tử (, , hay ) Các giá trị hợp lệ cho thuộc tính khớp với kiểu dáng XML khác liên kê trên:  Kiểu bướu lạc đà mặc định)  Kiểu bướu lạc đà, chữ hoa  Có dấu nối  Có nhiều dấu chấm  Có dấu gạch Bạn thiết lập tên XML cho giá trị cách sử dụng riêng tùy chỉnh cho giá trị Việc sử dụng tùy chỉnh giá trị riêng lẻ cho phép bạn tồn quyền kiểm sốt hai mặt, làm để truy nhập giá trị biểu diễn XML giá trị Listing 11 đưa số ví dụ việc sử dụng phần tử tùy chỉnh cho giá trị riêng lẻ, dựa mã mẫu giống mà bạn thấy ví dụ trên: Listing 11 Tùy chỉnh tên không gian tên Tùy chỉnh giá trị Listing 11 dành cho thuộc tính orderNumber bên phần tử Bằng cách sử dụng thuộc tính element="order-num", tùy chỉnh orderNumber lệnh cho BindGen diễn tả giá trị phần tử, khơng phải dạng thuộc tính mặc định sử dụng cho giá trị nguyên thủy Tùy chỉnh thứ hai dành cho thuộc tính sưu tập mục hàng Tùy chỉnh sử dụng hai thuộc tính item-name element Thuộc tính item-name kiểm sốt tên sử dụng cho giá trị riêng lẻ mà sưu tập biểu diễn, thuộc tính element bắt buộc sử dụng tên cung cấp phần tử bao gói giá trị sưu tập XML khơng có khơng gian tên Tất ví dụ hướng dẫn sử dụng không gian tên XML việc sử dụng khơng gian tên thường coi thói quen thực tế tốt cho việc trao đổi liệu Nếu bạn muốn làm việc với XML mà khơng có khơng gian tên, bạn sử dụng thuộc tính namespace-style="none" mức tùy chỉnh để tắt hoàn toàn không gian tên cho tất thành phần lồng bên Các tùy chỉnh Listing 11 định nghĩa không gian tên sử dụng tài liệu XML Các ví dụ trước dựa vào BindGen xử lý mặc định không gian tên, cụ thể lấy URI không gian tên dùng biểu diễn XML mã Java gói Java Việc xử lý mặc định chuyển đổi gói org.jibx.starter thành URI không gian tên http://jibx.org/starter Trong Listing 11, không gian tên tùy chỉnh cách thêm cặp hai thuộc tính — namespace="http://jibx.org/custom" namespace-style="fixed" — phần tử gốc Thuộc tính định nghĩa khơng gian tên sở, cịn thuộc tính thứ hai ngăn chặn hành vi thông thường sửa đổi không gian tên dựa vào gói Java Cả hai thuộc tính thừa kế xuyên qua phần tử tùy chỉnh lồng vào nhau, chúng dễ dàng đặt vào phần tử thay phần tử Bạn thử nghiệm tùy chỉnh Listing 11 cách sử dụng đích Ant custgen3 để tạo lược đồ liên kết đích run3 để chạy phép thử nghiệm (sau sử dụng đích bind tiêu chuẩn để chạy trình biên dịch liên kết JiBX — cần sử dụng đích full3 để thực toàn chuỗi tác vụ) Listing 12 hiển thị tài liệu đầu vào sử dụng với mã thử nghiệm: Listing 12 Mẫu XML với tên không gian tên tùy chỉnh 12345678 5678 John Smith 12345 Happy Lane Plunk USA PRIORITY_MAIL 333 River Avenue Kirkland Nếu bạn so sánh mẫu Listing 12 với mẫu Listing 10 bạn thấy biểu diễn XML thay đổi tùy chỉnh Tùy chỉnh biểu diễn lược đồ Bây bạn thấy tùy chỉnh BindGen thay đổi biểu diễn XML liệu Java bạn Các tùy chỉnh sử dụng để kiểm sốt số khía cạnh cấu trúc lược đồ thực tế Hãy nhớ lại BindGen mặc định sử dụng định nghĩa lồng kiểu phần tử toàn cục Nếu bạn xem lại lược đồ tạo Listing bạn thấy cấu trúc lồng Lược đồ sử dụng ba định nghĩa toàn cầu: kiểu phức hợp địa (address) đơn hàng (order) phần tử order Các lớp khác cấu trúc liệu Java (Customer, Item, Shipping) thứ tham chiếu điểm lớp Order định nghĩa kiểu tương ứng nhúng trực tiếp định nghĩa kiểu lược đồ order Bạn thay đổi kiểu dáng lược đồ cách sử dụng thuộc tính force-mapping="true" phần tử tùy chỉnh lồng Listing13 cho thấy tệp tin tùy chỉnh custom4.xml, bổ sung thêm thay đổi cho tùy chỉnh custom2.xml khớp với lược đồ tạo Listing 9: Listing 13 Tùy chỉnh cho cấu trúc lược đồ Listing 14 hiển thị cấu trúc lược đồ kết (là tệp starter.xsd tạo cách chạy đích custgen4) Phiên lược đồ biểu diễn cấu trúc tài liệu XML giống lược đồ Listing bao gồm định nghĩa kiểu riêng biệt khớp với lớp Java Listing 14 Cấu trúc lược đồ tùy chỉnh Supported shipment methods The "INTERNATIONAL" shipment methods can only be used for orders with shipping addresses outside the U.S., and one of these methods is required in this case. Order line item information. Address information. Customer information. Order information. Get the order number. Các lược đồ theo kiểu hiển thị Listing 14, gọi lược đồ kiểu "Cửa chớp lật" (Venetian Blind) sử dụng phổ biến định nghĩa cấu trúc XML phức hợp Bằng cách tách riêng định nghĩa kiểu, lược đồ kiểu cho phép bạn dễ dàng sử dụng lại cấu trúc thành phần sửa đổi mở rộng lược đồ Tính linh hoạt lược đồ kiểu “Venetian Blind” khơng quan trọng bạn lập kế hoạch để sử dụng mã Java bạn làm sở cho thay đổi thêm khác (chạy lại BindGen thay đổi mã bạn), tốt hơn, bạn dự định sử dụng lược đồ làm sở cho phát triển Các tham số dòng lệnh BindGen BindGen hỗ trợ số tham số dịng lệnh ngồi tham số dùng mã hướng dẫn Bảng liệt kê tùy chọn quan trọng nhất: Bảng Các tùy chọn dòng lệnh BuildGen Command Purpose -b name Tên tệp tin định nghĩa liên kết gốc tạo (tên mặc định binding.xml) -c path Đường dẫn đến tệp tin tùy chỉnh đầu vào Cho cặp URI không gian tên lược đồ -n uri=name, tên-tệp tin (mặc định tạo tên tệp tin từ URI không gian tên lược đồ) -p path, Các đường dẫn để nạp tệp tin lớp Java (mặc định đường dẫn sử dụng để chạy BindGen) -s path, Các đường dẫn để nạp tệp mã nguồn Java (nguồn không sử dụng theo mặc định) -t path Đường dẫn thư mục đích dành cho kết đầu tạo (mặc định thư mục tại) -w Xoá tất tệp tin khỏi thư mục đích trước sinh kết đầu (bỏ qua thư mục đích thư mục tại) Bạn chuyển cho BindGen tùy chỉnh toàn cục dạng tham số dịng lệnh mà khơng cần phải tạo tệp tin tùy chỉnh, cách sử dụng kí hiệu làm tiền tố dành riêng cho giá trị thuộc tính tùy chỉnh Ví dụ để thiết lập tùy chọn toàn cầu giống dùng tùy chỉnh Listing 13, bạn cần thêm property-access=true force-mapping=true vào dòng lệnh BindGen Không cần dùng dấu nháy kép cho giá trị thuộc tính bạn sử dụng kỹ thuật Nếu bạn muốn thiết lập tùy chỉnh cho danh sách nhiều giá trị, sử dụng dấu phẩy để phân cách giá trị riêng lẻ khoảng trống (Ví dụ, để bỏ qua tiền tố m_ s_ trước tên trường, bạn sử dụng tham số dòng lệnh strip-prefixes=m_,s_) Tiến xa Trong hướng dẫn này, bạn học điều cách sử dụng JiBX để tạo định nghĩa lược đồ XML từ mã Java bạn sau chuyển đổi tài liệu XML khớp với lược đồ thành cấu trúc liệu Java ngược lại Có nhiều tùy chỉnh khác mà bạn sử dụng để kiểm sốt việc tạo lược đồ, ngồi thứ mà tơi trình bày hướng dẫn Các tài liệu JiBX cung cấp đầy đủ chi tiết tất lựa chọn tùy chỉnh ấy, với nhiều ví dụ việc tạo lược đồ từ mã Java Bạn chí tiến xa với JiBX cách làm việc với định nghĩa liên kết thực tế; cho phép bạn kiểm sốt tất bước q trình biến đổi Bạn dễ dàng thêm mã riêng bạn mà thực phần phép biến đổi, sử dụng móc nối phần mở rộng người dùng xây dựng vào định nghĩa liên kết Bạn chí tự viết mã lệnh hóa khơng hóa tùy biến riêng bạn để chúng kiểm sốt có chọn lọc mã JiBX tạo để xử lý cấu trúc XML cấu trúc liệu Java Tài liệu JiBX bao gồm hướng dẫn để minh họa nhiều khía cạnh làm việc với định nghĩa liên kết, bao gồm đặc tính mở rộng này, với tài liệu tham khảo có tất thơng tin chi tiết JiBX đặc biệt tiện lợi bạn muốn phát triển định nghĩa lược đồ cách nhanh chóng để trao đổi liệu mà khơng cần phải tìm hiểu nhiều lược đồ Lược đồ XML tiêu chuẩn phức tạp công cụ để làm việc với định nghĩa lược đồ cung cấp hỗ trợ cho việc tổ chức lại cấu trúc lại lược đồ Bằng cách sử dụng mã Java BindGen làm sở cho phát triển lược đồ bạn hướng dẫn này, bạn áp dụng tất tính linh hoạt IDE Java để tạo định nghĩa lược đồ cách nhanh chóng dễ dàng mà khơng phải tự cam kết sử dụng JiBX JiBX bao gồm công cụ để tạo đầy đủ định nghĩa lược đồ WSDL cho dịch vụ Web dựa mã Java Cơng cụ này, có tên Jibx2Wsdl, xây dựng bên BindGen Bạn sử dụng tất tuỳ chỉnh BindGen bàn luận viết cho lớp liệu sử dụng làm đầu vào đầu cho phương thức dịch vụ bạn, cho lược đồ tạo phản ánh sở thích bạn Tài liệu JiBX cung cấp chi tiết cách sử dụng Jibx2Wsdl Trong Phần 2, bạn tìm hiểu cách sử dụng JiBX để tạo mã Java từ định nghĩa lược đồ XML ... diễn XML thay đổi tùy chỉnh Tùy chỉnh biểu diễn lược đồ Bây bạn thấy tùy chỉnh BindGen thay đổi biểu diễn XML liệu Java bạn Các tùy chỉnh sử dụng để kiểm sốt số khía cạnh cấu trúc lược đồ thực... này, bạn học điều cách sử dụng JiBX để tạo định nghĩa lược đồ XML từ mã Java bạn sau chuyển đổi tài liệu XML khớp với lược đồ thành cấu trúc liệu Java ngược lại Có nhiều tùy chỉnh khác mà bạn... kết phép bạn sử dụng JiBX để chuyển đổi mã Java tài liệu XML khớp với định nghĩa lược đồ Trong hướng dẫn này, bạn thấy cách làm để áp dụng kiểu tạo mã đầu tiên: từ mã Java sinh định nghĩa lược đồ