Pengenalan kepada JAX-WS

Pengaturcaraan

1. Gambaran keseluruhan

Java API for XML Web Services (JAX-WS) adalah API standard untuk membuat dan menggunakan perkhidmatan web SOAP (Simple Object Access Protocol).

Dalam artikel ini, kami akan membuat perkhidmatan web SOAP dan menyambung dengannya menggunakan JAX-WS.

2. Sabun

SOAP adalah spesifikasi XML untuk mengirim mesej melalui rangkaian. Mesej SOAP tidak bergantung pada sistem operasi apa pun dan dapat menggunakan pelbagai protokol komunikasi termasuk HTTP dan SMTP.

SOAP adalah berat XML, oleh itu paling baik digunakan dengan alat / kerangka kerja. JAX-WS adalah kerangka kerja yang mempermudah penggunaan SOAP. Ia adalah sebahagian daripada Java standard.

3. Atas-Bawah vs Bawah-Atas

Terdapat dua cara untuk membina perkhidmatan web SOAP. Kita boleh pergi dengan pendekatan atas-bawah atau pendekatan bawah-atas.

Dalam pendekatan top-down (kontrak-pertama), dokumen WSDL dibuat, dan kelas Java yang diperlukan dihasilkan dari WSDL. Dalam pendekatan bottom-up (contract-last), kelas Java ditulis, dan WSDL dihasilkan dari kelas Java.

Menulis fail WSDL agak sukar bergantung pada seberapa kompleks perkhidmatan web anda. Ini menjadikan pendekatan bawah-atas menjadi pilihan yang lebih mudah. Sebaliknya, kerana WSDL anda dihasilkan dari kelas Java, setiap perubahan kod boleh menyebabkan perubahan pada WSDL. Ini bukan masalah pendekatan top-down.

Dalam artikel ini, kita akan melihat kedua pendekatan tersebut.

4. Bahasa Definisi Perkhidmatan Web (WSDL)

WSDL adalah definisi kontrak bagi perkhidmatan yang ada. Ini adalah spesifikasi pesan input / output, dan cara menggunakan perkhidmatan web. Ia tidak berbahasa dan didefinisikan dalam XML.

Mari lihat elemen utama dokumen WSDL.

4.1. Definisi

The definisi unsur unsur akar semua dokumen WSDL. Ini menentukan nama, ruang nama, dan lain-lain perkhidmatan dan, seperti yang anda lihat, boleh cukup luas:

 ...

4.2. Jenis-Jenis

Yang jenis elemen mentakrifkan jenis data yang digunakan oleh perkhidmatan web. WSDL menggunakan XSD (XML Schema Definition) sebagai sistem jenis yang membantu dengan operasi:

 ...      ...

4.3. Mesej

The mesej elemen menyediakan definisi abstrak data yang dihantar. Setiap elemen mesej menerangkan input atau output kaedah perkhidmatan dan kemungkinan pengecualian:

 ...          ...

4.4. Jenis Operasi dan Pelabuhan

The portType unsur menerangkan setiap operasi yang boleh dilakukan dan semua mesej unsur-unsur yang terlibat. Sebagai contoh, operasi getEm Employee menentukan permintaan input , output dan kemungkinan pengecualian kesalahan yang dilemparkan oleh operasi perkhidmatan web :

 ...       ....  ...

4.5. Ikatan

Yang mengikat unsur menyediakan protokol dan format data butiran bagi setiap portType :

 ...               ...  ...

4.6. Perkhidmatan dan Pelabuhan

The perkhidmatan elemen mentakrifkan pelabuhan disokong oleh perkhidmatan web. The port elemen dalam perkhidmatan mentakrifkan nama , mengikat dan alamat perkhidmatan:

 ...      ...

5. Pendekatan Top-Down (Kontrak-Pertama)

Mari mulakan dengan pendekatan top-down dengan membuat file WSDL karyawanervicetopdown.wsdl. Demi kesederhanaan, hanya ada satu kaedah:

5.1. Menjana Fail Sumber Perkhidmatan Web dari WSDL

Terdapat beberapa cara untuk menghasilkan fail sumber perkhidmatan web dari dokumen WSDL.

Salah satu cara adalah dengan menggunakan alat wsimport yang merupakan sebahagian daripada JDK (pada $ JAVA_HOME / bin) hingga JDK 8.

Dari arahan arahan:

wsimport -s . -p com.baeldung.jaxws.server.topdown employeeservicetopdown.wsdl

Pilihan baris perintah yang digunakan: -p menentukan paket sasaran. -s menentukan tempat meletakkan fail sumber yang dihasilkan.

Untuk versi JDK yang kemudian, kami dapat menggunakan jaxws-maven-plugin oleh MojoHaus seperti yang dijelaskan di sini.

Sebagai alternatif, org.jvnet.jaxb2 's maven-jaxb2-plugin boleh datang berguna seperti yang diperincikan dalam Pembangkitan yang SOAP Web Perkhidmatan di Spring.

Fail yang dihasilkan:

  • EmployeeServiceTopDown.java - adalah antara muka endpoint perkhidmatan (SEI) yang mengandungi definisi kaedah
  • ObjectFactory.java - mengandungi kaedah kilang untuk membuat contoh kelas turunan skema secara program
  • EmployeeServiceTopDown_Service.java - adalah kelas penyedia perkhidmatan yang boleh digunakan oleh klien JAX-WS

