beadledom-jaxrs

This module provides a guice module for providing JAX-RS specific bindings.

Correlation Id

The purpose of the correlation id is to associate request/response interactions. This allows tracing of an originating request throughout a system. This is helpful for debugging and logging purposes.

The CorrelationIdFilter reads the correlation id header from the request, adds it to the response headers, and adds it to the slf4j Mapped Diagnostic Context (MDC).

The correlation id will be taken from the correlation id request header if present, or generated if absent. The id will also be added to the response and to the MDC for logging.

The default header and mdc key name is Correlation-Id. However, both names are configurable through guice bindings. More on this later.

To include the correlation id in the catalina.out file using log4j, update the log format to include %X{Correlation-Id} replacing the name with your configured name.

PATCH

JAX-RS 2.0 (see section 3.3 for Resource Methods) does not require implementations to support the PATCH HTTP method. This is likely due to the fact that PATCH was introduced in a later rfc that added the new HTTP method to the already existing HTTP/1.1 specification.

@PATCH was added to beadledom-jaxrs to allow services to support partial updates without the need of overloading @POST. The annotation has no opinion on how the service decides to implement the resource performing the PATCH operation. Implementing services have the freedom to support JSON Patch and/or JSON Merge Patch.

As long as a service has beadledom-jaxrs as a dependency @PATCH can be used just like any of the HTTP method annotations defined by JAX-RS. Below is a small example of @PATCH being used in an interface for a resource.

@PATCH
@Path("path/to/patch")
@Produces(MediaType.APPLICATION_JSON)
public Response patch(
  @PathParam("id") final Long id,
  @ApiParam(value = "changes to make to the object with the specified id")
  PatchObject patchObject);

Download

Download using Maven

<dependency>
    <groupId>com.cerner.beadledom</groupId>
    <artifactId>beadledom-jaxrs</artifactId>
    <version>[insert latest version]</version>
</dependency>

Usage

The correlation id header and/or MDC name can overridden by adding a binding for your custom name and annotating it with @CorrelationIdHeader or @CorrelationIdMdc respectively.

public class MyModule extends AbstractModule {

  @Override
  public void configure() {
    install(new JaxRsModule());

    String customCorrelationIdName = "Not-Default";
    bind(String.class).annotatedWith(CorrelationIdHeader.class).toInstance(customCorrelationIdName);
    bind(String.class).annotatedWith(CorrelationIdMdc.class).toInstance(customCorrelationIdName);
  }
}

or

public class MyModule extends AbstractModule {

  private final String customCorrelationIdName = "Not-Default";

  @Override
  public void configure() {
    install(new JaxRsModule());
  }

  @Provides
  @CorrelationIdHeader
  public String provideCorrelationIdHeader() {
    return customCorrelationIdName;
  }

  @Provides
  @CorrelationIdMdc
  public String provideCorrelationIdMdc() {
    return customCorrelationIdName;
  }
}