Согласование содержимого во время выполнения

Аннотации @Produces и @Consumes обрабатывают согласование статического содержимого в JAX-RS. Эти аннотации определяют настройки содержимого сервера. Заголовки HTTP Accept, Content-Type и Accept-Language определяют параметры согласования содержимого клиента.

Дополнительные сведения о заголовках HTTP для согласования содержимого см. в HTTP/1.1 — Согласование содержимого (http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html).

Следующий фрагмент кода показывает настройки содержимого сервера:

@Produces("text/plain")
@Path("/employee")
public class Employee {

    @GET
    public String getEmployeeAddressText(String address) {...}

    @Produces("text/xml")
    @GET
    public String getEmployeeAddressXml(Address address) {...}
}

Метод getEmployeeAddressText вызывается для HTTP-запроса, который выглядит следующим образом:

GET /employee
Accept: text/plain

Это даст следующий ответ:

500 Oracle Parkway, Redwood Shores, CA

Метод getEmployeeAddressXml вызывается для HTTP-запроса, который выглядит следующим образом:

GET /employee
Accept: text/xml

Это даст следующий ответ:

<address street="500 Oracle Parkway, Redwood Shores, CA" country="USA"/>

При согласовании статического содержимого вы также можете определить несколько типов содержимого и MIME для клиента и сервера.

@Produces("text/plain", "text/xml")

Помимо поддержки согласования статического содержимого, JAX-RS также поддерживает согласование содержимого во время выполнения с использованием объектов javax.ws.rs.core.Variant и Request. Класс Variant определяет представление ресурса согласования контента. Каждый объект класса Variant может содержать тип MIME, язык и кодировку. Объект Variant определяет представление ресурса, которое поддерживается сервером. Класс Variant.VariantListBuilder используется для создания списка вариантов представления.

В следующем фрагменте кода показано, как создать список вариантов представления ресурсов:

List<Variant> vs = Variant.mediatypes("application/xml", "application/json")
        .languages("en", "fr").build();

Этот фрагмент кода вызывает метод build класса VariantListBuilder. Класс VariantListBuilder вызывается при вызове методов mediatypes, languages или encodings. Метод build создаёт серию представлений ресурсов. Список Variant, созданный методом build, содержит все возможные комбинации элементов, указанных в методах mediatypes, languages и encodings.

В этом примере размер объекта vs, как определено в этом фрагменте кода, равен 4, а содержимое выглядит следующим образом:

[["application/xml","en"], ["application/json","en"],
    ["application/xml","fr"],["application/json","fr"]]

Метод javax.ws.rs.core.Request.selectVariant принимает список объектов Variant и выбирает объект Variant, который соответствует HTTP-запросу. Этот метод сравнивает свой список объектов Variant с заголовками Accept, Accept-Encoding, Accept-Language и Accept-Charset HTTP-запроса.

В следующем фрагменте кода показано, как использовать метод selectVariant для выбора наиболее приемлемого Variant из значений в клиентском запросе:

@GET
public Response get(@Context Request r) {
    List<Variant> vs = ...;
    Variant v = r.selectVariant(vs);
    if (v == null) {
        return Response.notAcceptable(vs).build();
    } else {
        Object rep = selectRepresentation(v);
        return Response.ok(rep, v);
    }
}

Метод selectVariant возвращает объект Variant, который соответствует запросу, или null, если совпадений не найдено. В этом фрагменте кода, если метод возвращает значение null, создаётся объект Response неприемлемого ответа. В противном случае возвращается объект Response со статусом OK, содержащий представление сущности в форме Object и Variant.