Introduksjon til JAX-WS
1. Oversikt
Java API for XML Web Services (JAX-WS) er et standardisert API for å lage og konsumere SOAP (Simple Object Access Protocol) webtjenester.
I denne artikkelen oppretter vi en SOAP-nettjeneste og kobler til den ved hjelp av JAX-WS.
2. SÅPE
SOAP er en XML-spesifikasjon for sending av meldinger over et nettverk. SOAP-meldinger er uavhengige av ethvert operativsystem og kan bruke en rekke kommunikasjonsprotokoller, inkludert HTTP og SMTP.
SOAP er XML tung, derav best brukt med verktøy / rammer. JAX-WS er et rammeverk som forenkler bruk av SOAP. Det er en del av standard Java.
3. Top-Down vs. Bottom-Up
Det er to måter å bygge SOAP-nettjenester på. Vi kan gå med en ovenfra og ned tilnærming.
I en top-down (kontrakt-først) tilnærming blir et WSDL-dokument opprettet, og de nødvendige Java-klassene genereres fra WSDL. I en bottom-up (kontrakt-siste) tilnærming blir Java-klassene skrevet, og WSDL genereres fra Java-klassene.
Å skrive en WSDL-fil kan være ganske vanskelig, avhengig av hvor kompleks nettjenesten din er. Dette gjør bottom-up-tilnærmingen til et enklere alternativ. På den annen side, siden WSDL er generert fra Java-klassene, kan enhver endring i kode føre til en endring i WSDL. Dette er ikke tilfelle for top-down-tilnærmingen.
I denne artikkelen vil vi se på begge tilnærminger.
4. Definisjonsspråk for webtjenester (WSDL)
WSDL er en kontraktdefinisjon av tilgjengelige tjenester. Det er en spesifikasjon av inngangs- / utgangsmeldinger, og hvordan man påkaller nettjenesten. Det er språknøytralt og er definert i XML.
La oss se på hovedelementene i et WSDL-dokument.
4.1. Definisjoner
De definisjoner elementet er rotelementet til alle WSDL-dokumenter. Den definerer navnet, navneområdet osv. På tjenesten, og som du kan se, kan det være ganske romslig:
... 4.2. Typer
De typer element definerer datatypene som brukes av nettjenesten. WSDL bruker XSD (XML Schema Definition) som typesystem som hjelper med interoperabilitet:
... ... 4.3. Meldinger
De beskjed element gir en abstrakt definisjon av dataene som overføres. Hver beskjed element beskriver inngangen eller utgangen av en tjenestemetode og mulige unntak:
... ... 4.4. Operasjoner og porttyper
De portType element beskriver hver operasjon som kan utføres og alt beskjed elementer involvert. For eksempel få medarbeider operasjonen spesifiserer forespørselen inngang, produksjon og mulig feil unntak kastet av nettjenesten operasjon:
... .... ... 4.5. Bindinger
De bindende elementet gir detaljer om protokoll og dataformat for hver portType:
... ... ... 4.6. Tjenester og porter
De service element definerer portene som støttes av nettjenesten. De havn element i service definerer Navn, bindende og adresse av tjenesten:
... ... 5. Top-Down (Contract-First) tilnærming
La oss starte med en top-down-tilnærming ved å lage en WSDL-fil ansatteervicetopdown.wsdl. For enkelhets skyld har den bare en metode:
5.1. Genererer Web Service Source Files fra WSDL
Det er flere måter å generere kildefiler til webtjenester fra et WSDL-dokument.
En måte er å bruke wsimport verktøy som er en del av JDK (på $ JAVA_HOME / bin) til JDK 8.
Fra ledeteksten:
wsimport -s. -p com.baeldung.jaxws.server.topdown ansatteervicetopdown.wsdlKommandolinjealternativer brukt: -p spesifiserer målpakken. -s angir hvor de genererte kildefilene skal plasseres.
For senere JDK-versjoner kan vi bruke jaxws-maven-plugin av MojoHaus som beskrevet her.
Alternativt org.jvnet.jaxb2‘S maven-jaxb2-plugin kan være nyttig som beskrevet i Påkalle en SOAP-nettjeneste om våren.
De genererte filene:
- EmployeeServiceTopDown.java - er service endpoint interface (SEI) som inneholder metodedefinisjoner
- ObjectFactory.java - inneholder fabrikkmetoder for å lage forekomster av skjemaavledede klasser programmatisk
- EmployeeServiceTopDown_Service.java - er tjenesteleverandørklassen som kan brukes av en JAX-WS-klient
5.2. Web Service Endpoint Interface
De wsimport verktøyet har generert grensesnittet for sluttjeneste for webtjenester EmployeeServiceTopDown. Det erklærer nettjenestemetodene:
@WebService (name = "EmployeeServiceTopDown", targetNamespace = "//topdown.server.jaxws.baeldung.com/") @SOAPBinding (parameterStyle = SOAPBinding.ParameterStyle.BARE) @XmlSeeAlso ({ObjectFactory.class}) offentlig grensesnitt EmployeeServiceTopD @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. Implementering av webtjenester
De wsimport verktøyet har skapt strukturen til nettjenesten. Vi må lage implementeringen av nettjenesten:
@WebService (name = "EmployeeServiceTopDown", endpointInterface = "com.baeldung.jaxws.server.topdown.EmployeeServiceTopDown", targetNamespace = "//topdown.server.jaxws.baeldung.com/") offentlig klasse EmployeeServiceTopDownImplop implementerer EmployeeService private EmployeeRepository ansatteRepositoryImpl; @WebMethod public int countEmployees () {return employeeRepositoryImpl.count (); }}6. Bottom-Up (Contract-Last) Approach
I en bottom-up-tilnærming må vi lage både endepunktsgrensesnittet og implementeringsklassene. WSDL genereres fra klassene når nettjenesten publiseres.
La oss lage en webtjeneste som vil utføre enkle CRUD-operasjoner på Ansatt data.
6.1. Modellklassen
De Ansatt modellklasse:
offentlig klasse ansatt {privat int id; privat streng fornavn; // standard getters og setters}6.2. Web Service Endpoint Interface
Grensesnittet for nettjenestens sluttpunkt som deklarerer nettjenestemetodene:
@WebService offentlig grensesnitt EmployeeService {@WebMethod Employee getEmployee (int id); @WebMethod MedarbeideroppdateringMedarbeider (int id, strengnavn); @WebMethod boolsk deleteEmployee (int id); @WebMethod Ansatt addEmployee (int id, strengnavn); // ...}Dette grensesnittet definerer en abstrakt kontrakt for webtjenesten. Kommentarene som ble brukt:
- @Nettjeneste angir at det er et nettjenestegrensesnitt
- @WebMethod brukes til å tilpasse en webtjenesteoperasjon
- @WebResult brukes til å tilpasse navnet på XML-elementet som representerer returverdien
6.3. Implementering av webtjenester
Implementeringsklassen til nettpunktsgrensesnittet:
@WebService (endpointInterface = "com.baeldung.jaxws.EmployeeService") offentlig klasse EmployeeServiceImpl implementerer EmployeeService {@Inject private EmployeeRepository employeeRepositoryImpl; @WebMethod offentlig ansatt getEmployee (int id) {return employeeRepositoryImpl.getEmployee (id); } @WebMethod offentlig MedarbeideroppdateringMedarbeider (int id, String name) {return employeeRepositoryImpl.updateEmployee (id, name); } @WebMethod offentlig boolsk deleteEmployee (int id) {return employeeRepositoryImpl.deleteEmployee (id); } @WebMethod offentlig ansatt addEmployee (int id, strengnavn) {return workerRepositoryImpl.addEmployee (id, name); } // ...}7. Publisering av nettjenestens sluttpunkter
For å publisere webtjenestene (ovenfra og ned og opp) må vi sende en adresse og en forekomst av implementeringen av nettjenesten til publisere() metoden for javax.xml.ws.Endpoint klasse:
offentlig klasse EmployeeServicePublisher {public static void main (String [] args) {Endpoint.publish ("// localhost: 8080 / workerservicetopdown", new EmployeeServiceTopDownImpl ()); Endpoint.publish ("// localhost: 8080 / workerservice", ny EmployeeServiceImpl ()); }}Vi kan nå løpe EmployeeServicePublisher for å starte nettjenesten. For å gjøre bruk av CDI-funksjoner, kan webtjenestene distribueres som WAR-fil til applikasjonsservere som WildFly eller GlassFish.
8. Ekstern webtjenesteklient
La oss nå opprette en JAX-WS-klient for å koble til EmployeeService nettjeneste eksternt.
8.1. Genererer klientgjenstander
For å generere JAX-WS klientgjenstander, kan vi igjen bruke wsimport verktøy:
wsimport -keep -p com.baeldung.jaxws.client // localhost: 8080 / medarbeiderservice? wsdlDen genererte EmployeeService_Service klasse innkapsler logikken for å få serverporten til å bruke URL og QName.
8.2. Koble til nettjenesten
Webtjenesteklienten bruker det genererte EmployeeService_Service for å koble til serveren og ringe nettjenestetjenester eksternt:
offentlig klasse EmployeeServiceClient {public static void main (String [] args) kaster Unntak {URL url = ny URL ("// localhost: 8080 / ansatte service? wsdl"); EmployeeService_Service employeeService_Service = ny EmployeeService_Service (url); EmployeeService employeeServiceProxy = medarbeiderService_Service.getEmployeeServiceImplPort (); Liste allAnsatte = ansatteServiceProxy.getAllEmployees (); }}9. Konklusjon
Denne artikkelen er en rask introduksjon til SOAP Web-tjenester ved bruk av JAX-WS.
Vi har brukt både bottom-up og top-down tilnærminger for å lage SOAP Web-tjenester ved hjelp av JAX-WS API. Vi har også skrevet en JAX-WS-klient som eksternt kan koble til serveren og ringe webservicen.
Den komplette kildekoden er tilgjengelig på GitHub.
