39 posts tagged with "migration-guide"

Changes and improvements​

Refactoring Options.Option​

As net.democritus.sys.Options.Option is being phased out, this version of rest-expanders replaced the vast majority of its uses with java.util.Optional. All of these changes are located in the validation system and may affect custom code.

Changes and Improvements​

Both Model Validations and Model Transmutations have been refactored to make configuration easier.

The annotation processors are now defined in the validations-core and modelTransmutations-core jars and no longer need to be explicitly added to your maven builds.

<plugins>
  <plugin>
    <groupId>net.democritus.maven.plugins</groupId>
    <artifactId>expanders-maven-plugin</artifactId>
    <version>${expanders-maven-plugin.version}</version>
    <executions>
      <execution>
        <goals>
          <goal>expansionResource</goal>
        </goals>
        <configuration>
          <includeClassPathDependencies>true</includeClassPathDependencies>
        </configuration>
      </execution>
    </executions>
  </plugin>
  <!-- Remove this -->
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.10.0</version>
    <configuration>
      <showWarnings>true</showWarnings>
      <annotationProcessors>
        <annotationProcessor>
          net.democritus.transmutations.compilation.TransmutationAnnotationProcessor
        </annotationProcessor>
      </annotationProcessors>
    </configuration>
  </plugin>
  ...
</plugins>

Furthermore, the generated DataResources are generated in the new format.

Migration​

Update your expanders-maven-plugin to 2023.3.1 or higher:

<expanders-maven-plugin.version>2023.3.1</expanders-maven-plugin.version>

Next, remove the DataResource reference in your _data.xml file:

<dataResources>
  ...
  <!-- Remove these -->
  <dataResource>
    <path>data/transmutations/modelTransmutations.xml</path>
    <elementTypeCanonicalName>net.democritus.transmutations.ModelTransmutation</elementTypeCanonicalName>
  </dataResource>
  <dataResource>
    <path>data/validations/validationGroups.xml</path>
    <elementTypeCanonicalName>net.democritus.validations.ValidationGroup</elementTypeCanonicalName>
  </dataResource>
</dataResources>

Changes and Improvements​

The plugin has been refactored to support an easier way to register data-resources with the expansionResource goal.

With the latest version, you can create an XML file with dataResource as root tag and a type attribute:

<dataResource type="elements::Technology">
  <technology name="HSQLDB">
    <subdir>hsql</subdir>
    <concernType name="DATABASE"/>
    <description>-</description>
  </technology>
  <technology name="MARIADB">
    <subdir>mariadb</subdir>
    <concernType name="DATABASE"/>
    <description>MariaDB Database</description>
  </technology>
  <technology name="POSTGRESQL">
    <subdir>postgresql</subdir>
    <concernType name="DATABASE"/>
    <description>PostgreSQL Database</description>
  </technology>
</dataResource>

The file should still be placed in a resources directory or another directory that is included in the build. The expansionResource mojo will scan through the target/classes directory to find these files and register them. Because of this change, we no longer need a _data.xml file to describe the locations of the data-resources.

Changes and improvements​

Legacy constraint methods​

The when(boolean, QueryConstraint) and whenOrElse(boolean, QueryConstraint) methods have been removed after being marked as deprecated for three years. These methods were fundamentally flawed as the constraints are passed as a parameter adn as such evaluated immediately, instead of only when the condition is true as per the design of these constraints.

The exists(qualifiedElementName, variableName, constraint, queryOptions) constraint method has now been marked as deprecated. This method was superseded by a new exists() method in version 1.7.0, which takes a QueryBuilder instance as an argument. Using the QueryBuilder instance if more version transparent and more readable.

Meta-model​

The QuerySearchOptionType element has been removed in favor of using the new ValueType system introduced in the elements metamodel. This change aligns the querySearch metamodel more with the elements model which it extend and will allow for more flexibility as the metamodel is refined further. This change was also planned for quite a long time ago and the reason the model was still considered unstable. With this change now implemented, the querySearch metamodel can now be considered to be stable and will no longer be subjected to large breaking changes in the future.

Changes and improvements​

OpenApi 3.0 support​

In this version of rest-expanders, we've introduced support for OpenAPI 3.0. Previously we only supported OpenAPI 2.0, which was Swagger originally. Due to some technical challenges, we were not able to support OpenAPI 3.0 up to this point. Now that these hurdles have been cleared, we've finished the implementation and made it the new default.

The new version of the specification is also integrated with a Swagger UI front-end as was the case with the previous specification. This version does rely on a new major version of the Swagger library, which brings many breaking changes. As a regular, custom code will be heavily impacted by this change. We do provide a model option to switch back to OpenAPI 2.

More information about updating can be found in the migration guide.

SecurityRight annotation​

The SecurityRight annotation is used to define rights for an endpoint. Previously these would only be added to expanded endpoints when use of account::DataAccess was enabled. This made it difficult to add more functionality to the annotation. Now this annotation is added to all expanded endpoints and anchors are available in the annotation to add additional property values.