5.2. Antaramuka Titik Akhir Perkhidmatan Web

Alat wsimport telah menghasilkan antara muka titik akhir perkhidmatan web EmployeeServiceTopDown . Ia menyatakan kaedah perkhidmatan web:

@WebService( name = "EmployeeServiceTopDown", targetNamespace = "//topdown.server.jaxws.baeldung.com/") @SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) @XmlSeeAlso({ ObjectFactory.class }) public interface EmployeeServiceTopDown { @WebMethod( action = "//topdown.server.jaxws.baeldung.com/" + "EmployeeServiceTopDown/countEmployees") @WebResult( name = "countEmployeesResponse", targetNamespace = "//topdown.server.jaxws.baeldung.com/", partName = "parameters") public int countEmployees(); }

5.3. Pelaksanaan Perkhidmatan Web

Alat wsimport telah membuat struktur perkhidmatan web. Kita harus membuat pelaksanaan perkhidmatan web:

@WebService( name = "EmployeeServiceTopDown", endpointInterface = "com.baeldung.jaxws.server.topdown.EmployeeServiceTopDown", targetNamespace = "//topdown.server.jaxws.baeldung.com/") public class EmployeeServiceTopDownImpl implements EmployeeServiceTopDown { @Inject private EmployeeRepository employeeRepositoryImpl; @WebMethod public int countEmployees() { return employeeRepositoryImpl.count(); } }

6. Pendekatan Bottom-Up (Kontrak-Terakhir)

Dalam pendekatan bawah-atas, kita harus membuat antara muka titik akhir dan kelas pelaksanaan. WSDL dihasilkan dari kelas semasa perkhidmatan web diterbitkan.

Let's create a web service that will perform simple CRUD operations on Employee data.

6.1. The Model Class

The Employee model class:

public class Employee { private int id; private String firstName; // standard getters and setters }

6.2. Web Service Endpoint Interface

The web service endpoint interface which declares the web service methods:

@WebService public interface EmployeeService { @WebMethod Employee getEmployee(int id); @WebMethod Employee updateEmployee(int id, String name); @WebMethod boolean deleteEmployee(int id); @WebMethod Employee addEmployee(int id, String name); // ... }

This interface defines an abstract contract for the web service. The annotations used:

  • @WebService denotes that it is a web service interface
  • @WebMethod is used to customize a web service operation
  • @WebResult is used to customize name of the XML element that represents the return value

6.3. Web Service Implementation

The implementation class of the web service endpoint interface:

@WebService(endpointInterface = "com.baeldung.jaxws.EmployeeService") public class EmployeeServiceImpl implements EmployeeService { @Inject private EmployeeRepository employeeRepositoryImpl; @WebMethod public Employee getEmployee(int id) { return employeeRepositoryImpl.getEmployee(id); } @WebMethod public Employee updateEmployee(int id, String name) { return employeeRepositoryImpl.updateEmployee(id, name); } @WebMethod public boolean deleteEmployee(int id) { return employeeRepositoryImpl.deleteEmployee(id); } @WebMethod public Employee addEmployee(int id, String name) { return employeeRepositoryImpl.addEmployee(id, name); } // ... }

7. Publishing the Web Service Endpoints

To publish the web services (top-down and bottom-up), we need to pass an address and an instance of the web service implementation to the publish() method of the javax.xml.ws.Endpoint class:

public class EmployeeServicePublisher { public static void main(String[] args) { Endpoint.publish( "//localhost:8080/employeeservicetopdown", new EmployeeServiceTopDownImpl()); Endpoint.publish("//localhost:8080/employeeservice", new EmployeeServiceImpl()); } }

We can now run EmployeeServicePublisher to start the web service. To make use of CDI features, the web services can be deployed as WAR file to application servers like WildFly or GlassFish.

8. Remote Web Service Client

Let's now create a JAX-WS client to connect to the EmployeeService web service remotely.

8.1. Generating Client Artifacts

To generate JAX-WS client artifacts, we can once again use the wsimport tool:

wsimport -keep -p com.baeldung.jaxws.client //localhost:8080/employeeservice?wsdl

Kelas EmployeeService_Service yang dihasilkan merangkumi logik untuk mendapatkan port pelayan menggunakan URL dan QName .

8.2. Menyambung ke Perkhidmatan Web

Pelanggan perkhidmatan web menggunakan EmployeeService_Service yang dihasilkan untuk menyambung ke pelayan dan membuat panggilan perkhidmatan web dari jauh:

public class EmployeeServiceClient { public static void main(String[] args) throws Exception { URL url = new URL("//localhost:8080/employeeservice?wsdl"); EmployeeService_Service employeeService_Service = new EmployeeService_Service(url); EmployeeService employeeServiceProxy = employeeService_Service.getEmployeeServiceImplPort(); List allEmployees = employeeServiceProxy.getAllEmployees(); } }

9. Kesimpulannya

Artikel ini adalah pengenalan pantas untuk perkhidmatan Web SOAP menggunakan JAX-WS .

Kami telah menggunakan pendekatan bawah-atas dan atas-bawah untuk membuat perkhidmatan Web SOAP menggunakan JAX-WS API. Kami juga telah menulis klien JAX-WS yang dapat menyambung ke pelayan dari jauh dan membuat panggilan perkhidmatan web.

Kod sumber lengkap boleh didapati di GitHub.