REST Expanders 3.0.0

Version 3 of the REST Expanders bundle brings quite a few new features and improvements! This post will cover an overview of what's new and provide a migration guide to assist in updating. The full release notes can be found here.

Resources

The expansion resources below provide REST Expanders 3.0.0.

Resource	Version
rest-expanders	3.0.0
rest-jaxrs-stack	3.0.0

Changes and improvements

Java 17

The REST Expanders have fully embraced Java 17! The expanders now require JRE 17 to run, as they now target Java 17 bytecode when building. Aside from the expanders, also the code they generate will now also require a Java 17 target. This means that you can expect Java 17 specific to start appearing in expanded applications!

Transmutations & Validations

With the introduction of model transmutations and validations validations, the REST Expanders now provide their own transmuters and validations to support the development process.

Transmutations

There are two transmutations available, which can provision a model with the required elements and option to expose a default JAX-RS REST API:

• On elements::Component, the transmutation CreateDefaultRestApi can be used to provision a Component and all of its DataElements a default API.

  mvn expanders:transmute-model -Dtransmutation=CreateDefaultRestApi -DtargetElement=componentName
• On elements::DataElement, the transmutation AddDefaultRestApi can be used to provision a single DataElement with a default API, given that its component has the option enableJaxrs.

  mvn expanders:transmute-model -Dtransmutation=AddDefaultRestApi -DtargetElement=componentName::dataElementName

The transmutations are also accessible in the context menus in the µRadiant and take into account modifications to the provisioned elements and options where possible.

Validations

There are 5 new model validations that check for common mistakes made when using the options for the REST Expanders. More will be added in the future, but these will already cover quite a few issues.

Migration guide

info

Use version 2022.4.1 (or newer) of the expanders-maven-plugin to avoid issues and have all benefits of the new model transmutations and model validations.

Java 17 target

Starting with version 3.0.0, the rest-expanders now require Java 17 to both expand and build applications. This means that aside from running the expansion with Java 17 in Maven, the applications should also target Java 17 in their technology infrastructure and be deployed on Java 17.

Shared libraries

Two shared libraries were introduced to house some duplicated expanded code that should not require any customization. To migrate code to use these moved classes (when relevant), it should suffice to rename the packages of the classes, as the classes themselves have not been renamed.

The classes were renamed as follows:

• SHARED_LAYER:
  • <componentName>.context.BaseUrlContext
net.democritus.jaxrs.context.BaseUrlContext
• CONTROL_LAYER:
  • <componentName>.exception.CorsForbiddenException
net.democritus.jaxrs.exception.CorsForbiddenException
  • <componentName>.exception.CreateFailedException
net.democritus.jaxrs.exception.CreateFailedException
  • <componentName>.exception.DeleteFailedException
net.democritus.jaxrs.exception.DeleteFailedException
  • <componentName>.exception.IllegalDBStateException
net.democritus.jaxrs.exception.IllegalDBStateException
  • <componentName>.exception.IllegalSortParametersFormatException
net.democritus.jaxrs.exception.IllegalSortParametersFormatException
  • <componentName>.exception.IllegalTimestampFormatException
net.democritus.jaxrs.exception.IllegalTimestampFormatException
  • <componentName>.exception.MalformedHeaderException
net.democritus.jaxrs.exception.MalformedHeaderException
  • <componentName>.exception.ModificationFailedException
net.democritus.jaxrs.exception.ModificationFailedException
  • <componentName>.exception.NotAuthorizedException
net.democritus.jaxrs.exception.NotAuthorizedException
  • <componentName>.exception.SearchResultException
net.democritus.jaxrs.exception.SearchResultException
  • <componentName>.exception.UnknownSortParameterException
net.democritus.jaxrs.exception.UnknownSortParameterException
  • <componentName>.jaxrs.JaxNsContext
net.democritus.jaxrs.context.JaxNsContext
  • <componentName>.jaxrs.MediaTypes
net.democritus.jaxrs.MediaTypes
  • <componentName>.jaxrs.provider.BaseUrlProvider
net.democritus.jaxrs.proxy.param.BaseUrlProvider
  • <componentName>.jaxrs.provider.param.DateParamConverter
net.democritus.jaxrs.provider.param.DateParamConverter
  • <componentName>.jaxrs.provider.param.DateParamProvider
net.democritus.jaxrs.provider.param.DateParamProvider
  • <componentName>.jaxrs.provider.param.SortParamConverter
net.democritus.jaxrs.provider.param.SortParamConverter
  • <componentName>.jaxrs.provider.param.SortParamProvider
net.democritus.jaxrs.provider.param.SortParamProvider
  • <componentName>.jaxrs.sorting.SortOrder
net.democritus.jaxrs.sorting.SortOrder
  • <componentName>.jaxrs.sorting.SortParameters
net.democritus.jaxrs.sorting.SortParameters

Proxy headers

The rest-expanders have for a long time been provided with its own processing functionality for proxy headers, as part of the BaseUrlProvider class. Previously, this simply overlayed all proxy headers over each other, with the standardized Forwarded header being processed first and then being overlayed with the non-standard X-Forwarded headers. This behavior has been altered, so the standardized Forwarded header is used if present and if not, the non-standard X-Forwarded headers are used instead.

JSON dependencies moved

The dependencies json and everit-json-schema have been moved from the SHARED layer to CONTROL and LOGIC. In theory, in function of the JAX-RS API, this technology should not be present in the SHARED layer, so all custom code in the SHARED layer that uses them, should be moved to the appropriate layers.

Jetbrains Annotations removed

The annotations library from Jetbrains was removed from expanded code. The annotations provided by it are mostly to provide context information for IDEs. All annotations except for @NotNull and @Nullable have been removed, as they are quite useful. For quite some time, alternatives for these annotations (with the same name) have been provided by the nsx-contract-annotations library, which is part of nsx-runtime. The NSX Support Plugin for IntelliJ automatically registers these annotations as alternatives in IntelliJ, so they provide the same functionality.

A transient option legacy.annotations.reenable (expires on 2023-04-07) has been added to re-enable the annotations library from Jetbrains. To migrate to the new approach, remove all annotations (@Nls, @Contract, ...) other than @NotNull and @Nullable. For the two remaining, change the imports:

• org.jetbrains.annotations.NotNull
net.democritus.contract.NotNull
• org.jetbrains.annotations.Nullable
net.democritus.contract.Nullable

Alternatively, if you wish to keep using the Jetbrains annotations library, add it to the application project in custom code.