streamalism.org

1. Oversikt

REST-paradigmet har eksistert i ganske mange år nå, og det får fremdeles mye oppmerksomhet.

En RESTful API kan implementeres i Java på flere måter: du kan bruke Spring, JAX-RS, eller du kan bare skrive dine egne bare servlets hvis du er god og modig nok. Alt du trenger er muligheten til å eksponere HTTP-metoder - resten handler om hvordan du organiserer dem og hvordan du veileder klienten når du ringer til API-et.

Som du kan se ut fra tittelen, vil denne artikkelen dekke JAX-RS. Men hva betyr "bare en API"? Det betyr at fokuset her er på å avklare forvirringen mellom JAX-RS og implementeringene og å tilby et eksempel på hvordan en skikkelig JAX-RS-webapp ser ut.

2. Inkludering i Java EE

JAX-RS er ikke noe mer enn en spesifikasjon, et sett med grensesnitt og merknader som tilbys av Java EE. Og så har vi selvfølgelig implementeringene; noen av de mer kjente er RESTEasy og Jersey.

Også, hvis du noen gang bestemmer deg for å bygge en JEE-kompatibel applikasjonsserver, vil gutta fra Oracle fortelle deg at serveren din blant mange andre ting skal gi en JAX-RS-implementering for de distribuerte appene å bruke. Derfor heter den Java Enterprise Edition Plattform.

Et annet godt eksempel på spesifikasjon og implementering er JPA og Hibernate.

2.1. Lette kriger

Så hvordan hjelper alt dette oss, utviklerne? Hjelpen er i og med at våre distribuerbare kan og burde være veldig tynne, slik at applikasjonsserveren tilbyr de nødvendige bibliotekene. Dette gjelder også når du utvikler en RESTful API: den endelige gjenstanden skal ikke inneholde informasjon om den brukte JAX-RS-implementeringen.

Visst, vi kan tilby implementeringen (her er en veiledning for RESTeasy). Men da kan vi ikke kalle applikasjonen vår “Java EE app” lenger. Hvis i morgen kommer noen og sier “Ok, tid til å bytte til Glassfish eller Payara, JBoss ble for dyrt!“, Vi kan kanskje gjøre det, men det blir ikke en enkel jobb.

Hvis vi gir vår egen implementering, må vi sørge for at serveren vet å ekskludere sin egen - dette skjer vanligvis ved å ha en proprietær XML-fil i den distribuerbare. Det er unødvendig å si at en slik fil skal inneholde alle slags koder og instruksjoner som ingen vet noe om, bortsett fra utviklerne som forlot selskapet for tre år siden.

2.2. Kjenn alltid serveren din

Vi sa så langt at vi burde dra nytte av plattformen vi tilbys.

Før vi bestemmer oss for en server som skal brukes, bør vi se hvilken JAX-RS-implementering (navn, leverandør, versjon og kjente feil) den gir, i det minste for produksjonsmiljøer. For eksempel kommer Glassfish med Jersey, mens Wildfly eller Jboss kommer med RESTEasy.

Dette betyr selvfølgelig litt tid på forskning, men det skal bare gjøres en gang, i begynnelsen av prosjektet eller når du migrerer det til en annen server.

3. Et eksempel

Hvis du vil begynne å spille med JAX-RS, er den korteste veien: ha et Maven webapp-prosjekt med følgende avhengighet i pom.xml:

 javax javaee-api 7.0 gitt 

Vi bruker JavaEE 7 siden det allerede er mange applikasjonsservere som implementerer den. API-glasset inneholder merknadene du trenger å bruke, plassert i pakken javax.ws.rs. Hvorfor er omfanget "gitt"? Fordi denne krukken ikke trenger å være i den endelige bygningen heller - vi trenger den på kompileringstidspunktet, og den leveres av serveren for kjøretiden.

Etter at avhengigheten er lagt til, må vi først skrive inngangsklassen: en tom klasse som strekker seg javax.ws.rs.core.Application og er kommentert med javax.ws.rs.ApplicationPath:

@ApplicationPath ("/ api") offentlig klasse RestApplication utvider applikasjonen {} 

Vi definerte inngangsveien som værende / api. Uansett andre veier vi angir for ressursene våre, vil de være foran / api.

La oss se en ressurs:

@Path ("/ notifications") public class NotificationsResource {@GET @Path ("/ ping") public Response ping () {return Response.ok (). Entity ("Service online"). Build (); } @GET @Path ("/ get / {id}") @Produces (MediaType.APPLICATION_JSON) public Response getNotification (@PathParam ("id") int id) {return Response.ok () .entity (new Notification (id , "john", "testnotification")) .build (); } @POST @Path ("/ post /") @Consumes (MediaType.APPLICATION_JSON) @Produces (MediaType.APPLICATION_JSON) public Response postNotification (Notification notification) {return Response.status (201) .entity (notification) .build () ; }}

Vi har et enkelt ping-endepunkt for å ringe og sjekke om appen vår kjører, en GET og en POST for en varsling (dette er bare en POJO med attributter pluss getters og setters).

Distribuer denne krigen på enhver applikasjonsserver som implementerer JEE7, og følgende kommandoer fungerer:

curl // localhost: 8080 / simple-jaxrs-ex / api / notifications / ping / curl // localhost: 8080 / simple-jaxrs-ex / api / notifications / get / 1 curl -X POST -d '{"id" : 23, "text": "lorem ipsum", "brukernavn": "johana"} '// localhost: 8080 / simple-jaxrs-ex / api / notifications / post / --header "Content-Type: application / json "

Hvor simple-jaxrs-ex er kontekst-roten til webappen.

Dette ble testet med Glassfish 4.1.0 og Wildfly 9.0.1.Final. Vær oppmerksom på at de to siste kommandoene ikke fungerer med Glassfish 4.1.1 på grunn av denne feilen. Det er tilsynelatende et kjent problem i denne Glassfish-versjonen, angående serialisering av JSON (hvis du må bruke denne serverversjonen, må du administrere JSON marshaling alene)

4. Konklusjon

På slutten av denne artikkelen, bare husk at JAX-RS er et kraftig API og at de fleste (om ikke alle) tingene du trenger allerede er implementert av webserveren din. Du trenger ikke å gjøre den distribuerbare til en uhåndterlig haug med biblioteker.

Denne oppskriften presenterer et enkelt eksempel, og ting kan bli mer kompliserte. For eksempel vil du kanskje skrive dine egne marshalere. Når det er nødvendig, se etter veiledninger som løser problemet ditt med JAX-RS, ikke med Jersey, Resteasy eller annen konkret implementering. Det er veldig sannsynlig at problemet ditt kan løses med en eller to kommentarer.