Changes and improvements​

UniqueConstraints​

This version of rest-expanders introduces initial support for the new UniqueConstraints added to the elements model. Though at this time the isUnique option will not yet be replaced by these constraints, if they are added to the model and fail validation, they will be correctly mapped to unique constraint validation errors in the REST API.

Known issues​

• This release breaks the DiagnosticInterceptor interface. This can affect implementations of the class in custom code that override the intercept(Diagnostic) method that was removed. Version 3.8.0 has a fix for backwards compatibility, though refactoring the custom class would be the preferred solution.

Migration guide​

This version of the expanders provides an update of Swagger UI from 3.52.5 to 4.15.5. One notable change is that all inline JavaScript and CSS styling was moved from the main swagger-ui.html file into separate files swagger-initializer.js and index.css. The CSS file has simply been added as css/swagger-ui-index.css. The inline JavaScript code did however contain several anchors. These anchors have been moved from their original location in html/<componentName>-swagger.html to js/<componentName>-swagger-initializer.js. This pertains to the following anchors:

• @before-setup and custom-before-setup
• @config and custom-config
• @after-setup and custom-after-setup

As all of these anchors were placed in inline javascript code, it should be sufficient move the harvest file from html/<componentName>-swagger.html.harvest to js/<componentName>-swagger-initializer.js.harvest.

Of course any expanders that may target these anchors will also have to be updated to inject features into the new file.

Version 5.15.0 of the Expanders 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 Expanders 5.15.0.

Changes and improvements​

Changes in GlobalOptionSettings​

Several of the settings in GlobalOptionSettings have been replaced with options on the ApplicationInstance. The long-term goal is to make the GlobalOptionSettings, TechnicalInfrastructure, PresentationSettings and BusinessLogicSettings obsolete.

BeanInterfacePolicy​

The beanInterfacePolicy setting could either be BOTH, LOCAL or REMOTE and controls which interfaces are present on the bean. However, in practice, only the LOCAL and BOTH settings were functional. The option ejb.interfaces.localOnly replaces beanInterfacePolicy='LOCAL', while beanInterfacePolicy='BOTH' becomes the default.

Security Options​

The following flags have been migrated to options:

• enforceHttpMethod: replaced by option struts.security.enforceHttpMethod (Prevents requests to struts control layer from using the wrong HTTP Method.)
• useCsrfProtection: replaced by option struts.security.csrfProtection (Adds a security mechanism to protect against CSRF attacks.)
• useJavaEESecurity: replaced by option struts.security.custom, or simply remove account Component from the Application. (Removes login mechanism from the struts-header.xml file.)

GenerateArtifactLabel​

This feature added a postfix to the versions of Component artifacts in the project. This allows you to install artifacts or deploy them to the nexus so speed up subsequent maven builds by using e.g. the -Pslim profile.

The flag has been replaced by the option mvn.version.appendUniqueLabel. It also now appends the applicationInstance shortname and expanders version, instead of the names of the settings objects. This change is necessary if we want to move away from the settings elements.

CounterDefault​

The counterDefault settings on GlobalOptionSettings used to support a GLOBAL value. This would cause all of the id's to be set programmatically based on a single table.

This has been removed as there are better alternatives (see below).

Identity generation strategy for JPA​

The options persistence.identifier, persistence.sequence.name and persistence.sequence.schema have been renamed from options previously marked as experimental. These options allow a specific identity generation strategy to be selected for a DataElement. The options are available at any level of the model above DataElement and cascaded down. They can be overridden on a lower level for granular control if needed.

The options support either auto-incremented identity columns or native sequences.

For more information, visit the documentation about id generation.

Struts2 6.0​

Support for Struts2 6.0.3 was added to the expanders and is now the default version. From this version and onward, the expanders will start supporting a specific contemporary release version of Struts to improve the distribution of security patches.

There are some breaking changes both in how we handle Struts and the framework itself. See the migration guide for more information.

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.

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.

Removed generated PATCH annotation​

To annotate PATCH methods in the REST API, the expanders used the io.swagger.jaxrs.PATCH annotation, which is part of the Swagger library. The reason for using this, is that the JAX-RS libraries did not include this by default, since PATCH was a later addition to the HTTP standard.

Using this annotation caused an issue, as it is part of the Swagger libraries, creating an unwanted coupling, as well as an issue when the enableSwagger option was not used. To resolve this, a new expanded annotation was added as <componentName>.jaxrs.method.PATCH, which is referenced when the option enableSwagger is not used.

Recent versions of JAX-RS now include the annotation javax.ws.rs.PATCH, just like the annotations for other default HTTP methods. Therefor all dependencies on both the Swagger PATCH annotation, as well as the generated one have been replaced. As this deprecates the generated annotation, this has also been removed from the expanders.

To update custom code that uses either annotation, simply replace the import with javax.ws.rs.PATCH.