Inleiding tot JAX-WS

1. Overzicht

Java API voor XML Web Services (JAX-WS) is een gestandaardiseerde API voor het maken en gebruiken van SOAP-webservices (Simple Object Access Protocol).

In dit artikel maken we een SOAP-webservice en maken we er verbinding mee via JAX-WS.

2. ZEEP

SOAP is een XML-specificatie voor het verzenden van berichten via een netwerk. SOAP-berichten zijn onafhankelijk van elk besturingssysteem en kunnen verschillende communicatieprotocollen gebruiken, waaronder HTTP en SMTP.

SOAP is XML-zwaar en kan daarom het beste worden gebruikt met tools / frameworks. JAX-WS is een framework dat het gebruik van SOAP vereenvoudigt. Het maakt deel uit van standaard Java.

3. Top-down versus bottom-up

Er zijn twee manieren om SOAP-webservices te bouwen. We kunnen kiezen voor een top-down benadering of een bottom-up benadering.

Bij een top-down (contract-first) benadering wordt een WSDL-document gemaakt en worden de benodigde Java-klassen gegenereerd op basis van de WSDL. In een bottom-up (contract-last) benadering worden de Java-klassen geschreven en wordt de WSDL gegenereerd vanuit de Java-klassen.

Het schrijven van een WSDL-bestand kan behoorlijk moeilijk zijn, afhankelijk van hoe complex uw webservice is. Dit maakt de bottom-up benadering een gemakkelijkere optie. Aan de andere kant, aangezien uw WSDL wordt gegenereerd vanuit de Java-klassen, kan elke wijziging in de code een wijziging in de WSDL veroorzaken. Dit is niet het geval bij de top-down benadering.

In dit artikel zullen we beide benaderingen bekijken.

4. Web Services Definition Language (WSDL)

WSDL is een contractdefinitie van de beschikbare services. Het is een specificatie van invoer- / uitvoerberichten en hoe de webservice moet worden aangeroepen. Het is taalneutraal en wordt gedefinieerd in XML.

Laten we eens kijken naar de belangrijkste elementen van een WSDL-document.

4.1. Definities

De definities element is het root-element van alle WSDL-documenten. Het definieert de naam, de naamruimte, enz. Van de service en kan, zoals u kunt zien, behoorlijk ruim zijn:

 ... 

4.2. Types

De types element definieert de gegevenstypen die door de webservice worden gebruikt. WSDL gebruikt XSD (XML Schema Definition) als het typesysteem dat helpt bij interoperabiliteit:

 ...      ... 

4.3. Berichten

De bericht element biedt een abstracte definitie van de gegevens die worden verzonden. Elk bericht element beschrijft de invoer of uitvoer van een servicemethode en de mogelijke uitzonderingen:

 ...          ... 

4.4. Operaties en poorttypen

De portType element beschrijft elk operatie dat kan worden uitgevoerd en alle bericht betrokken elementen. Bijvoorbeeld de getEmployee operatie specificeert het verzoek invoer, output en mogelijk fout uitzondering veroorzaakt door de webservice operatie:

 ...       ....  ...  

4.5. Bindingen

De verbindend element biedt protocol- en gegevensindelingsdetails voor elk portType:

 ...               ...  ... 

4.6. Services en poorten

De onderhoud element definieert de poorten die worden ondersteund door de webservice. De haven element in onderhoud definieert de naam, verbindend en de adres van de dienst:

 ...      ... 

5. Top-down (contract-eerst) benadering

Laten we beginnen met een top-down benadering door een WSDL-bestand te maken medewerkersservicetopdown.wsdl. Eenvoudigheidshalve heeft het maar één methode:

5.1. Genereren Webservicebronbestanden van WSDL

Er zijn verschillende manieren om bronbestanden voor webservices te genereren vanuit een WSDL-document.

Een manier is om de wsimport tool die deel uitmaakt van JDK (op $ JAVA_HOME / bin) tot JDK 8.

Vanaf de opdrachtprompt:

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

Gebruikte opdrachtregelopties: -p specificeert het doelpakket. -s specificeert waar de gegenereerde bronbestanden moeten worden geplaatst.

Voor latere JDK-versies kunnen we jaxws-maven-plugin door MojoHaus zoals hier beschreven.

Alternatief, org.jvnet.jaxb2‘S maven-jaxb2-plugin kan van pas komen, zoals beschreven in Een SOAP-webservice aanroepen in het voorjaar.

De gegenereerde bestanden:

  • EmployeeServiceTopDown.java - is de service-eindpuntinterface (SEI) die methodedefinities bevat
  • ObjectFactory.java - bevat fabrieksmethoden om programmatisch instanties van aan schema's afgeleide klassen te maken
  • EmployeeServiceTopDown_Service.java - is de serviceproviderklasse die kan worden gebruikt door een JAX-WS-client

5.2. Webservice-eindpuntinterface

De wsimport tool heeft de webservice-eindpuntinterface gegenereerd EmployeeServiceTopDown. Het verklaart de webservicemethoden:

