33 posts tagged with "migration-guide"

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.

Meta-model​

Following changes to NS model infrastructure, which now introduces options for every DataElement, the QuerySearchOption and QuerySearchOptionType elements have been removed. This functionality has so far not been adopted in such a way that it would have an impact. The new Option and OptionType elements in prime-core are now used as an alternative.

Meta-model​

Though still under development and prone to changes, this version introduces a very large structural change in the meta-model for QuerySearch, which may affect other expansion resources and early adopters.

The QuerySearch element now has DataElement as its parent element, rather than Component like it did before. This is the correct intended structure for the model, which was previously not possible due to technical limitations. What this affects:

• Expansion resources:
  • QuerySearch.component field no longer exists and is now only accessible as QuerySearch.dataElement.component.
  • QuerySearch instances are now registered in DataElement.extensions[] instead of Component.extensions[].
• Application projects:
  • QuerySearch model xml files have moved from <componentRoot>/model/querySearchs to <componentRoot>/model/dataElements/<dataElement>/querySearchs.
  • The QuerySearch model files should no longer contain a DataRef to the parent DataElement.

RestFacade removal​

The RestFacade class which was used previously in the control layer as a bridge between the Connector and Agent classes has been removed. This was an old artifact left from the original REST JAX-RS implementation for the NS application stack. This class was intended to provide some encapsulation, but it did not really encapsulate anything and violated data version transparency.

• $dataElement.name$RestFacade.create$dataElement.name$(): This method was integrated into the $dataElement.name$Connector.create$dataElement.name$() method.
• $dataElement.name$RestFacade.modify$dataElement.name$(): This method was integrated into the $dataElement.name$Connector.put$dataElement.name$() method.
• $dataElement.name$RestFacade.update$dataElement.name$(): This method was integrated into the $dataElement.name$Connector.patch$dataElement.name$() method.
• $dataElement.name$RestFacade.remove$dataElement.name$(): This method was integrated into the $dataElement.name$Connector.delete$dataElement.name$() method.
• $dataElement.name$RestFacade.fetch$dataElement.name$(): This method was integrated into the $dataElement.name$Connector.get$dataElement.name$Details() method, where the SearchDetails is now also constructed.
• $dataElement.name$RestFacade.fetch$dataElement.name$List(): This method was integrated into the $dataElement.name$Connector.get$dataElement.name$DetailsList() method, where the SearchDetails is now also constructed with support for sort parameters.
• $dataElement.name$RestFacade.applyPagination(): This method was moved to a new class $dataElement.name$Pagination.
• $dataElement.name$RestFacade.DEFAULT_PAGE: This constant was moved to a new class $dataElement.name$Pagination.
• $dataElement.name$RestFacade.DEFAULT_PAGE_SIZE: This constant was moved to a new class $dataElement.name$Pagination.
• $dataElement.name$RestFacade.MAX_PAGE_SIZE: This constant was moved to a new class $dataElement.name$Pagination.

All existing custom methods that were placed in the RestFacade class should be either integrated into their respective callers or be properly encapsulated if required in its own custom class. To provide some backwards compatibility for transitioning, the expansion of the RestFacade class can still be enabled with the transient option jaxrs.transient.generateFacade.enable. All expanded endpoints will no longer use the RestFacade even if this transient option is defined.

Sorting​

Default Order​

For some time data returned by the GETlist endpoints was always sorted ascending by database identifier by default if no other sorting was enforced in the DataElement's QuerySearch class. This functionality was removed after the querysearch-expanders split off from the rest-expanders, as for many requests it does not make sense to deteriorate query performance by always enforcing a default order.

Not having this default ordering for the REST apis created an issue with results returned by the query not always being consistently ordered in between multiple calls. As a result, paginated results do not always make sense as resources can will sometimes shift places in the results.

The querysearch-expanders introduced the option useDefaultOrder on the QuerySearch metamodel element, which is implicitly created by the rest-expanders. This option is now always added to that QuerySearch instance as well, so the default ordering by database identifier is always enforced for the REST API. Contrary to the original implementation, the ordering by database identifier is also enforced if other ordering is applied to the query, but it is added as the last order in the chain.

If for some reason it is required to disable this default ordering, this can still be achieved per individual DataElement by setting the default order to false on the queryBuilder in the QuerySearch class:

// anchor:custom-query-before-build:start
queryBuilder.useDefaultOrder(false);
// anchor:custom-query-before-build:end

Sorting parameter​

This version of the REST expanders introduces sorting of results returned by the GETlist endpoint through a query parameter sortby. This parameter is now always added to the expanded endpoints. It can however be disabled by adding the option jaxrs.endpoint.getList.sorting.disable to the DataElement or for the entire Component by adding the option jaxrs.endpoint.getList.sorting.disable to the Component.

Miscellaneous​

• All ValidationError constants in the ValidationError class are now marked final. They should always be fixed. Any deviations should be registered as new error codes.
• The pagination anchors were removed from the applyPagination() method, as pagination parameters can now be set through expansion options.

SQL script location​

Starting with version 2.0.0, the database setup script is no longer expanded to [APPLICATION_ROOT]/provision_db.sql, not is now available as [APPLICATION_ROOT]/database/000-init-database.sql. This change was made as there is now also the initial data script, which is expanded to [APPLCIATION_ROOT]/database/001-app-init-data.sql.

Paging parameters​

The DEFAULT_PAGE and DEFAULT_PAGE_SIZE constants could previously be modified using the anchors custom-default-page and custom-default-page-size. These anchors have been dropped in favor of DataOptions jaxrs.endpoint.getList.defaultPage and jaxrs.endpoint.getList.defaultPageSize.

QuerySearchResolver​

The QuerySearchResolver class was moved from the data layer to the logic layer. Since this is used most commonly to resolve references to other components, the use of Cruds classes in the data layer will create high coupling between those components, which is not intended.

To transition to the logic layer implementation, the Agent classes should be used when resolving data for elements in other components. In this scenario there is also no need to use dependency injection with EJB, as the agents do not require this.

A transient option querysearch.transient.dataLayerResolver.enable has been supplied to revert the behavior of the expanders for backwards compatibility. But keep in mind that this option will be removed in the future and has only been supplied for short-term compatibility if needed, allowing for planning to upgrade the codebase. This option will once again expand the QuerySearchResolver in the data layer, rather than the logic layer.