32 posts tagged with "migration-guide"

This release of Expanders is the final push to remove all uses of net.palver.util.Options.Option in our JEE stack.

Resources​

The expansion resources below provide Expanders 5.30.0.

Changes and improvements​

Fully deprecating Options.Option​

This last refactoring of Options.Option to Optional in the application stack required reworking code across several projects. Extensive changes were made to nsx-runtime, Expanders, base-components and alerting-component. We did manage however to reduce the impact of the changes to a minimum, so most projects will experience little impact from the migration.

We did choose to introduce a hard breaking change in one location, namely the getProperty() method of the expanded <component>ApplicationSettings class when the option configuration.properties is added to a component. The use of this option is still fairly limited at this time, so it seemed better to go for some minor refactoring in those projects that use it, than to add a new method like we did in Context and SearchResult.

The Options.Option class itself will still be available for quite some time, so projects can migrate to Optional on their own time, but we do intend to remove it in the future.

This release of Expanders is mostly focused around changes related to Struts2, amongst which the removal of all support for versions 2.3.x and 2.5.x, as well as the update to version 6.2.0.

Resources​

The expansion resources below provide Expanders 5.29.0.

Changes and improvements​

Removal of old version support​

We have been working towards removing support for outdated versions of Struts2 for some time now. On July 1st, the deprecated option struts.version expired. We've now removed all support that relied on this option to target Struts 2.3 and 2.5. This was announced last year with the release of Expanders 5.15.0.

Struts 6.2​

Struts version 6.2 was released yesterday as announced by Apache. This version brings mostly bugfixes and some improvements, but it also comes with some breaking changes. There's no official migration guide for this, but we've described some of these changes and the fixes in our migration guide below. Most of these changes will however be handled by our expanders, so the impact on projects should be fairly minimal.

Refactoring​

With the refactoring needed for the new Struts update, we've also taken the time to revisit some of the code in our JEE stack related to Struts and made some minor improvements. This includes replacing remaining code that still pulled the UserContext object directly from the session with Context. Though UserContext remains part of the session for now, this might change in the future

Efforts to reimagine and improve the way workflows are modeled and implemented within our applications have started a while ago. This release marks the first impact of those efforts on Expanders.

Resources​

The expansion resources below provide Expanders 5.28.0.

Changes and improvements​

Task perform and delegation​

Modeling your application should be as simple as possible. This includes providing developers with sensible defaults. Best practices shouln't be hidden behind an option. For this reason the following options have become deprecated and are now the default behavior:

• includePerform Every task should be able to be performed. The expanded perform method has the advantage that its contract aligns with the TaskElement model.
• includeDelegation In the JEE application stack a task is accessed as an EJB. Delegation allows us to implement the task independently of this technology. It will also improve the ability to test this implementation. To opt-out of delegate implementation(s) you can use the new noDelegation option.

Additionally, adding the includeRemoteAccess option is no longer recommended. This option exposes a task directly to a Struts api, which doesn't have the best interface and implementation.

Non-dynamic task implementation​

Available task implementations must be known at compile-time, which is why we replaced the dynamic lookup using Class.forName(..) with a switch-statement. This explicitly lists all available implementations and allows for better code navigation.

Multiple task implementations for the same task are infrequently used. However, when applicable it should at least be clear what each implementation does. For this reason we chose to retire the <Task>Impl2.java artifact, custom implementations with meaningful names should be used instead.

Additionally, getting rid of the dynamic lookup allows us to use named implementations instead of fully qualified class names as well. You could for example have a task implemented with and without encryption of some data. These implementations can now be named default and secure, which would then resolve to their respective implementation. Since the implementation name is just a string, you can still use fully qualified names as well.

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.