Въведение в JAX-WS

Програмиране

1. Общ преглед

Java API за XML уеб услуги (JAX-WS) е стандартизиран API за създаване и консумиране на SOAP (Simple Object Access Protocol) уеб услуги.

В тази статия ще създадем SOAP уеб услуга и ще се свържем с нея с помощта на JAX-WS.

2. САПУН

SOAP е XML спецификация за изпращане на съобщения през мрежа. SOAP съобщенията са независими от всяка операционна система и могат да използват различни комуникационни протоколи, включително HTTP и SMTP.

SOAP е XML тежък, следователно най-добре се използва с инструменти / рамки. JAX-WS е рамка, която опростява използването на SOAP. Той е част от стандартната Java.

3. Отгоре-надолу срещу отдолу-нагоре

Има два начина за изграждане на SOAP уеб услуги. Можем да използваме подход отгоре надолу или подход отдолу нагоре.

При подхода отгоре надолу (с договор първо) се създава WSDL документ и от WSDL се генерират необходимите Java класове. При подход отдолу нагоре (последен договор), Java класовете се записват и WSDL се генерира от Java класовете.

Написването на WSDL файл може да бъде доста трудно в зависимост от това колко сложна е вашата уеб услуга. Това прави подхода отдолу нагоре по-лесен вариант. От друга страна, тъй като вашият WSDL се генерира от класовете Java, всяка промяна в кода може да причини промяна в WSDL. Това не важи за подхода отгоре надолу.

В тази статия ще разгледаме и двата подхода.

4. Език за дефиниция на уеб услуги (WSDL)

WSDL е договорна дефиниция на наличните услуги. Това е спецификация на входно / изходни съобщения и как да се извика уеб услугата. Той е езиково неутрален и е дефиниран в XML.

Нека разгледаме основните елементи на WSDL документ.

4.1. Дефиниции

Елементът на дефинициите е основният елемент на всички WSDL документи. Той определя името, пространството от имена и т.н. на услугата и, както виждате, може да бъде доста просторен:

 ...

4.2. Видове

Елементът типове дефинира типовете данни, използвани от уеб услугата. WSDL използва XSD (XML Schema Definition) като типова система, която помага за оперативната съвместимост:

 ...      ...

4.3. Съобщения

Елементът съобщение предоставя абстрактна дефиниция на предаваните данни. Всеки елемент на съобщението описва входа или изхода на метод на услугата и възможните изключения:

 ...          ...

4.4. Операции и типове пристанища

Елементът portType описва всяка операция, която може да бъде изпълнена, и всички включени елементи на съобщението . Например, getEmployee операцията определя искане входа , изхода и е възможно вина изключение хвърлен от уеб услуга операцията :

 ...       ....  ...

4.5. Обвързвания

В задължителен елемент осигурява протоколни и формат на данните подробности за всяка portType :

 ...               ...  ...

4.6. Услуги и пристанища

Елементът на услугата определя портовете, поддържани от уеб услугата. Елементът порт в услугата определя името , обвързването и адреса на услугата:

 ...      ...

5. Подход отгоре надолу (договор първо)

Нека започнем с подход отгоре надолу, като създадем WSDL файл workerservicetopdown.wsdl . За по-голяма простота той има само един метод:

5.1. Генериране на файлове с изходни уеб услуги от WSDL

Има няколко начина за генериране на изходни файлове на уеб услуги от WSDL документ.

Един от начините е да използвате инструмента wsimport , който е част от JDK (при $ JAVA_HOME / bin) до JDK 8.

От командния ред:

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

Използвани опции на командния ред: -p указва целевия пакет. -s указва къде да се поставят генерираните изходни файлове.

За по-късните версии на JDK можем да използваме jaxws-maven-plugin от MojoHaus, както е описано тук.

Алтернативно, org.jvnet.jaxb2 е Maven-jaxb2-плъгин може да дойде по-удобно, както е описано в Позовавайки се на SOAP Web Service през пролетта.

Генерираните файлове:

  • EmployeeServiceTopDown.java - е интерфейсът за крайна точка на услугата (SEI), който съдържа дефиниции на методи
  • ObjectFactory.java - съдържа фабрични методи за програмно създаване на екземпляри от извлечени от схемата класове
  • EmployeeServiceTopDown_Service.java - е клас на доставчик на услуги, който може да се използва от JAX-WS клиент

5.2. Интерфейс на крайната точка на уеб услугата

Инструментът wsimport е генерирал интерфейс за крайна точка на уеб услугата EmployeeServiceTopDown . Той декларира методите на уеб услугата:

@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. Внедряване на уеб услуга

Инструментът wsimport е създал структурата на уеб услугата. Трябва да създадем внедряването на уеб услугата:

@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. Подход отдолу нагоре (последен договор)

При подход отдолу-нагоре трябва да създадем както интерфейса на крайната точка, така и класовете за внедряване. WSDL се генерира от класовете, когато се публикува уеб услугата.

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

Генерираният клас EmployeeService_Service капсулира логиката за получаване на порта на сървъра, използвайки URL и QName .

8.2. Свързване с уеб услугата

Клиентът на уеб услугата използва генерирания EmployeeService_Service, за да се свърже със сървъра и да осъществява дистанционни обаждания към уеб услуги:

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. Заключение

Тази статия е кратко въведение в SOAP уеб услугите, използващи JAX-WS .

Използвали сме както подходи отдолу нагоре, така и отгоре надолу за създаване на SOAP уеб услуги, използвайки JAX-WS API. Също така написахме клиент на JAX-WS, който може да се свързва дистанционно със сървъра и да осъществява повиквания за уеб услуги.

Пълният изходен код е достъпен в GitHub.