Учебник Restful Web Services на Java
Добро пожаловать в учебник Restful Web Services на Java. REST — это аббревиатура от REpresentational State Transfer. REST — это архитектурный стиль для разработки приложений, к которым можно получить доступ по сети. Архитектурный стиль REST был представлен Роем Филдингом в его докторской диссертации в 2000 году.
Спокойные веб-сервисы
Restful Web Services — это архитектура клиент-сервер без сохранения состояния, в которой веб-службы являются ресурсами и могут быть идентифицированы по их URI. Клиентские приложения REST могут использовать методы HTTP GET/POST для вызова веб-служб Restful. REST не указывает какой-либо конкретный протокол для использования, но почти во всех случаях он используется через HTTP/HTTPS. По сравнению с веб-сервисами SOAP они легковесны и не соответствуют никаким стандартам. Мы можем использовать XML, JSON, текст или любой другой тип данных для запроса и ответа.
API веб-служб Java RESTful
API Java для веб-служб RESTful (JAX-RS) — это API Java для создания веб-служб REST. JAX-RS использует аннотации для упрощения разработки и развертывания веб-сервисов. JAX-RS является частью JDK, поэтому вам не нужно ничего включать, чтобы использовать его аннотации.
Аннотации Restful Web Services
Вот некоторые из важных аннотаций JAX-RS:
@Path
: используется для указания относительного пути к классу и методам. Мы можем получить URI веб-сервиса, просканировав значение аннотации Path.@GET
,@PUT
,@POST
,@DELETE
и@HEAD
: используется для указания типа HTTP-запроса для метода.@Produces
,@Consumes
: используются для указания типов запросов и ответов.@PathParam
: используется для привязки параметра метода к значению пути путем его анализа.
Restful Web Services и SOAP
- SOAP – это протокол, тогда как REST – это архитектурный стиль.
- Сервер SOAP и клиентские приложения тесно связаны и связаны контрактом WSDL, тогда как в веб-службах REST и клиенте контракт отсутствует.
- Кривая обучения REST проста по сравнению с веб-службами SOAP.
- Типы запросов и ответов веб-служб REST могут быть XML, JSON, текстовыми и т. д., тогда как SOAP работает только с XML.
- JAX-RS — это API Java для веб-служб REST, тогда как JAX-WS — это API Java для веб-служб SOAP.
Реализации API REST
Есть две основные реализации JAX-RS API.
- Jersey: Джерси — это эталонная реализация, предоставленная Sun. Для использования Джерси в качестве нашей реализации JAX-RS все, что нам нужно, это настроить его сервлет в файле web.xml и добавить необходимые зависимости. Обратите внимание, что JAX-RS API является частью JDK, а не Джерси, поэтому мы должны добавить в наше приложение его файлы зависимостей.
- RESTEasy: RESTEasy — это проект JBoss, обеспечивающий реализацию JAX-RS.
Учебное пособие по Java Restful Web Services
Давайте посмотрим, как легко создать веб-сервис Restful, используя Jersey, а затем RESTEasy. Мы будем предоставлять следующие методы через HTTP и использовать расширение Chrome Postman для их тестирования.
URI | HTTP Method | Description |
---|---|---|
/person/{id}/getDummy | GET | Returns a dummy person object |
/person/add | POST | Adds a person |
/person/{id}/delete | GET | Delete the person with ‘id’ in the URI |
/person/getAll | GET | Get all persons |
/person/{id}/get | GET | Get the person with ‘id’ in the URI |
Джерси Restful Web Services
<project xmlns="https://maven.apache.org/POM/4.0.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>JAXRS-Example</groupId>
<artifactId>JAXRS-Example</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>war</packaging>
<dependencies>
<dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-server</artifactId>
<version>1.19</version>
</dependency>
<dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-servlet</artifactId>
<version>1.19</version>
</dependency>
<dependency>
<groupId>com.sun.jersey</groupId>
<artifactId>jersey-client</artifactId>
<version>1.19</version>
</dependency>
</dependencies>
<build>
<sourceDirectory>src</sourceDirectory>
<plugins>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>2.6</version>
<configuration>
<warSourceDirectory>WebContent</warSourceDirectory>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.3</version>
<configuration>
<source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
</plugins>
</build>
</project>
Мы не обязаны добавлять зависимости jersey-client, но если вы пишете Java-программу для вызова веб-службы REST с использованием Jersey, тогда это необходимо. Теперь давайте посмотрим на дескриптор развертывания, чтобы узнать, как настроить Джерси для создания нашего веб-приложения.
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns="https://xmlns.jcp.org/xml/ns/javaee" xsi:schemaLocation="https://xmlns.jcp.org/xml/ns/javaee https://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd" id="WebApp_ID" version="3.1">
<display-name>JAXRS-Example</display-name>
<!-- Jersey Servlet configurations -->
<servlet>
<servlet-name>Jersey REST Service</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>com.journaldev</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Jersey REST Service</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
<!-- Jersey Servlet configurations -->
</web-app>
Это все, что требуется для подключения Джерси к нашему веб-приложению, в нашем java-коде мы будем использовать аннотации JAX-RS. Обратите внимание на значение параметра инициализации com.sun.jersey.config.property.packages
для предоставления пакета, который будет сканироваться на наличие ресурсов и методов веб-службы.
Примеры классов моделей REST
Прежде всего, мы создадим два bean-компонента модели — Person
для данных нашего приложения и Response
для отправки ответа клиентским системам. Поскольку мы будем отправлять XML-ответ, bean-компоненты должны быть аннотированы с помощью @XmlRootElement
, поэтому у нас есть этот класс.
package com.journaldev.jaxrs.model;
import javax.xml.bind.annotation.XmlRootElement;
@XmlRootElement (name="person")
public class Person {
private String name;
private int age;
private int id;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
@Override
public String toString(){
return id+"::"+name+"::"+age;
}
}
package com.journaldev.jaxrs.model;
import javax.xml.bind.annotation.XmlRootElement;
@XmlRootElement
public class Response {
private boolean status;
private String message;
public boolean isStatus() {
return status;
}
public void setStatus(boolean status) {
this.status = status;
}
public String getMessage() {
return message;
}
public void setMessage(String message) {
this.message = message;
}
}
Учебные службы по веб-службам REST
На основе нашей структуры URI ниже приведен интерфейс сервиса и код его реализации.
package com.journaldev.jaxrs.service;
import com.journaldev.jaxrs.model.Person;
import com.journaldev.jaxrs.model.Response;
public interface PersonService {
public Response addPerson(Person p);
public Response deletePerson(int id);
public Person getPerson(int id);
public Person[] getAllPersons();
}
package com.journaldev.jaxrs.service;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;
import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import com.journaldev.jaxrs.model.Person;
import com.journaldev.jaxrs.model.Response;
@Path("/person")
@Consumes(MediaType.APPLICATION_XML)
@Produces(MediaType.APPLICATION_XML)
public class PersonServiceImpl implements PersonService {
private static Map<Integer,Person> persons = new HashMap<Integer,Person>();
@Override
@POST
@Path("/add")
public Response addPerson(Person p) {
Response response = new Response();
if(persons.get(p.getId()) != null){
response.setStatus(false);
response.setMessage("Person Already Exists");
return response;
}
persons.put(p.getId(), p);
response.setStatus(true);
response.setMessage("Person created successfully");
return response;
}
@Override
@GET
@Path("/{id}/delete")
public Response deletePerson(@PathParam("id") int id) {
Response response = new Response();
if(persons.get(id) == null){
response.setStatus(false);
response.setMessage("Person Doesn't Exists");
return response;
}
persons.remove(id);
response.setStatus(true);
response.setMessage("Person deleted successfully");
return response;
}
@Override
@GET
@Path("/{id}/get")
public Person getPerson(@PathParam("id") int id) {
return persons.get(id);
}
@GET
@Path("/{id}/getDummy")
public Person getDummyPerson(@PathParam("id") int id) {
Person p = new Person();
p.setAge(99);
p.setName("Dummy");
p.setId(id);
return p;
}
@Override
@GET
@Path("/getAll")
public Person[] getAllPersons() {
Set<Integer> ids = persons.keySet();
Person[] p = new Person[ids.size()];
int i=0;
for(Integer id : ids){
p[i] = persons.get(id);
i++;
}
return p;
}
}
Большая часть кода говорит сама за себя, потратьте некоторое время на ознакомление с аннотациями JAX-RS @Path
, @PathParam
, @POST
, @GET
, @Consumes
и @Produces
.
Тест спокойных веб-сервисов
Это все, что касается создания веб-сервисов с использованием реализации Jersey JAX-RS. Как видите, большая часть кода использует аннотации JAX-RS, а Jersey подключается через дескриптор развертывания и зависимости.
RESTEasy Пример веб-сервисов RESTful
<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-jaxrs</artifactId>
<version>3.0.13.Final</version>
</dependency>
<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-jaxb-provider</artifactId>
<version>3.0.13.Final</version>
</dependency>
Ниже приведен файл web.xml, в котором мы настраиваем сервлет Resteasy.
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns="https://xmlns.jcp.org/xml/ns/javaee" xsi:schemaLocation="https://xmlns.jcp.org/xml/ns/javaee https://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd" id="WebApp_ID" version="3.1">
<display-name>JAXRS-Example-RestEasy</display-name>
<listener>
<listener-class>
org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
</listener-class>
</listener>
<servlet>
<servlet-name>resteasy-servlet</servlet-name>
<servlet-class>
org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
</servlet-class>
<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>com.journaldev.jaxrs.resteasy.app.MyApp</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>resteasy-servlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
Обратите внимание на параметр инициализации, где в качестве значения предоставляется класс MyApp
. Здесь мы расширяем класс javax.ws.rs.core.Application
, как показано ниже.
package com.journaldev.jaxrs.resteasy.app;
import java.util.HashSet;
import java.util.Set;
import javax.ws.rs.core.Application;
import com.journaldev.jaxrs.service.PersonServiceImpl;
public class MyApp extends Application {
private Set<Object> singletons = new HashSet<Object>();
public MyApp() {
singletons.add(new PersonServiceImpl());
}
@Override
public Set<Object> getSingletons() {
return singletons;
}
}
RESTEasy Тест веб-сервисов
Вот и все. Наш веб-сервис готов с реализацией RESTEasy JAX-RS. Ниже приведены некоторые результаты теста расширения Postman для Chrome.
Это все, что касается учебника по веб-сервисам Restful. Я надеюсь, вы узнали об аннотациях JAX-RS и поняли преимущества наличия стандартного API, который помог нам в повторном использовании кода и легком переходе с Джерси на RESTEasy.