Introduktion til JAX-WS

1. Oversigt

Java API til XML Web Services (JAX-WS) er en standardiseret API til oprettelse og forbrug af SOAP-webtjenester (Simple Object Access Protocol).

I denne artikel opretter vi en SOAP-webservice og opretter forbindelse til den ved hjælp af JAX-WS.

2. SÆBE

SOAP er en XML-specifikation til afsendelse af meddelelser over et netværk. SOAP-meddelelser er uafhængige af ethvert operativsystem og kan bruge en række kommunikationsprotokoller, herunder HTTP og SMTP.

SOAP er XML tung, og derfor bedst brugt med værktøjer / rammer. JAX-WS er ​​en ramme, der forenkler brugen af ​​SOAP. Det er en del af standard Java.

3. Top-Down vs. Bottom-Up

Der er to måder at opbygge SOAP-webtjenester på. Vi kan gå med en top-down-tilgang eller en bottom-up-tilgang.

I en top-down (kontrakt-første) tilgang oprettes et WSDL-dokument, og de nødvendige Java-klasser genereres fra WSDL. I en bottom-up (kontrakt-sidste) tilgang skrives Java-klasser, og WSDL genereres fra Java-klasser.

Skrivning af en WSDL-fil kan være ret vanskelig, afhængigt af hvor kompleks din webservice er. Dette gør bottom-up tilgang til en lettere mulighed. På den anden side, da din WSDL genereres fra Java-klasser, kan enhver ændring i kode medføre en ændring i WSDL. Dette er ikke tilfældet med top-down-tilgangen.

I denne artikel ser vi på begge tilgange.

4. Definitionssprog til webservices (WSDL)

WSDL er en kontraktdefinition af de tilgængelige tjenester. Det er en specifikation af input / output-beskeder, og hvordan man påberåber sig webservicen. Det er sprogneutralt og er defineret i XML.

Lad os se på de vigtigste elementer i et WSDL-dokument.

4.1. Definitioner

Det definitioner element er rodelementet i alle WSDL-dokumenter. Det definerer tjenestens navn, navneområde osv., Og som du kan se, kan det være ret rummeligt:

 ... 

4.2. Typer

Det typer element definerer de datatyper, der bruges af webservicen. WSDL bruger XSD (XML Schema Definition) som det typesystem, der hjælper med interoperabilitet:

 ...      ... 

4.3. Beskeder

Det besked element giver en abstrakt definition af de data, der transmitteres. Hver besked element beskriver input eller output af en servicemetode og de mulige undtagelser:

 ...          ... 

4.4. Operationer og havnetyper

Det portType element beskriver hver operation der kan udføres og alt det besked involverede elementer. F.eks getMedarbejder operation specificerer anmodningen input, produktion og mulig fejl undtagelse kastet af webservicen operation:

 ...       ....  ...  

4.5. Bindinger

Det bindende element giver protokol- og dataformatoplysninger for hver portType:

 ...               ...  ... 

4.6. Tjenester og porte

Det service element definerer de porte, der understøttes af webservicen. Det Havn element i service definerer navn, bindende og adresse af tjenesten:

 ...      ... 

5. Top-down (kontrakt-første) tilgang

Lad os starte med en top-down tilgang ved at oprette en WSDL-fil medarbejdereservicetopdown.wsdl. For enkelheds skyld har den kun en metode:

5.1. Genererer Webtjeneste kildefiler fra WSDL

Der er flere måder at generere webservicekildefiler fra et WSDL-dokument.

En måde er at bruge wsimport værktøj, der er en del af JDK (på $ JAVA_HOME / bin) indtil JDK 8.

Fra kommandoprompten:

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

Brugte kommandolinjemuligheder: -p angiver målpakken. -s angiver, hvor de genererede kildefiler skal placeres.

Til senere JDK-versioner kan vi bruge jaxws-maven-plugin af MojoHaus som beskrevet her.

Alternativt org.jvnet.jaxb2'S maven-jaxb2-plugin kan være nyttigt som beskrevet i Påkald af en SOAP-webservice om foråret.

De genererede filer:

  • EmployeeServiceTopDown.java - er serviceendepunktsgrænsefladen (SEI), der indeholder metodedefinitioner
  • ObjectFactory.java - indeholder fabriksmetoder til at oprette forekomster af skemaafledte klasser programmatisk
  • EmployeeServiceTopDown_Service.java - er den tjenesteudbyderklasse, der kan bruges af en JAX-WS-klient

5.2. Web Service Endpoint Interface

Det wsimport værktøjet har genereret webtjenestens slutpunktsgrænseflade EmployeeServiceTopDown. Det erklærer webservicemetoderne:

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

5.3. Implementering af webservice

