rest-patch

This library aims to aid in supporting patching for requests in Java-based RESTFUL webservices. It is not tied into Spring in anyway, but all examples here are shown using Spring Boot. It aims to support the logical way of handling REST patching in services like Stripe and Previsto and hence support JSON and FORM based requests.

What does it do?

Merging

First of all it allows you to patch a POJO upon another POJO of same type based on a list of dirty fields. You simply gather a list of dirty fields which you want to be patched from one POJO to another. You use the EntityMerger for this purpose as shown below.

Merge Example

public void main() {
  EntityMerger merger = new EntityMerger();
  Pet patch = new Pet();
  patch.setName("Bella");
  patch.setKind(Kind.Cat);
  
  Pet original = new Pet();
  original.setName("Barkley");
  original.setKind(Kind.Dog);
  
  List<String> dirtyFields = Collections.singletonList("name");
  merger.mergeEntities(original, patch, dirtyFields);
  
  System.out.println(original.getName()); // Outputs "Bella" (Was patched)
  System.out.println(original.getKind()); // Outputs "Dog" (Was NOT patched)  
}

Resolve dirty fields

Second, it allows you to gather the dirty fields from JSON(via Jackson) and FORM(via Java Map) requests. Checkout the following examples:

JSON Example (Spring Boot)

@RestController
public class PetController {

  private TreeNodePropertyReferenceConverter fieldConverter = new TreeNodePropertyReferenceConverter();
  private EntityMerger<Pet> merger = new EntityMerger();
    
  @PutMapping("/pets/{id}")
  public Pet update(@RequestBody Pet patch, @PathVariable String id) {
    Pet original = ...;  // Get original from backend
    List<String> fields = fieldConverter.translate(TreeNodeHolder.get());
    Pet merge = this.merger.mergeEntities(original, patch, fields);
    ... // Save merge to backend
  } 
}

The above example allows us to send just the fields we want to update, fx. {"name": "Bessie"}, without overwriting other fields.

Note on thread safety: TreeNodeHolder is a single slot per thread and is cleared at the start of every capture, so a failed request never leaves stale data behind. Always consume the captured node immediately and release it in a finally block:

try {
  Pet original = ...;
  List<String> fields = fieldConverter.translate(TreeNodeHolder.get());
  ...
} finally {
  TreeNodeHolder.clear();
}

Getting dirty fields without thread-local state (recommended)

If you control the ObjectMapper, use a JacksonTreeNodeMapper and the Patched API instead. The raw tree node is returned together with the deserialized value, so no thread-local state is involved at all:

@RestController
public class PetController {

  private JacksonTreeNodeMapper mapper = new JacksonTreeNodeMapper();
  private EntityMerger<Pet> merger = new EntityMerger();

  @PutMapping("/pets/{id}")
  public Pet update(@RequestBody String payload, @PathVariable String id) throws IOException {
    Pet original = ...;  // Get original from backend
    Patched<Pet> patched = mapper.readPatchedValue(payload, Pet.class);
    List<String> fields = patched.dirtyFields();
    Pet merge = this.merger.mergeEntities(original, patched.value(), fields);
    ... // Save merge to backend
  }
}

It gives you the same flexibility with FORM input which is handy when it comes to supporting access to the API via cUrl.

FORM Example (Spring Boot)

@RestController
public class PetController {

  private FormPropertyReferenceConverter fieldConverter = new FormPropertyReferenceConverter();
  private EntityMerger<Pet> merger = new EntityMerger();
    
  @PutMapping("/pets/{id}", consumes = "application/x-www-form-urlencoded")
  public Pet update(@ModelAttribute Pet patch, @PathVariable String id, HttpServletRequest request) {
    Pet original = ...;  // Get original from backend
    List<String> fields = fieldConverter.translate(request.getParameterMap());
    Pet merge = this.merger.mergeEntities(original, patch, fields);
    ... // Save merge to backend
  } 
}

The above example allows us to send just the fields we want to update via cUrl, fx. curl -X PUT -d name=Bessie http://server/pets/{id}, without overwriting other fields.