61.4. 클라이언트 요청 필터

이 섹션에서는 클라이언트 측에서 발신 요청 메시지를 가로채는 데 사용되는 클라이언트 요청 필터 를 구현하고 등록하는 방법을 설명합니다. 클라이언트 요청 필터는 헤더를 처리하는 데 자주 사용되며 모든 종류의 일반 요청 처리에 사용할 수 있습니다.

javax.ws.rs.client.ClientRequestFilter 인터페이스는 다음과 같이 정의됩니다.

// Java
package javax.ws.rs.client;
...
import javax.ws.rs.client.ClientRequestFilter;
import javax.ws.rs.client.ClientRequestContext;
...
public interface ClientRequestFilter {
    void filter(ClientRequestContext requestContext) throws IOException;
}

ClientRequestFilter 를 구현하면 클라이언트 측에서 ClientRequest 확장 지점에 대한 필터를 만들어 메시지를 서버로 보내기 전에 요청 메시지를 필터링할 수 있습니다.

ClientRequestFilter 의 filter 메서드는 발신 요청 메시지 및 관련 메타데이터에 액세스하는 데 사용할 수 있는 javax.ws.rs.client.ClientRequestContext 유형의 단일 인수를 수신합니다. ClientRequestContext 인터페이스는 다음과 같이 정의됩니다.

// Java
...
package javax.ws.rs.client;

import java.io.OutputStream;
import java.lang.annotation.Annotation;
import java.lang.reflect.Type;
import java.net.URI;
import java.util.Collection;
import java.util.Date;
import java.util.List;
import java.util.Locale;
import java.util.Map;

import javax.ws.rs.core.Configuration;
import javax.ws.rs.core.Cookie;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.core.Response;
import javax.ws.rs.ext.MessageBodyWriter;

public interface ClientRequestContext {

    public Object getProperty(String name);

    public Collection<String> getPropertyNames();

    public void setProperty(String name, Object object);

    public void removeProperty(String name);

    public URI getUri();

    public void setUri(URI uri);

    public String getMethod();

    public void setMethod(String method);

    public MultivaluedMap<String, Object> getHeaders();

    public abstract MultivaluedMap<String, String> getStringHeaders();

    public String getHeaderString(String name);

    public Date getDate();

    public Locale getLanguage();

    public MediaType getMediaType();

    public List<MediaType> getAcceptableMediaTypes();

    public List<Locale> getAcceptableLanguages();

    public Map<String, Cookie> getCookies();

    public boolean hasEntity();

    public Object getEntity();

    public Class<?> getEntityClass();

    public Type getEntityType();

    public void setEntity(final Object entity);

    public void setEntity(
            final Object entity,
            final Annotation[] annotations,
            final MediaType mediaType);

    public Annotation[] getEntityAnnotations();

    public OutputStream getEntityStream();

    public void setEntityStream(OutputStream outputStream);

    public Client getClient();

    public Configuration getConfiguration();

    public void abortWith(Response response);
}

ClientRequest 확장 지점(즉, 요청 메시지를 보내기 전에 필터가 실행되는 경우)에 대한 클라이언트 요청 필터를 구현하려면 ClientRequestFilter 인터페이스를 구현하는 클래스를 정의합니다.

예를 들어 다음 코드는 우선 순위가 20인 ClientRequest 확장 지점에 설치되는 간단한 클라이언트 요청 필터의 예를 보여줍니다.

// Java
package org.jboss.fuse.example;

import javax.ws.rs.client.ClientRequestContext;
import javax.ws.rs.client.ClientRequestFilter;
import javax.annotation.Priority;

@Priority(value = 20)
public class SampleClientRequestFilter implements ClientRequestFilter {

  public SampleClientRequestFilter() {
    System.out.println("SampleClientRequestFilter starting up");
  }

  @Override
  public void filter(ClientRequestContext requestContext) {
    System.out.println("ClientRequestFilter.filter() invoked");
  }
}

적합한 클라이언트 요청 필터를 구현하여 클라이언트 측 호출을 중단할 수 있습니다. 예를 들어 클라이언트 측 필터를 구현하여 요청이 올바르게 포맷되었는지 확인하고 필요한 경우 요청을 중단할 수 있습니다.

다음 테스트 코드는 항상 요청을 중단하고 BAD_REQUEST HTTP 상태를 클라이언트 호출 코드로 반환합니다.

// Java
package org.jboss.fuse.example;

import javax.ws.rs.client.ClientRequestContext;
import javax.ws.rs.client.ClientRequestFilter;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status;
import javax.annotation.Priority;

@Priority(value = 10)
public class TestAbortClientRequestFilter implements ClientRequestFilter {

  public TestAbortClientRequestFilter() {
    System.out.println("TestAbortClientRequestFilter starting up");
  }

  @Override
  public void filter(ClientRequestContext requestContext) {
    // Test filter: aborts with BAD_REQUEST status
    requestContext.abortWith(Response.status(Status.BAD_REQUEST).build());
  }
}

Cryostat-RS 2.0 클라이언트 API를 사용하여 javax.ws.rs.client.client .Client 개체 또는 javax.ws.rs.client.WebTarget 오브젝트에 직접 클라이언트 요청 필터를 등록할 수 있습니다. 효과적으로, 클라이언트 요청 필터를 선택적으로 다른 범위에 적용할 수 있으므로 특정 URI 경로만 필터의 영향을 받습니다.

예를 들어 다음 코드는 클라이언트 개체를 사용하여 수행한 모든 호출에 적용되도록 SampleClientRequestFilter 필터를 등록하고, TestAbortClientRequestFilter 필터를 등록하여 rest/TestAbortClientRequest RequestRequestRequest의 하위 경로에만 적용되도록 하는 방법을 보여줍니다.

// Java
...
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Invocation;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.Response;
...
Client client = ClientBuilder.newClient();
client.register(new SampleClientRequestFilter());
WebTarget target = client
  .target("http://localhost:8001/rest/TestAbortClientRequest");
target.register(new TestAbortClientRequestFilter());