Package com.toedter.spring.hateoas.jsonapi

Class JsonApiConfiguration

java.lang.Object
com.toedter.spring.hateoas.jsonapi.JsonApiConfiguration
public class JsonApiConfiguration extends Object
JSON:API specific configuration.

  • Constructor Details

  • Method Details

    • customize

      public tools.jackson.databind.json.JsonMapper.Builder customize(tools.jackson.databind.json.JsonMapper.Builder builder)
      Customizes the given JsonMapper.Builder with the registered callback.
      Parameters:
      builder - must not be null.
      Returns:
      will never be null.

    • getJsonMapper

      public tools.jackson.databind.json.JsonMapper getJsonMapper()
      Returns a configured JsonMapper instance.

      This method creates a new JsonMapper with the customizations applied through the mapperCustomizer.

      Returns:
      A configured JsonMapper instance.

    • withTypeForClass

      public JsonApiConfiguration withTypeForClass(Class<?> clazz, String type)
      Creates a mapping for a given class to get the JSON:API resource object type when rendered.
      Parameters:
      clazz - must not be null.
      type - must not be null.
      Returns:
      a clone of this object, except with this updated property

    • getTypeForClass

      @Nullable public String getTypeForClass(Class<?> clazz)
      Returns the JSON:API resource object type for a given class, when it was added with withTypeForClass(Class, String).
      Parameters:
      clazz - must not be null.
      Returns:
      can return null.

    • getClassForType

      @Nullable public Class<?> getClassForType(String type)
      Returns the class for a given type, when the class was added with withTypeForClass(Class, String).
      Parameters:
      type - must not be null.
      Returns:
      can return null.

    • withPluralizedTypeRendered

      public JsonApiConfiguration withPluralizedTypeRendered(boolean pluralizedTypeRendered)
      Indicates if the JSON:API type attribute of resource objects is pluralized.
      Parameters:
      pluralizedTypeRendered - The new value of this configuration's pluralizedTypeRendered
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • isPluralizedTypeRendered

      public boolean isPluralizedTypeRendered()
      Indicates if the JSON:API type attribute of resource objects is pluralized.
      Returns:
      The default is true.

    • withLowerCasedTypeRendered

      public JsonApiConfiguration withLowerCasedTypeRendered(boolean lowerCasedTypeRendered)
      Indicates if the JSON:API type attribute of resource objects is lower-cased.
      Parameters:
      lowerCasedTypeRendered - The new value of this configuration's lowerCasedTypeRendered
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • isLowerCasedTypeRendered

      public boolean isLowerCasedTypeRendered()
      Indicates if the JSON:API type attribute of resource objects is lower-cased.
      Returns:
      The default is true.

    • withJsonApiObject

      public JsonApiConfiguration withJsonApiObject(JsonApiObject jsonApiObject)
      Indicates if the JSON:API object is rendered.

      If set, each rendered JSON:API document will start with a JSON:API object like 

       {
   "jsonapi": {
     "version": "1.1",
     "ext": [
       "https://jsonapi.org/ext/atomic"
     ],
     "profile": [
       "http://example.com/profiles/flexible-pagination",
       "http://example.com/profiles/resource-versioning"
     ]
   }
 }
      See also JSON:API Object.
      Parameters:
      jsonApiObject - The new value of this configuration's jsonApiObject
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • getJsonApiObject

      public JsonApiObject getJsonApiObject()
      Indicates if the JSON:API object is rendered.

      If set, each rendered JSON:API document will start with a JSON:API object like 

       {
   "jsonapi": {
     "version": "1.1",
     "ext": [
       "https://jsonapi.org/ext/atomic"
     ],
     "profile": [
       "http://example.com/profiles/flexible-pagination",
       "http://example.com/profiles/resource-versioning"
     ]
   }
 }
      See also JSON:API Object.
      Returns:
      The default is false.

    • withPageMetaAutomaticallyCreated

      public JsonApiConfiguration withPageMetaAutomaticallyCreated(boolean pageMetaAutomaticallyCreated)
      Indicates if page metadata (rendered as top level JSON:API meta) for a paged model is created automatically.
      Parameters:
      pageMetaAutomaticallyCreated - The new value of this configuration's pageMetaAutomaticallyCreated
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • isPageMetaAutomaticallyCreated

      public boolean isPageMetaAutomaticallyCreated()
      Indicates if page metadata (rendered as top level JSON:API meta) for a paged model is created automatically.
      Returns:
      The default is true.

    • withTypeForClassUsedForDeserialization

      public JsonApiConfiguration withTypeForClassUsedForDeserialization(boolean typeForClassUsedForDeserialization)
      Indicates if the Java class to JSON:API mapping created with JsonApiConfiguration is also used during deserialization.
      Parameters:
      typeForClassUsedForDeserialization - The new value of this configuration's typeForClassUsedForDeserialization
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • isTypeForClassUsedForDeserialization

      public boolean isTypeForClassUsedForDeserialization()
      Indicates if the Java class to JSON:API mapping created with JsonApiConfiguration is also used during deserialization.
      Returns:
      The default is false.

    • withAffordancesRenderedAsLinkMeta

      public JsonApiConfiguration withAffordancesRenderedAsLinkMeta(JsonApiConfiguration.AffordanceType affordancesRenderedAsLinkMeta)
      Indicates if Spring HATEOAS affordances are rendered as JSON:API link meta. This feature is experimental, please don't use it in production yet. The format of the affordances will probably change. Currently, only a proprietary format (SPRING_HATEOAS) derived from the internal affordance model and HAL-FORMS _templates are supported.
      Parameters:
      affordancesRenderedAsLinkMeta - The new value of this configuration's affordancesRenderedAsLinkMeta
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • getAffordancesRenderedAsLinkMeta

      public JsonApiConfiguration.AffordanceType getAffordancesRenderedAsLinkMeta()
      Indicates if Spring HATEOAS affordances are rendered as JSON:API link meta. This feature is experimental, please don't use it in production yet. The format of the affordances will probably change. Currently, only a proprietary format (SPRING_HATEOAS) derived from the internal affordance model and HAL-FORMS _templates are supported.
      Returns:
      The list of JsonApiConfiguration.AffordanceType. The default is NONE, so no affordances will be rendered.

    • withEmptyAttributesObjectSerialized

      public JsonApiConfiguration withEmptyAttributesObjectSerialized(boolean emptyAttributesObjectSerialized)
      Indicates if empty attributes are serialized as empty object.

      If set to true, empty attributes are serialized as 

       {
   "data": {
      "id": "1",
      "type": "movies",
      "attributes": {
      }
   }
 }

      If set to false, attributes are not serialized, 

       {
   "data": {
      "id": "1",
      "type": "movies"
   }
 }
      Parameters:
      emptyAttributesObjectSerialized - The new value of this configuration's emptyAttributesObjectSerialized
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • isEmptyAttributesObjectSerialized

      public boolean isEmptyAttributesObjectSerialized()
      Indicates if empty attributes are serialized as empty object.

      If set to true, empty attributes are serialized as 

       {
   "data": {
      "id": "1",
      "type": "movies",
      "attributes": {
      }
   }
 }

      If set to false, attributes are not serialized, 

       {
   "data": {
      "id": "1",
      "type": "movies"
   }
 }
      Returns:
      The default is true.

    • withJsonApiIdNotSerializedForValue

      public JsonApiConfiguration withJsonApiIdNotSerializedForValue(String jsonApiIdNotSerializedForValue)
      If you want to create JSON for a POST request that does not contain the id attribute. For example, if you set this property to "doNotSerialize" and initialize a Movie object with id = "doNotSerialize", the serialized JSON would look like 
       {
   "data": {
      "type": "movies",
      "attributes": {
         "title": "Star Wars"
       }
    }
 }
      Parameters:
      jsonApiIdNotSerializedForValue - The value of the JSON:API resource id that is ignored for serialization
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • getJsonApiIdNotSerializedForValue

      public String getJsonApiIdNotSerializedForValue()
      If you want to create JSON for a POST request that does not contain the id attribute. For example, if you set this property to "doNotSerialize" and initialize a Movie object with id = "doNotSerialize", the serialized JSON would look like 
       {
   "data": {
      "type": "movies",
      "attributes": {
         "title": "Star Wars"
       }
    }
 }
      Returns:
      The default is null.

    • withMapperCustomizer

      public JsonApiConfiguration withMapperCustomizer(UnaryOperator<tools.jackson.databind.json.JsonMapper.Builder> mapperCustomizer)
      A customizer function that allows modification of the JsonMapper.Builder used for JSON:API serialization and deserialization.

      This customizer is applied when calling customize(JsonMapper.Builder) and allows you to configure additional Jackson features, modules, or settings that are not directly exposed through this configuration class.

      Example usage: 

       JsonApiConfiguration config = new JsonApiConfiguration()
     .withMapperCustomizer(builder -> builder
         .enable(SerializationFeature.INDENT_OUTPUT)
         .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES));
      Parameters:
      mapperCustomizer - A unary operator that takes a JsonMapper.Builder and returns a modified JsonMapper.Builder. If null, no customization is applied.
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • withJsonApi11LinkPropertiesRemovedFromLinkMeta

      public JsonApiConfiguration withJsonApi11LinkPropertiesRemovedFromLinkMeta(boolean jsonApi11LinkPropertiesRemovedFromLinkMeta)
      JSON:API 1.1 introduced the possible link properties title, type, and hreflang (and some more), see JSON:API link objects. Since title, type and hreflang exist also in the Spring HATEOAS link model, for JSON:API 1.1 they are now serialized as direct link properties. For the previous version JSON:API v1.0 they were serialized in the meta section.

      The removal from the meta section is a breaking change that could harm existing clients. But to keep the format backward-compatible to previous versions of this JSON:API for Spring HATEOASrary, title, type, and hreflang can still be rendered also in the link's meta section. For backward-compatible behavior, set this configuration to false.

      Parameters:
      jsonApi11LinkPropertiesRemovedFromLinkMeta - The new value of this configuration's jsonApi11LinkPropertiesRemovedFromLinkMeta
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • isJsonApi11LinkPropertiesRemovedFromLinkMeta

      public boolean isJsonApi11LinkPropertiesRemovedFromLinkMeta()
      JSON:API 1.1 introduced the possible link properties title, type, and hreflang (and some more), see JSON:API link objects. Since title, type and hreflang exist also in the Spring HATEOAS link model, for JSON:API 1.1 they are now serialized as direct link properties. For the previous version JSON:API v1.0 they were serialized in the meta section.

      The removal from the meta section is a breaking change that could harm existing clients. But to keep the format backward-compatible to previous versions of this JSON:API for Spring HATEOASrary, title, type, and hreflang can still be rendered also in the link's meta section. For backward-compatible behavior, set this configuration to false.

      Returns:
      The default is true.

    • withJsonApiCompliantLinks

      public JsonApiConfiguration withJsonApiCompliantLinks(boolean jsonApiCompliantLinks)
      JSON:API is very strict about the allowed link relations, the allowed top-level links are self, related, describedBy, next, pre, first and last. The only allowed resource link is self.

      If you set this configuration to false, Spring HATEOAS links that are not compliant with JSON:API would also be serialized.

      Parameters:
      jsonApiCompliantLinks - The new value of this configuration's jsonApiCompliantLinks
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • isJsonApiCompliantLinks

      public boolean isJsonApiCompliantLinks()
      JSON:API is very strict about the allowed link relations, the allowed top-level links are self, related, describedBy, next, pre, first and last. The only allowed resource link is self.

      If you set this configuration to false, Spring HATEOAS links that are not compliant with JSON:API would also be serialized.

      Returns:
      The default is true.

    • withLinksNotUrlEncoded

      public JsonApiConfiguration withLinksNotUrlEncoded(Set<org.springframework.hateoas.LinkRelation> linksNotUrlEncoded)
      By default, JSON:API links are serialized as URL encoded.

      If you set this configuration, Spring HATEOAS links with set relations won't be URL encoded. This can be useful for instance to avoid double uri encoding when you pass the links to the model already URL encoded.

      Parameters:
      linksNotUrlEncoded - The new value of this configuration's linksNotUrlEncoded
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • getLinksNotUrlEncoded

      public Set<org.springframework.hateoas.LinkRelation> getLinksNotUrlEncoded()
      By default, JSON:API links are serialized as URL encoded.

      If you set this configuration, Spring HATEOAS links with set relations won't be URL encoded. This can be useful for instance to avoid double uri encoding when you pass the links to the model already URL encoded.

      Returns:
      The default is an empty set.

    • withLinksAtResourceLevel

      public JsonApiConfiguration withLinksAtResourceLevel(boolean linksAtResourceLevel)
      Controls where links are placed in JSON:API documents for single resource (EntityModel) serialization.

      According to the JSON:API specification, links can be placed at:

      • Document level (top-level) - the default behavior
      • Resource level (within the resource object in the "data" section)

      When set to true, links from EntityModel are placed at the resource level (inside the resource object). When set to false, links are placed at the document level (top-level).

      Note: This configuration only affects single resource serialization (EntityModel). Collection resources and relationships are not affected by this setting.

      Parameters:
      linksAtResourceLevel - The new value of this configuration's linksAtResourceLevel
      Returns:
      a clone of this object, except with this updated property (returns this if an identical value is passed).

    • isLinksAtResourceLevel

      public boolean isLinksAtResourceLevel()
      Controls where links are placed in JSON:API documents for single resource (EntityModel) serialization.

      According to the JSON:API specification, links can be placed at:

      • Document level (top-level) - the default behavior
      • Resource level (within the resource object in the "data" section)

      When set to true, links from EntityModel are placed at the resource level (inside the resource object). When set to false, links are placed at the document level (top-level).

      Note: This configuration only affects single resource serialization (EntityModel). Collection resources and relationships are not affected by this setting.

      Returns:
      The default is false (links at document level).