Package de.kamillionlabs.hateoflux.model.hal

Klasse HalResourceWrapper<ResourceT,EmbeddedT>

java.lang.Object
de.kamillionlabs.hateoflux.model.hal.HalWrapper<HalResourceWrapper<ResourceT,EmbeddedT>>
de.kamillionlabs.hateoflux.model.hal.HalResourceWrapper<ResourceT,EmbeddedT>
Typparameter:
ResourceT - the type of the object being wrapped, which contains the main data
EmbeddedT - the type of the object representing additional embedded resources related to the main data, if any
public final class HalResourceWrapper<ResourceT,EmbeddedT> extends HalWrapper<HalResourceWrapper<ResourceT,EmbeddedT>>
Represents an immutable wrapper class for adding hypermedia links to any arbitrary resource object and, optionally, incorporating embedded resources, adhering to HAL standards.

The HalResourceWrapper is a final class and not intended for extension. It encapsulates an instance of ResourceT, representing the primary or main resource, and can optionally include an instance of EmbeddedT for additional embedded resources related to said main resource. This wrapper ensures that when serialized, the fields of the resource object are presented at the top level.

Usage of this class involves creating an instance with the resource and, if necessary, embedded resources. Links can then be added to enrich the resource model with HAL's hypermedia-driven format. During serialization, this wrapper directly integrates the resource and any embedded resources into the enclosing structure.

  • Methodendetails

    • wrap

      public static <ResourceT> HalResourceWrapper<ResourceT,Void> wrap(@NonNull ResourceT resource)
      Wraps any given resource into a HalResourceWrapper to make it conform to HAL standards.

      For wrapping a list of resources, use HalListWrapper instead.

      The embedded resource is optional. Initially the type of the embedded is set to Void as "being non-existing". The embedded is then not accessible. If embedding is desirable, methods such as withEmbeddedResource(HalEmbeddedWrapper) or other appropriate withEmbeddedXYZ() methods can be utilized.

      Typparameter:
      ResourceT - the type of the resource to be wrapped
      Parameter:
      resource - the object to wrap
      Gibt zurück:
      a new instance containing the wrapped resource

    • withEmbeddedResource

      public <NewEmbeddedT> HalResourceWrapper<ResourceT,NewEmbeddedT> withEmbeddedResource(HalEmbeddedWrapper<NewEmbeddedT> embedded)
      Adds an embedded resource i.e. object to the HalResourceWrapper. The relation name for the embedded resource is determined by the Relation annotation on the resource's class, if present, or by their class name otherwise.

      Only one embedded element can be held at a time. If multiple objects need to be embedded, use withNonEmptyEmbeddedList(List), withEmbeddedList(String, List), or withEmbeddedList(Class, List).

      Calling any withEmbeddedXYZ() method multiple times results in overriding the previously embedded resource each time.

      Hint: Call this method with an empty embedded (HalEmbeddedWrapper.empty()) if the embedded type is desired to be changed from Void.

      Typparameter:
      NewEmbeddedT - the type of the resource to embed
      Parameter:
      embedded - the resource to embed (may be empty, but not null)
      Gibt zurück:
      new instance with the embedded resource
      Löst aus:
      IllegalArgumentException - if the resource is null

    • withNonEmptyEmbeddedList

      public <NewEmbeddedT> HalResourceWrapper<ResourceT,NewEmbeddedT> withNonEmptyEmbeddedList(@NonNull List<HalEmbeddedWrapper<NewEmbeddedT>> resourcesToEmbed)
      Adds an embedded list of type NewEmbeddedT to the HalResourceWrapper. The relation name for the embedded list is determined by the Relation annotation on the list's items, if present, or by their class name otherwise.

      Due to type erasure with Java generics, retrieving the class name of elements in an empty list is not feasible because no type information is retained at runtime. Therefore, the list must be initialized and not empty.

      Calling any withEmbeddedXYZ() method multiple times results in overriding the previously embedded resource each time.

      Typparameter:
      NewEmbeddedT - the type of the items in the list to embed
      Parameter:
      resourcesToEmbed - the list to be embedded
      Gibt zurück:
      new instance with the embedded list
      Löst aus:
      IllegalArgumentException - if the list is null or empty

    • withEmbeddedList

      public <NewEmbeddedT> HalResourceWrapper<ResourceT,NewEmbeddedT> withEmbeddedList(@NonNull String embeddedListName, List<HalEmbeddedWrapper<NewEmbeddedT>> resourcesToEmbed)
      Adds an embedded list to the HalResourceWrapper. The list is allowed to be empty. The relation name for the list is specified by embeddedListName.

      Calling any withEmbeddedXYZ() method multiple times results in overriding the previously embedded resource each time.

      Typparameter:
      NewEmbeddedT - the type of the items in the list to embed
      Parameter:
      embeddedListName - Non-null and non-empty name or relation for the embedded list
      resourcesToEmbed - Non-null list to be embedded
      Gibt zurück:
      new instance with the embedded list
      Löst aus:
      IllegalArgumentException - if resourcesToEmbed is null or if the embeddedListName is null or empty

    • withEmbeddedList

      public <NewEmbeddedT> HalResourceWrapper<ResourceT,NewEmbeddedT> withEmbeddedList(@NonNull Class<NewEmbeddedT> embeddedTypeAsNameOrigin, List<HalEmbeddedWrapper<NewEmbeddedT>> resourcesToEmbed)
      Adds an embedded list to the HalResourceWrapper. The list is allowed to be empty. The relation name for the list is determined by embeddedTypeAsNameOrigin. If the passed class is annotated with Relation, the name is taken from the annotation; otherwise, it is derived from the class name.

      Calling any withEmbeddedXYZ() method multiple times results in overriding the previously embedded resource each time.

      Typparameter:
      NewEmbeddedT - the type of the items in the list to embed
      Parameter:
      embeddedTypeAsNameOrigin - the class type used to derive the name or relation for the embedded list. This parameter must be non-null.
      resourcesToEmbed - the list to be embedded
      Gibt zurück:
      a new instance with the embedded list
      Löst aus:
      IllegalArgumentException - if embeddedTypeAsNameOrigin is null

    • getEmbedded

      public Optional<List<HalEmbeddedWrapper<EmbeddedT>>> getEmbedded()
      Returns the embedded resource(s). The embedded resource is stored in form of a list and thus will return a list even if a single resource was embedded.
      Gibt zurück:
      List with embedded resources

    • getNameOfEmbedded

      public Optional<String> getNameOfEmbedded()
      Returns the name of the embedded resource or list of resources.
      Gibt zurück:
      Name of the embedded resource

    • hasEmbedded

      public boolean hasEmbedded()
      Indicates whether the HalResourceWrapper has an embedded resource
      Gibt zurück:
      true if an embedded resource exists; false otherwise

    • getRequiredEmbedded

      public List<HalEmbeddedWrapper<EmbeddedT>> getRequiredEmbedded()
      Returns the embedded resource(s). The embedded resource is stored in form of a list and thus will return a list even if a single resource was embedded.

      In contrast to getEmbedded(), it is assumed, that the embedded resource(s) exist, otherwise an exception is thrown.

      Gibt zurück:
      List with embedded resources
      Löst aus:
      IllegalArgumentException - if no embedded resource(s) exist

    • getRequiredNameOfEmbedded

      public String getRequiredNameOfEmbedded()
      Returns the name of the embedded resource or list of resources.

      In contrast to getNameOfEmbedded(), it is assumed, that the embedded resource(s) exist, otherwise an exception is thrown.

      Gibt zurück:
      Name of the embedded resource
      Löst aus:
      IllegalArgumentException - if no embedded resource(s) exist