diff --git a/README.md b/README.md index 8e6714b..53bb277 100644 --- a/README.md +++ b/README.md @@ -2,68 +2,94 @@ [![Maven Central](https://img.shields.io/maven-central/v/com.cosium.hal_model/hal-model.svg)](https://central.sonatype.com/artifact/com.cosium.hal_model/hal-model) # HAL Model -A java modelisation of HAL (Hypertext Application Language) + +A java modelisation of HAL (Hypertext Application Language). # Prerequisites + - Java 17+ -# Quick start - -1. Add the `hal-model` dependency: - ```xml - - com.cosium.hal_model - hal-model2 - ${hal-model.version} - - ``` -2. Add `HalModelJacksonModule` to your [Jackson ObjectMapper](https://github.com/fasterxml/jackson): - ```java - JsonMapper jsonMapper = JsonMapper.builder().addModule(new HalModelJacksonModule()).build(); - ``` -3. Use [Jackson ObjectMapper](https://github.com/fasterxml/jackson) to parse any HAL(-FORMS) JSON body +# Setup + +Add the `hal-model` dependency: + +```xml + + com.cosium.hal_model + hal-model2 + ${hal-model.version} + +``` + +# JSON parsing + +## HalFormsBodies#parseJson + +```java +record User(@JsonProperty("username") String username) { +} + +void main() { + HalFormsBody halFormsBody = HalFormsBodies.parseJson(json); +} +``` + +## Custom Jackson JsonMapper + +```java +record User(@JsonProperty("username") String username) { +} + +void main() { + JsonMapper jsonMapper = JsonMapper.builder().addModule(new HalModelJacksonModule()).build(); + HalFormsBody halFormsBody = jsonMapper.readValue(json, new TypeReference<>() { + }); +} +``` # Atomic representation parsing ```json { - "username" : "jdoe", - "_links" : { - "self" : { - "href" : "http://localhost/self" + "username": "jdoe", + "_links": { + "self": { + "href": "http://localhost/self" } }, - "_templates" : { - "default" : { - "method" : "PUT", - "properties" : [ { - "name" : "foo" - } ] + "_templates": { + "default": { + "method": "PUT", + "properties": [ + { + "name": "foo" + } + ] } } } ``` ```java -record User(@JsonProperty("username") String username) {} +record User(@JsonProperty("username") String username) { +} void main() { - JsonMapper jsonMapper = JsonMapper.builder().addModule(new HalModelJacksonModule()).build(); - HalFormsBody halFormsBody = jsonMapper.readValue(json, new TypeReference<>() {}); - assertThat(halFormsBody.representation().username()).isEqualTo("jdoe"); - assertThat(halFormsBody.linkByName()).containsOnlyKeys("self"); - assertThat(halFormsBody.requireLink("self").href().expand()) - .isEqualTo("http://localhost/self"); - assertThat(halFormsBody.requireSelfUri()).isEqualTo("http://localhost/self"); - - assertThat(halFormsBody.templateByKey()).containsOnlyKeys("default"); - - TemplateRepresentation template = halFormsBody.requireTemplate("default"); - assertThat(template.method()).isEqualTo("PUT"); - assertThat(template.propertyByName()).containsOnlyKeys("foo"); - - TemplatePropertyRepresentation property = template.propertyByName().get("foo"); - assertThat(property.type()).isEqualTo("text"); + HalFormsBody halFormsBody = HalFormsBodies.parseJson(json); + assertThat(halFormsBody.representation().username()).isEqualTo("jdoe"); + assertThat(halFormsBody.linkByName()).containsOnlyKeys("self"); + assertThat(halFormsBody.requireLink("self").href().expand()) + .isEqualTo("http://localhost/self"); + assertThat(halFormsBody.requireSelfUri()).isEqualTo("http://localhost/self"); + + assertThat(halFormsBody.templateByKey()).containsOnlyKeys("default"); + + TemplateRepresentation template = halFormsBody.requireTemplate("default"); + assertThat(template.method()).isEqualTo("PUT"); + assertThat(template.propertyByName()).containsOnlyKeys("foo"); + + TemplatePropertyRepresentation property = template.propertyByName().get("foo"); + assertThat(property.type()).isEqualTo("text"); } ``` @@ -71,46 +97,55 @@ void main() { ```json { - "_embedded" : { - "content" : [ "element1", "element2" ] + "_embedded": { + "content": [ + "element1", + "element2" + ] }, - "_links" : { - "self" : { - "href" : "http://localhost/self" + "_links": { + "self": { + "href": "http://localhost/self" } }, - "_templates" : { - "default" : { - "method" : "PUT", - "properties" : [ { - "name" : "foo" - } ] + "_templates": { + "default": { + "method": "PUT", + "properties": [ + { + "name": "foo" + } + ] } } } ``` ```java -record ContentList(@JsonProperty("content") @Nullable List content) {} +record ContentList(@JsonProperty("content") @Nullable List content) { +} void main() { - JsonMapper jsonMapper = JsonMapper.builder().addModule(new HalModelJacksonModule()).build(); - HalFormsBody>> halFormsBody = - JSON_MAPPER.readValue(json, new TypeReference<>() {}); - assertThat(halFormsBody.representation().requireEmbedded().content()) - .containsExactly("element1", "element2"); - assertThat(halFormsBody.linkByName()).containsOnlyKeys("self"); - assertThat(halFormsBody.requireLink("self").href().expand()) - .isEqualTo("http://localhost/self"); - - assertThat(halFormsBody.templateByKey()).containsOnlyKeys("default"); - - TemplateRepresentation template = halFormsBody.requireTemplate("default"); - assertThat(template.method()).isEqualTo("PUT"); - assertThat(template.propertyByName()).containsOnlyKeys("foo"); - - TemplatePropertyRepresentation property = template.propertyByName().get("foo"); - assertThat(property.type()).isEqualTo("text"); + HalFormsBody>> halFormsBody = HalFormsBodies.parseJson(json); + assertThat(halFormsBody.representation().requireEmbedded().content()) + .containsExactly("element1", "element2"); + assertThat(halFormsBody.linkByName()).containsOnlyKeys("self"); + assertThat(halFormsBody.requireLink("self").href().expand()) + .isEqualTo("http://localhost/self"); + + assertThat(halFormsBody.templateByKey()).containsOnlyKeys("default"); + + TemplateRepresentation template = halFormsBody.requireTemplate("default"); + assertThat(template.method()).isEqualTo("PUT"); + assertThat(template.propertyByName()).containsOnlyKeys("foo"); + + TemplatePropertyRepresentation property = template.propertyByName().get("foo"); + assertThat(property.type()).isEqualTo("text"); } +``` + +# Dependencies -``` \ No newline at end of file +- [Jackson 3](https://github.com/fasterxml/jackson) +- [JSpecify](https://jspecify.dev/) +- [Handy-URI-Templates](https://github.com/damnhandy/Handy-URI-Templates) \ No newline at end of file diff --git a/src/main/java/com/cosium/hal_model2/HalFormsBodies.java b/src/main/java/com/cosium/hal_model2/HalFormsBodies.java new file mode 100644 index 0000000..a98dfc2 --- /dev/null +++ b/src/main/java/com/cosium/hal_model2/HalFormsBodies.java @@ -0,0 +1,19 @@ +package com.cosium.hal_model2; + +import tools.jackson.core.type.TypeReference; +import tools.jackson.databind.json.JsonMapper; + +/** + * @author Réda Housni Alaoui + */ +public class HalFormsBodies { + + private static final JsonMapper JSON_MAPPER = + JsonMapper.builder().addModule(new HalModelJacksonModule()).build(); + + private HalFormsBodies() {} + + public static HalFormsBody parseJson(String json) { + return JSON_MAPPER.readValue(json, new TypeReference<>() {}); + } +} diff --git a/src/main/java/com/cosium/hal_model2/HalFormsBody.java b/src/main/java/com/cosium/hal_model2/HalFormsBody.java index 59f9ac1..9019ec2 100644 --- a/src/main/java/com/cosium/hal_model2/HalFormsBody.java +++ b/src/main/java/com/cosium/hal_model2/HalFormsBody.java @@ -9,6 +9,7 @@ * @author Réda Housni Alaoui */ public class HalFormsBody { + private final T representation; private final Map linkByName; private final @Nullable String selfUri;