37 posts tagged with "migration-guide"

This version of the expanders updates the groupId of all Maven modules in the expanded application project, to be more consistent and configurable.

Resources​

The expansion resources below provide Expanders 5.35.1.

Changes and improvements​

Maven groupIds​

In the past, all modules in the application project had the groupId org.normalizedsystems, except for the ear file module, which was org.normalized. To finally bring some consistency into this and differentiate them from those in other applications (to avoid collisions between base-component artifacts), this has now been changed.

The new groupId is now uniform across the entire project and is specifically org.normalizedsystems with the application shortname added after it in lowercase. So for shortname testApp it is org.normalizedsystems.testapp.

These new groupIds are merely the default settings though, it can now be configured with the application option maven.groupId, for which the value will be used as the groupId instead.

PascalCase for expander templating​

We've now added PascalCase as a format for all engines in the expander framework, the same way it is available for other formats.

We have been hard at work on the process automation component, which supersedes the workflow component.

Resources​

Workflow model​

The first step is moving away from database config into the model. The workflow model allows you to define all workflows statically. It also provides bindings for the workflow component such that it automatically updates the database configuration when changes are made to the model. Having the information in the model also gives the MicroRadiant the ability to visualize your workflows.

We also provide a tool for importing existing database configuration into the model.

Process automation component​

A preview release is now available for the new process automation component!

The component is a new approach to workflows, designed with more flexibility in mind. The key distinction is queue based processing, where the previous component could only handle timed polling. This means we can now start supporting a wide range of triggers, such as CRUD events, transitions, cron schedules and even the flow engines you're already familiar with.

Migration​

Migration can be quite involved depending on the current state of your application. To ease the difficulty, we provide a migration guide with smaller steps so applications can incrementally adopt the new component.

It is recommended for all applications to at least perform Step 1 (workflow model) and Step 2 (task outcome model). This will already give some advantages like model-based configuration and makes it easier to adopt process automation on a stable release.

This version of the expanders introduces improved support for imports in Expanders.

Resources​

The expansion resources below provide Expanders 5.33.2.

Changes and improvements​

Better support of Imports in mapping files​

The mapping file syntax has been extended with 2 new keywords: artifact and uses.

Mapping files often had a separate list statement to resolve imports:

<mapping xmlns="https://schemas.normalizedsystems.org/xsd/expanders/2023/0/0/mapping">
  <list name="valueTypes"
        eval="finder.fieldOperatorPairs.{ field }.{? valueField neq null }.{ javaType }"
        param="javaType" unique="javaType">
    <filter name="requiresImport" eval="javaType.requiresImport()"/>
    <value name="qualifiedType" eval="javaType.qualifiedTypeName"/>
  </list>
  <list name="fields" eval="finder.fieldOperatorPairs"
          param="fieldOperatorPair" filter="fieldOperatorPair.field neq null">
    <let name="field" eval="fieldOperatorPair.field"/>
    <value name="name" eval="field.name"/>
    <!-- ... -->
  </list>
  <!-- ... -->
</mapping>

This can be replaced by adding uses statements for the imported classes. The artifact definition describes which import resolver to use.

<mapping xmlns="https://schemas.normalizedsystems.org/xsd/expanders/2023/1/0/mapping">
  <artifact this="classBuilder.from(finder).qualifiedName + 'Details'" importStrategy="java"/>
  <list name="fields" eval="finder.fieldOperatorPairs"
          param="fieldOperatorPair" filter="fieldOperatorPair.field neq null">
    <let name="field" eval="fieldOperatorPair.field"/>
    <value name="name" eval="field.name"/>
    <uses eval="field.javaType"/>
    <!-- ... -->
  </list>
  <!-- ... -->
</mapping>

The imports can then be inserted into the template with @imports:

base() ::= <<
package <dataElement.type.packageName>;

// <expanderComment>

// anchor:imports:start
@imports
// anchor:imports:end
@anchor:imports
...
>>

Check out the article to learn more.

In this release of Expanders, we've cleaned up some long-deprecated code that still uses UserContext as the main context transport object. There's also been several improvements in the infrastructure to improve ease of use for functional keys.

Resources​

The expansion resources below provide Expanders 5.32.0.

Changes and improvements​

Functional key infrastructure​

FinderResolver​

A new class FinderResolver has been introduced, which is called from the Bean.find() method in the logic layer. This class will automatically resolve the DataRefs for any field operator pairs that target link fields. Resolving means that it will resolve the DataRef against the database in case there's no database identifier present in it. While much of the methods in the stack already did this, the finders still did not, which often caused some confusion. The finder would not work as intended if the database identifier was not present in the DataRefs. This resolution will only occur if there is no database identifier in the DataRef, so the impact on performance should be negligible in existing code.

Agent.getDetails()​

The Agent.getDetails(DataRef) method did not behave quite the same as LocalAgent.getDetails(DataRef). Even though the same code was called down the line, the way it worked on the remote agent would lose all information in the DataRef except for the database identifier. This meant that it had to be resolved prior to use. This issue has now been resolved as well, by having it call getProjection() instead, just like its LocalAgent counterpart.

Context transport​

In a distant past, there was no Context class, rather the only context was UserContext ans it was used to pass all context information. This has been replaced for years in favor of the Context class and the UserContext has since only been used for actual information about the user. Therefore, we've started removing a lot of this deprecated infrastructure that still relied on UserContext where Context should be used instead. Some of these methods include Agent.getAgent(UserContext) and LocalAgent.getLocalAgent().

Deprecating old methods​

We intend to remove a lot of clutter that has been created in the stack over the years, with methods for backwards compatibility that should no longer be used. We've started marking many of these methods as deprecated for removal, so it is already clear to developers that these should not be used in new code and should be refactored if they are still in use in older code. A prime example of these are methods in the stack that still use a database identifier as a Long parameter, rather than a DataRef. We'll be marking more of these as deprecated in future releases.

Typed finders​

The typed finders system is now the default for all applications. The option finders.enableTypedFinders is now no longer required. Typed finders means that generics are used through the stack for finders, to ensure that the compiler will verify that they are not used with infrastructure of the wrong DataElement. It also changes the FinderBean to use mapped method references for the finder implementations, rather than reflection. This means that it is no longer possible to defined custom finders that are not present in the model.

Changes and improvements​

2 new ValueTypes have been added: VarText and EmailAddresses.

• VarText is text of variable length. It is similar to Text, but adds nativeTypes for the SQL-expanders, so that the columns are correctly initialized.
• EmailAddresses extends VarText. It expects a comma-separated list of e-mail addresses.

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>