Customizing Type Conversion
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’s 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 doesn’t 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 doesn’t 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 shouldn’t be necessary in Hilla, since the TypeScript-generated API shouldn’t 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