entity

Description

Unmarshalls the request entity to the given type and passes it to its inner Route. An unmarshaller returns an Either with Right(value) if successful or Left(exception) for a failure. The entity method will either pass the value to the inner route or map the exception to a akka.http.javadsl.server.Rejection.

The entity directive works in conjunction with as and akka.http.scaladsl.unmarshalling to convert some serialized “wire format” value into a higher-level object structure.
The unmarshalling documentation explains this process in detail. This directive simplifies extraction and error handling to the specified type from the request.

An unmarshaller will return a Left(exception) in the case of an error. This is converted to a akka.http.scaladsl.server.Rejection within the entity directive. The following table lists how exceptions are mapped to rejections:

Examples

The following example uses Json Support via Jackson to unmarshall a json request into a simple Person

static public class Person {
  private final String name;
  private final int favoriteNumber;

  //default constructor required for Jackson
  public Person() {
    this.name = "";
    this.favoriteNumber = 0;
  }

  public Person(String name, int favoriteNumber) {
    this.name = name;
    this.favoriteNumber = favoriteNumber;
  }

  public String getName() {
    return name;
  }

  public int getFavoriteNumber() {
    return favoriteNumber;
  }
}

final Unmarshaller<HttpEntity, Person> unmarshallar = Jackson.unmarshaller(Person.class);

final Route route = entity(unmarshallar, person ->
  complete( "Person:" +  person.getName() + " - favoriteNumber:" + person.getFavoriteNumber() )
);

testRoute(route).run(
  HttpRequest.POST("/")
    .withEntity(
      HttpEntities.create(
        ContentTypes.APPLICATION_JSON, "{\"name\":\"Jane\",\"favoriteNumber\":42}"
      )
    )
).assertEntity("Person:Jane - favoriteNumber:42");