Customizing Type Conversion

Using annotations to control the options when serializing and deserializing data in Java endpoints.

Annotations

When serializing and deserializing data in Java endpoints, the developer might be interested in renaming properties and excluding certain properties and types.

Omitting properties helps the application avoid sending sensitive data, such as password fields. Leaving out types helps to simplify the TypeScript-exported classes, and to avoid circular dependencies in the serialized JSON output.

Annotations

Hilla relies on the Jackson JSON library to do serialization, so it is possible to use their annotations to rename properties or exclude data.

The @JsonProperty Annotation

The @JsonProperty annotation is used to define a method as a setter or getter for a logical property, or to define a field to be serialized and deserialized as a specific logical property.

The annotation value indicates the name of the property in the JSON object. By default, it takes the Java name of the method or field.

public class Student {
   @JsonProperty("bookId")
   private String id;
   private String name;

   @JsonProperty("name")
   public void setFirstName(String name) {
      this.name = name;
   }

   @JsonProperty("name")
   public String getFirstName() {
      return name;
   }

   @JsonProperty
   public int getRating() {
      return StudentRating.getRatingFor(name);
   }
}

The @JsonIgnore Annotation

The @JsonIgnore annotation indicates that the logical property used in serializing and deserializing for the accessor (field, getter or setter) is to be ignored.

@JsonIgnore
private String category;

@JsonIgnore
public String getCategory() {
  return category;
}

@JsonIgnore
public void setCategory(String category) {
   this.category = category;
}

The @JsonIgnoreProperties Annotation

The @JsonIgnoreProperties annotation ignores a set of logical properties in serializing and deserializing. It must be used at class level.

@JsonIgnoreProperties(value = { "id"}, allowGetters = true)
public class Product {
   private String id;
   private String name;

   ...
}

In addition to the properties passed as the annotation value, the @JsonIgnoreProperties annotation accepts the following options:

allowSetters

For ignored properties, allowSetters allows you to set properties when deserializing, but does not list them in serialization.

In the following snippet, password would not be in the payload returned to TypeScript, but TypeScript can set it.

@JsonIgnoreProperties(value = { "password"}, allowSetters = true)
public class User {
   private String name;
   private String password;

   ...
}

allowGetters

For ignored properties, allowGetters lists them in the serialized object but does not allow you to set it.

This is useful for read-only properties

@JsonIgnoreProperties(value = { "id"}, allowGetters = true)
public class Product {
   private String id;
   private String name;

   ...
}

ignoreUnknown

During deserializing, ignoreUnknown prevents an error caused by the presence of a property in the JSON object that has no corresponding property in the Java class.

This is a corner case, and should not be necessary in Hilla, since the TypeScript-generated API should not pass unknown properties.

The @JsonIgnoreType Annotation

The @JsonIgnoreType annotation is a class-level annotation that indicates that all properties of the annotated class type should be ignored during serializing and deserializing.

In the following example, the field client in Sale will be omitted in the JSON result.

@JsonIgnoreType
public class Client {
   ...
}

@JsonIgnoreProperties(value = { "password"}, allowSetters = true)
public class Sale {
   private Client client;

   private Product product;
   private int amount;
   private double total;

   ...
}

diff --git a/articles/application/configuring.asciidoc b/articles/application/configuring.asciidoc

Hilla Documentation