@WebService (name = "EmployeeServiceTopDown", targetNamespace = "//topdown.server.jaxws.baeldung.com/") @SOAPBinding (parameterStyle = SOAPBinding.ParameterStyle.BARE) @XmlSeeAlso ({ObjectFactory.class}) openbare 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. Implementatie van webservices

De wsimport tool heeft de structuur van de webservice gemaakt. We moeten de implementatie van de webservice maken:

@WebService (name = "EmployeeServiceTopDown", endpointInterface = "com.baeldung.jaxws.server.topdown.EmployeeServiceTopDown", targetNamespace = "//topdown.server.jaxws.baeldung.com/") openbare klasse EmployeeServiceTopDownImpl implementeert EmployeeServiceTopDown {@Inject privé EmployeeRepository employeeRepositoryImpl; @WebMethod openbare int countEmployees () {terugkeer employeeRepositoryImpl.count (); }}

6. Bottom-Up (Contract-Last) benadering

Bij een bottom-up benadering moeten we zowel de eindpuntinterface als de implementatieklassen creëren. De WSDL wordt gegenereerd op basis van de klassen wanneer de webservice wordt gepubliceerd.

Laten we een webservice maken die eenvoudige CRUD-bewerkingen kan uitvoeren op Werknemer gegevens.

6.1. De modelklasse

De Werknemer model klasse:

openbare klasse Medewerker {privé int id; private String voornaam; // standaard getters en setters}

6.2. Webservice-eindpuntinterface

De webservice-eindpuntinterface die de webservicemethoden declareert:

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

Deze interface definieert een abstract contract voor de webservice. De gebruikte annotaties:

  • @WebService geeft aan dat het een webservice-interface is
  • @WebMethod wordt gebruikt om een ​​webservicebewerking aan te passen
  • @WebResult wordt gebruikt om de naam aan te passen van het XML-element dat de geretourneerde waarde vertegenwoordigt

6.3. Implementatie van webservices

De implementatieklasse van de webservice-eindpuntinterface:

@WebService (endpointInterface = "com.baeldung.jaxws.EmployeeService") openbare klasse EmployeeServiceImpl implementeert EmployeeService {@Inject private EmployeeRepository employeeRepositoryImpl; @WebMethod openbare Werknemer getEmployee (int id) {terugkeer employeeRepositoryImpl.getEmployee (id); } @WebMethod openbare Werknemer updateEmployee (int id, String naam) {return employeeRepositoryImpl.updateEmployee (id, naam); } @WebMethod openbare boolean deleteEmployee (int id) {return employeeRepositoryImpl.deleteEmployee (id); } @WebMethod openbare Werknemer addEmployee (int id, String naam) {return employeeRepositoryImpl.addEmployee (id, naam); } // ...}

7. Publiceren van de webservice-eindpunten

Om de webservices (top-down en bottom-up) te publiceren, moeten we een adres en een instantie van de webservice-implementatie doorgeven aan de publiceren() methode van de javax.xml.ws.Endpoint klasse:

openbare klasse EmployeeServicePublisher {public static void main (String [] args) {Endpoint.publish ("// localhost: 8080 / workerservicetopdown", nieuwe EmployeeServiceTopDownImpl ()); Endpoint.publish ("// localhost: 8080 / workerservice", nieuwe EmployeeServiceImpl ()); }}

We kunnen nu rennen MedewerkerServicePublisher om de webservice te starten. Om gebruik te maken van CDI-functies, kunnen de webservices als WAR-bestand worden ingezet op applicatieservers zoals WildFly of GlassFish.

8. Externe webserviceclient

Laten we nu een JAX-WS-client maken om verbinding te maken met het Medewerker Service webservice op afstand.

8.1. Clientartefacten genereren

Om JAX-WS-clientartefacten te genereren, kunnen we opnieuw de wsimport hulpmiddel:

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

Het gegenereerde EmployeeService_Service class kapselt de logica in om de serverpoort te gebruiken met URL en QName.

8.2. Verbinding maken met de webservice

De webserviceclient gebruikt het gegenereerde EmployeeService_Service om verbinding te maken met de server en op afstand webservicegesprekken te voeren:

public class EmployeeServiceClient {public static void main (String [] args) genereert Uitzondering {URL url = nieuwe URL ("// localhost: 8080 / workerservice? wsdl"); EmployeeService_Service employeeService_Service = nieuwe EmployeeService_Service (url); EmployeeService employeeServiceProxy = employeeService_Service.getEmployeeServiceImplPort (); Lijst allEmployees = employeeServiceProxy.getAllEmployees (); }}

9. Conclusie

Dit artikel is een korte inleiding tot SOAP-webservices met JAX-WS.

We hebben zowel de bottom-up als de top-down benadering gebruikt om SOAP-webservices te maken met behulp van de JAX-WS API. We hebben ook een JAX-WS-client geschreven die op afstand verbinding kan maken met de server en webservice-oproepen kan plaatsen.

De volledige broncode is beschikbaar op GitHub.