Det wsimport værktøj har skabt strukturen i webservicen. Vi er nødt til at oprette implementeringen af ​​webservicen:

@WebService (name = "EmployeeServiceTopDown", endpointInterface = "com.baeldung.jaxws.server.topdown.EmployeeServiceTopDown", targetNamespace = "//topdown.server.jaxws.baeldung.com/") offentlig klasse EmployeeServiceTopDownImpl implementerer EmployeeService private EmployeeRepository medarbejderRepositoryImpl; @WebMethod offentlig int countEmployees () {return medarbejderRepositoryImpl.count (); }}

6. Bottom-Up (Contract-Last) tilgang

I en bottom-up-tilgang er vi nødt til at oprette både slutpunktsgrænsefladen og implementeringsklasser. WSDL genereres fra klasser, når webservicen offentliggøres.

Lad os oprette en webservice, der udfører enkle CRUD-operationer Medarbejder data.

6.1. Modelklassen

Det Medarbejder model klasse:

offentlig klassemedarbejder {privat int id; privat streng fornavn; // standard getters og setter}

6.2. Web Service Endpoint Interface

Webtjenestens slutpunktsgrænseflade, der erklærer webservicemetoderne:

@WebService offentlig grænseflade EmployeeService {@WebMethod Medarbejder getEmployee (int id); @WebMethod MedarbejderopdateringMedarbejder (int id, strengnavn); @WebMethod boolsk deleteEmployee (int id); @WebMethod Medarbejder addEmployee (int id, strengnavn); // ...}

Denne grænseflade definerer en abstrakt kontrakt for webservicen. Anvendte annoteringer:

  • @WebService angiver, at det er en webtjenestegrænseflade
  • @WebMethod bruges til at tilpasse en webservicefunktion
  • @WebResult bruges til at tilpasse navnet på det XML-element, der repræsenterer returværdien

6.3. Implementering af webservice

Implementeringsklassen for webtjenestens slutpunktsgrænseflade:

@WebService (endpointInterface = "com.baeldung.jaxws.EmployeeService") offentlig klasse EmployeeServiceImpl implementerer EmployeeService {@Inject private EmployeeRepository workerRepositoryImpl; @WebMethod offentlig medarbejder getEmployee (int id) {return medarbejderRepositoryImpl.getEmployee (id); } @WebMethod offentlig medarbejderopdateringMedarbejder (int id, strengnavn) {returner medarbejderRepositoryImpl.updateEmployee (id, navn); } @WebMethod offentlig boolsk deleteEmployee (int id) {return medarbejderRepositoryImpl.deleteEmployee (id); } @WebMethod offentlig ansat addEmployee (int id, strengnavn) {returner medarbejderRepositoryImpl.addEmployee (id, navn); } // ...}

7. Udgivelse af webservicens slutpunkter

For at udgive webtjenesterne (top-down og bottom-up) er vi nødt til at videregive en adresse og en forekomst af implementeringen af ​​webservicen til offentliggøre() metode til javax.xml.ws.Endpoint klasse:

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

Vi kan nu løbe EmployeeServicePublisher for at starte webservicen. For at gøre brug af CDI-funktioner kan webtjenesterne distribueres som WAR-fil til applikationsservere som WildFly eller GlassFish.

8. Remote Web Service Client

Lad os nu oprette en JAX-WS-klient til at oprette forbindelse til Medarbejderstjeneste fjernbetjening af webservice.

8.1. Generering af klientartefakter

For at generere JAX-WS-klientartefakter kan vi igen bruge wsimport værktøj:

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

Den genererede EmployeeService_Service klasse indkapsler logikken for at få serverporten til at bruge URL og QName.

8.2. Opretter forbindelse til webservicen

Webserviceklienten bruger det genererede EmployeeService_Service at oprette forbindelse til serveren og foretage eksternt opkald til webservices:

offentlig klasse EmployeeServiceClient {public static void main (String [] args) throw Exception {URL url = new URL ("// localhost: 8080 / workerservice? wsdl"); EmployeeService_Service employeeService_Service = ny EmployeeService_Service (url); EmployeeService medarbejderServiceProxy = medarbejderService_Service.getEmployeeServiceImplPort (); Vis allEmployees = medarbejderServiceProxy.getAllEmployees (); }}

9. Konklusion

Denne artikel er en hurtig introduktion til SOAP-webtjenester ved hjælp af JAX-WS.

Vi har brugt både bottom-up og top-down tilgange til oprettelse af SOAP-webtjenester ved hjælp af JAX-WS API. Vi har også skrevet en JAX-WS-klient, der kan oprette forbindelse til serveren eksternt og foretage webservicekald.

Den komplette kildekode er tilgængelig på GitHub.