Доступ к параметрам запросов в RESTful веб-сервисах.
Во второй статье (http://forum.vingrad.ru/index.php?show_type=forum&showtopic=242699&kw=restful-jax--jersey-webservices) было показано как обрабатывать HTTP запросы с помощью RESTful веб-сервисов. В данной статье мы коснемся вопросов доступа и обработки параметров HTTP запросов.
Виды параметров и их определение.
JAX-RS поддерживает следующие виды параметров для автоматического инжектирования:- @MatrixParam - извлекает значение URI matrix параметра.
- @QueryParam - извлекает значение URI query параметра.
- @PathParam - извлекает значение URI параметра по шаблону.
- @CookieParam - извлекает значение cookie параметра.
- @HeaderParam - извлекает значение параметра из заголовка запроса.
- @FormParam - извлекает значение параметра из заголовка запроса.
Эти аннотации могут быть использованы на параметрах методов, полях классов и setter методах. Во время выполнения, контейнер подставит туда актуальные значения. Далее рассмотрим некоторые примеры их использования.
Пример использования @Path параметров с шаблонами.
Path-параметр извлекается непосредственно из URI. Шаблон для него можно задать с помощью аннотации @Path, а извлечении сделать с помощью @PathParam. Рассмотрим следующий шаблон URI:
| Цитата | http://localhost:8080/myrestfulapp/webresources/simpleservice/{filename}/{version}
|
{filename} и {version} могут меняться, но обработка должна происходить в одном сервисе. При этом, {version} может состоять только из числовых символов. Такой URI можно обрабатывать следующим сервисом:
| Код |
package com.mycompany;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
@Path("simpleservice")
public class SimpleService
{
@GET
@Path("/{filename}/{version:.*[0-9]}")
@Produces("text/plain")
public String myGetHandler(
@PathParam("filename") String filename,
@PathParam("version") String version)
{
return "this is content of file " + filename + " v[" + version + "]";
}
}
|
Примером реального и правильного URI в данном случае может быть такой:
| Цитата | http://localhost:8080/myrestfulapp/webresources/simpleservice/test.txt/12
|
Результатом такого запроса:
| Цитата | http://localhost:8080/myrestfulapp/webresources/simpleservice/test.txt/12ab
|
Будет ошибка 404, поскольку параметр версии не удовлетворяет заданному шаблону.
Так же можно использовать объект UriInfo для получения доступа к параметрам:
| Код |
package com.mycompany;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.core.UriInfo;
@Path("simpleservice")
public class SimpleService
{
@Context
private UriInfo uriInfo;
@GET
@Path("/{filename}/{version:.*[0-9]}")
@Produces("text/plain")
public String myGetHandler()
{
MultivaluedMap<String, String> pathParameters = uriInfo.getPathParameters(false);
return "this is content of file " + pathParameters.getFirst("filename") +
" v[" + pathParameters.getFirst("version") + "]";
}
}
|
Пример использования @QueryParam.
@QueryParam используется для извлечения параметров запроса. Такие параметры передаются после URI запроса. Вот пример такого URI:
| Цитата | http://localhost:8080/myrestfulapp/webresources/simpleservice?filename=test.txt&version=12
|
В данном случае передается 2 параметра: filename со значением test.txt и version со значением 12. Получить доступ в сервисе к таким параметрам можно как показано в следующем примере:
| Код |
package com.mycompany;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
@Path("simpleservice")
public class SimpleService
{
@GET
@Produces("text/plain")
public String myGetHandler(
@QueryParam("filename") String filename,
@QueryParam("version") String version)
{
return "this is content of file " + filename + " v[" + version + "]";
}
}
|
Пример использования @MatrixParam.
Получение Matrix параметров схоже с получением Query параметров.
Пример URI:
| Цитата | http://localhost:8080/myrestfulapp/webresources/simpleservice;filename=test.txt;version=15
|
Код сервиса для обработки Matrix параметров:
| Код |
package com.mycompany;
import javax.ws.rs.GET;
import javax.ws.rs.MatrixParam;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
@Path("simpleservice")
public class SimpleService
{
@GET
@Produces("text/plain")
public String myGetHandler(
@MatrixParam("filename") String filename,
@MatrixParam("version") String version)
{
return "this is content of file " + filename + " v[" + version + "]";
}
}
|
Пример использования @FormParam.
Аннотация @FormParam может быть использована для извлечения параметров переданных POST запросом, если его MIME тип application/x-www-form-urlencoded.
@FormParam используется аналогично другим аннотациям для доступа к параметрам.
| Код |
package com.mycompany;
import javax.ws.rs.Consumes;
import javax.ws.rs.FormParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.core.Response;
@Path("simpleservice")
public class SimpleService
{
@POST
@Consumes("application/x-www-form-urlencoded")
public Response myGetHandler(
@FormParam("filename") String filename,
@FormParam("version") String version)
{
// do something with parameters.
return Response.noContent().build();
}
}
|
Пример использования @DefaultValue.
Вы также можете использовать аннотацию @DefaultValue для установки значения по умолчанию для параметров. Это полезно, если оно не было явно задано в запросе.
| Код |
package com.mycompany;
import javax.ws.rs.DefaultValue;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
@Path("simpleservice")
public class SimpleService
{
@GET
@Produces("text/html")
public String firstMessage(
@DefaultValue("powerOn") @QueryParam("name") String username)
{
return "<html><body><b> Hello, " + username + "! This is a simple RESTful web service!</b></body></html>";
}
}
|
На этом я завершаю обзор методов получения доступа к параметрам запросов из RESTful веб-сервисов. Дополнительную информацию можно получить обратившись к официальной документации по JAX-RS (JSR-311).
Ссылки на ресурсы используемые при написании статьи:
https://jersey.dev.java.net/ - домашняя страница проекта Jersey.
http://java.sun.com/developer/technicalArticles/WebServices/restful/ - обзор RESTful веб-сервисов на java.sun.com.
http://jcp.org/en/jsr/detail?id=311 - спецификация JAX-RS 1.0.
http://docs.sun.com/app/docs/doc/820-4867/6nga7f5mk?l=ru&a=view - руководство разработчика.
|