JAX-RS je samo API!

1. Pregled

Paradigma REST postoji već nekoliko godina i još uvijek joj se posvećuje velika pažnja.

API RESTful može se implementirati u Javu na više načina: možete koristiti Spring, JAX-RS ili možete napisati vlastite gole servlete ako ste dovoljno dobri i hrabri. Sve što trebate je sposobnost izlaganja HTTP metoda - ostalo je sve o tome kako ih organizirate i kako vodite klijenta prilikom pozivanja na vaš API.

Kao što možete razabrati iz naslova, ovaj će članak pokrivati ​​JAX-RS. Ali što znači "samo API"? To znači da je ovdje fokus na rasvjetljavanju zabune između JAX-RS i njegovih implementacija i na pružanju primjera kako izgleda odgovarajući JAX-RS webapp.

2. Uključivanje u Java EE

JAX-RS nije ništa drugo nego specifikacija, skup sučelja i napomena koje nudi Java EE. I onda, naravno, imamo implementacije; neki od poznatijih su RESTEasy i Jersey.

Također, ako ikad odlučite izgraditi JEE-kompatibilan poslužitelj aplikacija, momci iz Oraclea reći će vam da, između ostalog, vaš poslužitelj treba pružiti JAX-RS implementaciju za instalirane aplikacije koje će se koristiti. Zbog toga se zove Java Enterprise Edition Platforma.

Još jedan dobar primjer specifikacije i provedbe su JPA i Hibernate.

2.1. Lagani ratovi

Pa kako sve ovo pomaže nama, programerima? Pomoć je u tome što naši raspoloživi programi mogu i trebaju biti vrlo tanki, dopuštajući aplikacijskom poslužitelju da pruži potrebne knjižnice. To se odnosi i na razvoj RESTful API-ja: konačni artefakt ne smije sadržavati nikakve informacije o korištenoj implementaciji JAX-RS.

Svakako, možemo pružiti implementaciju (evo vodiča za RESTeasy). Ali tada našu aplikaciju više ne možemo nazivati ​​"Java EE aplikacijom". Ako sutra netko dođe i kaže “Ok, vrijeme je za prelazak na Glassfish ili Payaru, JBoss je postao preskup!“, Možda bismo to mogli učiniti, ali to neće biti lak posao.

Ako osiguravamo vlastitu implementaciju, moramo biti sigurni da poslužitelj zna isključiti vlastitu - to se obično događa tako što se u raspoloživu vlasničku XML datoteku. Nepotrebno je reći da bi takva datoteka trebala sadržavati sve moguće oznake i upute o kojima nitko ništa ne zna, osim programera koji su tvrtku napustili prije tri godine.

2.2. Uvijek znajte svoj poslužitelj

Dosad smo rekli da bismo trebali iskoristiti platformu koja nam se nudi.

Prije nego što se odlučimo za poslužitelj za upotrebu, trebali bismo vidjeti koju implementaciju JAX-RS (ime, dobavljač, verzija i poznate pogreške) pruža, barem za proizvodna okruženja. Na primjer, Glassfish dolazi s Jerseyem, dok Wildfly ili Jboss dolazi s RESTEasyem.

To, naravno, znači malo vremena provedenog na istraživanju, ali to bi trebalo biti učinjeno samo jednom, na početku projekta ili prilikom njegove migracije na drugi poslužitelj.

3. Primjer

Ako želite početi igrati s JAX-RS, najkraći put je: imajte Maven webapp projekt sa sljedećom ovisnošću u pom.xml:

 javax javaee-api 7.0 

Koristimo JavaEE 7 jer već postoji puno aplikacijskih poslužitelja koji ga implementiraju. Taj API jar sadrži napomene koje trebate koristiti, a nalaze se u paketu javax.ws.rs. Zašto je opseg "osiguran"? Budući da ni ovaj jar ne mora biti u završnoj gradnji - potreban nam je u vrijeme kompajliranja, a pruža ga poslužitelj za vrijeme izvođenja.

Nakon dodavanja ovisnosti, prvo moramo napisati ulaznu klasu: praznu klasu koja se proteže javax.ws.rs.core.Prijava a bilježi se s javax.ws.rs.ApplicationPath:

@ApplicationPath ("/ api") javna klasa RestApplication proširuje aplikaciju {} 

Put ulaska definirali smo kao / api. Bez obzira na druge puteve koje deklariramo za svoje resurse, oni će imati prefiks / api.

Dalje, pogledajmo resurs:

@Path ("/ notifications") javna klasa NotificationsResource {@GET @Path ("/ ping") javni odgovor ping () {return Response.ok (). Entitet ("Usluga na mreži"). Build (); } @GET @Path ("/ get / {id}") @Produces (MediaType.APPLICATION_JSON) javni odgovor getNotification (@PathParam ("id") int id) {return Response.ok () .entity (nova obavijest (id , "john", "obavijest o testiranju")) .build (); } @POST @Path ("/ post /") @Consumes (MediaType.APPLICATION_JSON) @Produces (MediaType.APPLICATION_JSON) javni odgovor postNotification (obavijest o obavijesti) {return Response.status (201) .entity (notification) .build () ; }}

Moramo nazvati jednostavnu krajnju točku pinga i provjeriti radi li naša aplikacija, GET i POST za obavijest (ovo je samo POJO s atributima plus getteri i postavljači).

Primijenite ovaj rat na bilo kojem aplikacijskom poslužitelju koji implementira JEE7 i sljedeće naredbe će raditi:

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", "username": "johana"} '// localhost: 8080 / simple-jaxrs-ex / api / notifications / post / --header "Content-Type: application / json "

Gdje je simple-jaxrs-ex kontekst-korijen webappa.

Ovo je testirano na Glassfishu 4.1.0 i Wildfly 9.0.1.Final. Imajte na umu da posljednje dvije naredbe neće raditi sa Glassfishom 4.1.1 zbog ove pogreške. Očigledno je poznato pitanje u ovoj verziji Glassfish-a u vezi sa serializacijom JSON-a (ako morate koristiti ovu verziju poslužitelja, morat ćete sami upravljati JSON-ovim marširanjem)

4. Zaključak

Na kraju ovog članka, imajte na umu da je JAX-RS moćan API i većinu (ako ne i sve) stvari koje trebate vaš je web-poslužitelj već implementirao. Ne morate pretvoriti svoju raspoloživu u neupravljivu hrpu knjižnica.

Ovaj opis predstavlja jednostavan primjer i stvari bi se mogle zakomplicirati. Na primjer, možda biste htjeli napisati vlastite maršalere. Kad je to potrebno, potražite vodiče koji će riješiti vaš problem s JAX-RS, a ne s Jerseyem, Resteasyem ili nekom drugom konkretnom primjenom. Vrlo je vjerojatno da se vaš problem može riješiti s jednom ili dvije bilješke.