Einführung in JAX-WS

1. Übersicht

Die Java-API für XML-Webdienste (JAX-WS) ist eine standardisierte API zum Erstellen und Verwenden von SOAP-Webdiensten (Simple Object Access Protocol).

In diesem Artikel erstellen wir einen SOAP-Webdienst und stellen mit JAX-WS eine Verbindung zu ihm her.

2. Seife

SOAP ist eine XML-Spezifikation zum Senden von Nachrichten über ein Netzwerk. SOAP-Nachrichten sind unabhängig von jedem Betriebssystem und können eine Vielzahl von Kommunikationsprotokollen verwenden, einschließlich HTTP und SMTP.

SOAP ist XML-schwer und wird daher am besten mit Tools / Frameworks verwendet. JAX-WS ist ein Framework, das die Verwendung von SOAP vereinfacht. Es ist Teil von Standard-Java.

3. Top-Down vs. Bottom-Up

Es gibt zwei Möglichkeiten, SOAP-Webdienste zu erstellen. Wir können einen Top-Down-Ansatz oder einen Bottom-Up-Ansatz wählen.

Bei einem Top-Down-Ansatz (Contract-First) wird ein WSDL-Dokument erstellt und die erforderlichen Java-Klassen werden aus der WSDL generiert. Bei einem Bottom-up-Ansatz (Contract-Last) werden die Java-Klassen geschrieben und die WSDL aus den Java-Klassen generiert.

Das Schreiben einer WSDL-Datei kann je nach Komplexität Ihres Webdienstes recht schwierig sein. Dies macht den Bottom-up-Ansatz zu einer einfacheren Option. Da Ihre WSDL aus den Java-Klassen generiert wird, kann jede Änderung des Codes zu einer Änderung der WSDL führen. Dies ist beim Top-Down-Ansatz nicht der Fall.

In diesem Artikel werden wir uns beide Ansätze ansehen.

4. WSDL (Web Services Definition Language)

WSDL ist eine Vertragsdefinition der verfügbaren Dienste. Es ist eine Spezifikation von Eingabe- / Ausgabemeldungen und wie der Webdienst aufgerufen wird. Es ist sprachneutral und in XML definiert.

Schauen wir uns die Hauptelemente eines WSDL-Dokuments an.

4.1. Definitionen

Das Definitionselement ist das Stammelement aller WSDL-Dokumente. Es definiert den Namen, den Namespace usw. des Dienstes und kann, wie Sie sehen, recht geräumig sein:

 ... 

4.2. Typen

Die Typen Element definiert die Datentypen , die von dem Web - Dienst verwendet. WSDL verwendet XSD (XML Schema Definition) als Typsystem, das die Interoperabilität unterstützt:

 ...      ... 

4.3. Mitteilungen

Das Nachrichtenelement bietet eine abstrakte Definition der übertragenen Daten. Jedes Nachrichtenelement beschreibt die Eingabe oder Ausgabe einer Dienstmethode und die möglichen Ausnahmen:

 ...          ... 

4.4. Operationen und Porttypen

Das portType- Element beschreibt jede ausführbare Operation und alle beteiligten Nachrichtenelemente . Zum Beispiel kann das getEmployee legt Betrieb die Anforderung Eingang , Ausgang und mögliche Fehler Ausnahme vom Webdienst geworfen Betrieb :

 ...       ....  ...  

4.5. Bindungen

Das Bindungselement enthält Protokoll- und Datenformatdetails für jeden Porttyp :

 ...               ...  ... 

4.6. Dienste und Häfen

Das Serviceelement definiert die vom Webdienst unterstützten Ports. Das Port Element in Dienst definiert den Namen , die Bindung und die Adresse des Dienstes:

 ...      ... 

5. Top-Down-Ansatz (Vertrag zuerst)

Beginnen wir mit einem Top-Down-Ansatz, indem wir eine WSDL-Datei employeeervicetopdown.wsdl erstellen . Der Einfachheit halber gibt es nur eine Methode:

5.1. Generieren von Webdienst-Quelldateien aus WSDL

Es gibt verschiedene Möglichkeiten, Webdienst-Quelldateien aus einem WSDL-Dokument zu generieren.

Eine Möglichkeit besteht darin, das wsimport- Tool zu verwenden, das Teil von JDK ist (unter $ JAVA_HOME / bin), bis JDK 8.

An der Eingabeaufforderung:

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

Verwendete Befehlszeilenoptionen: -p gibt das Zielpaket an. -s gibt an, wo die generierten Quelldateien abgelegt werden sollen.

Für spätere JDK-Versionen können wir das hier beschriebene jaxws-maven-plugin von MojoHaus verwenden.

Alternativ kann das maven-jaxb2-Plugin von org.jvnet.jaxb2 nützlich sein, wie unter Aufrufen eines SOAP-Webdienstes im Frühjahr beschrieben.

Die generierten Dateien:

  • EmployeeServiceTopDown.java - ist die Service Endpoint Interface (SEI), die Methodendefinitionen enthält
  • ObjectFactory.java - enthält Factory-Methoden zum programmgesteuerten Erstellen von Instanzen von vom Schema abgeleiteten Klassen
  • EmployeeServiceTopDown_Service.java - ist die Dienstanbieterklasse, die von einem JAX-WS-Client verwendet werden kann

5.2. Webdienst-Endpunktschnittstelle

Das Tool wsimport hat die Webdienst-Endpunktschnittstelle EmployeeServiceTopDown generiert . Es deklariert die Webdienstmethoden:

@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. Implementierung des Webdienstes

Das Tool wsimport hat die Struktur des Webdienstes erstellt. Wir müssen die Implementierung des Webdienstes erstellen:

@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. Bottom-Up-Ansatz (Vertrags-letzter Ansatz)

In einem Bottom-up-Ansatz müssen wir sowohl die Endpunktschnittstelle als auch die Implementierungsklassen erstellen. Die WSDL wird aus den Klassen generiert, wenn der Webdienst veröffentlicht wird.

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

Die generierte EmployeeService_Service- Klasse kapselt die Logik zum Abrufen des Serverports mithilfe von URL und QName .

8.2. Herstellen einer Verbindung zum Webdienst

Der Webdienstclient verwendet den generierten EmployeeService_Service , um eine Verbindung zum Server herzustellen und Webdienstaufrufe remote durchzuführen:

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. Fazit

Dieser Artikel ist eine kurze Einführung in SOAP-Webdienste mit JAX-WS .

Wir haben sowohl Bottom-up- als auch Top-down-Ansätze zum Erstellen von SOAP-Webdiensten mithilfe der JAX-WS-API verwendet. Wir haben auch einen JAX-WS-Client geschrieben, der eine Remoteverbindung zum Server herstellen und Webdienstaufrufe tätigen kann.

Der vollständige Quellcode ist auf GitHub verfügbar.