This document describes the steps needed to upgrade the edoras one application to 1.5.0.S109.
Please stop the edoras one server, perform all upgrade steps described below and then restart the server again at the end.
REST service refactoring
In this release the REST endpoint implementations were significantly refactored to improve the transaction handling. In most cases no changes are required in customer projects, as the supported REST endpoints remain unchanged and function exactly as before.
If your project contains patched versions of the affected REST service implementations or the corresponding Spring bean configurations then these will have to be updated to match the new code. The main classes affected are:
-
com.edorasware.cloud.core.service.frontendobject.FrontendObjectRestService
-
com.edorasware.cloud.core.service.frontendobject.ModelerDashboardRestService
-
com.edorasware.cloud.core.service.frontendobject.UserDashboardRestService
-
com.edorasware.cloud.core.service.frontendobject.AdminDashboardRestService
In the previous release, *RestService
implementations had two separate roles: they defined the REST interface and
also contained the corresponding high-level implementation. Functionality shared by the dashboard rest services
was provided by a common abstract base class, AbstractFrontendObjectRestService
(so-called after the name
of the DTO class used to transfer work object information between the server and the client):
The new implementations follow the pattern of a REST controller that defines the REST interface and contains
only the code needed to map between the business logic and the REST API. The business logic and transaction boundary
handling is delegated to a separate manager with a defined interface. Shared functionality is now moved to the class
FrontendObjectManagerUtils
which is referenced using composition instead of inheritance:
Code that uses the business logic from the old RestService implementations (e.g. to implement integration tests) can generally be simply updated to use the relevant manager interface instead. Some lower-level interface methods were also modified to make them more generic and if these are used in project code then it should be clear from the resulting compiler errors what needs to be changed.
In most cases the business logic that used to be provided by a *RestService
class is now provided by the
corresponding *Manager
class. The one exception is the App model import / export functionality which is now
managed by the separate AppImportExportRestService
. This and other REST services will also be migrated to use the
new controller / manager pattern in a future release.
Improved database handling
The database versioning check has been improved so that the application will be prevented from starting if the database version is newer than the application. This prevents problems that could arise from running old code on a newer database schema. The database creation strategy options have also been streamlined.
Changes in the database schema services
In this release there are several changes in the database schema services which were needed to break up some circular dependencies
and to introduce the use of listeners in the DatabaseSchemaService
. The following changes have been made:
Instantiation of the database schema beans
In the past the database schema beans were constructed inside the parser for the <gear:persistence-management…>
XML tag and now
these beans need to be defined separately. If you do not override the config/execution/persistence-management-config.xml
file in
your edoras one project (or in your test setup) then you do not need to change anything as these changes will be already configured
for you in this release.
If you overwrite this file or have your own <gear:persistence-management…>
configuration then you need to add the following three
beans to your application context:
<bean id="databaseSchemaService" class="com.edorasware.commons.core.persistence.schema.internal.DefaultDatabaseSchemaService">
<constructor-arg name="dataSource" ref="dataSource"/>
<constructor-arg name="migrationsLocation" value="com/edorasware/commons/core/persistence/schema"/>
<constructor-arg name="transactionManager" ref="transactionManager"/>
<property name="listener" ref="dataConsistencyPatch"/>
</bean>
<bean id="databaseSchemaManager" class="com.edorasware.commons.core.persistence.schema.internal.StrategyBasedDatabaseSchemaManager">
<constructor-arg name="databaseSchemaService" ref="databaseSchemaService"/>
<constructor-arg name="strategy" value="CREATE_UPDATE"/>
</bean>
<bean id="databaseSchemaManagerLifecycleBean" class="com.edorasware.gear.core.persistence.schema.DatabaseSchemaManagerLifecycleBean">
<constructor-arg name="databaseSchemaManager" ref="databaseSchemaManager"/>
</bean>
The above code implies that the data source bean has the id dataSource
, if not then please change the id in the databaseSchemaService
bean definition. And if you use separate data source for the schema updates which differs from the main data source, then also adapt the
id in the databaseSchemaService
bean definition.
Interface changes and listener support in the DatabaseSchemaService
In this release the upgrade()
method was removed from the com.edorasware.commons.core.persistence.schema.DatabaseSchemaService
interface
as this is not needed anymore. Please also note that we now support listener infrastructure for each operation on the DatabaseSchemaService
.
For the usage please have a look at the com.edorasware.commons.core.persistence.schema.DatabaseSchemaServiceListener
and the related classes.
Changes in the DatabaseSchemaCreationStrategy
This enum has been refactored to simplify its usage. The strategies create-or-validate
and create-update
have been removed. Now there
are the following database schema creation strategies:
Old value |
New value |
|
|
|
|
|
|
Also note that the format changed and please adapt this in your project if you use/override this somewhere. Please check the java doc on the
com.edorasware.commons.core.persistence.schema.DatabaseSchemaCreationStrategy
class for further information about the strategies.
CMMN developer API refactoring
A new transition was introduced to terminate AVAILABLE and ENABLED plan items of a completed stage. The transition is called parentComplete
.
Client projects implementing the TransitionListeners interface may have to provide an empty method stub in order for their code to compile
after upgrading.
Related modifications to the CMMN Spring config: there is a new bean config for bean parentCompleteHandlers' and two new arguments to
the `oneEngineListeners
bean.
The transition listener method suspend
has been removed. You may have to remove empty implementations
in your code in order for it to compile (there may be @Override annotations which now don’t compile).
Custom transition handler implementations now must implement the generic handleTransition method of the abstract TransitionHandler class. The new method was introduced to be more generic. It replaces the old methods that are named after the particular transition to execute. The old methods are still there. They now simply delegate to the generic implementation. Thus, if you extended DefaultCmmnExtensions, you’ll be able to just rename your old implementation method to the new method name.
New CMMN configuration options
The following three configuration options have been added to one.properties
:
-
cmmn.expose.planItemModelTypes
-
cmmn.expose.planItemTypes
-
cmmn.expose.planItemStates
By default, the properties are set to empty. Two of the properties are referenced in cmmn-engine-context.xml
where they are passed as
additional constructor arguments.
Changes in the content conversion xml configuration
The configuration file "content-config.xml" of the edoras-one-server-core module has been refactored to distribute its declared beans into two files: the existing "content-converter-config.xml" for all the content conversion beans and a new file called "content-utils-config.xml" for the content management related beans.
This change also removes a duplicated config filename in the project, between the so called file of edoras-one-server-core and the one from the edoras-one-hosted. Now, there is only a "content-config.xml" in the project, where the content manager is configured.
As the changes in the edoras-one-server-core are internal, the configuration of the bootstrap project is not affected.
URL Encoding
All URLs are now automatically encoded in the experimental View Engine. This means that if you are using manually encoded URLs in your model, then you need to change these URLs back to a non-encoded URL. This is the proper way to define the URLs. So, for most customers, there is no change needed. Here an example for such a change of a manually encoded URL that needs to be changed:
-
URL example with custom manual encoding:
search?q={{someExpression}}+type:CAS
-
URL example as it should be, without encoding:
search?q={{someExpression}} type:CAS
{note} For more information see here
If you are using the experimental View Engine and you have many encoded URLs defined in your model and/or you do not want to touch your model, you can enable a backwards compatibility mode by setting the following system property in your project properties file:
backwardcompatibility.urlencoding=true
The default value of this parameter is false
and the default behavior is to auto encode all URLs.
In general, this should be only a temporary workaround as we will remove this property and the backwards compatibility in some later sprints. The proper solution is to remove any
manual custom encoding in your URLs. We advise you to plan to change this in your models before we will remove the backwards compatibility.
Changes in vis configuration related to REST service refactoring
These changes are dependent on how you use edoras one: if you use the vanilla edoras-one-hosted
WAR file then you do not need to follow these steps, but if you use edoras one
as a dependency in your project then please read the changes carefully. Maybe not all changes apply to your setup as you did not overwrite the specified edoras one
configuration files. These are the changes you need to do if you overwrite the mentioned file:
-
In the
com/edorasware/vis/config/vis-application-context.xml
:-
In the bean declaration for the class
com.edorasware.vis.preview.service.VisTaskPreviewService
change the id toimagePreviewService
-
In the bean declaration for the class
com.edorasware.vis.translation.service.VisAppTranslationService
change the id toappTranslationService
-
In the bean declaration for the class
com.edorasware.vis.app.datamodel.service.VisAppDataModelService
change the id toappDataModelService
-
Bootstrap project
Here you will find a list of files which have changed in the bootstrap project since the last release. This helps you check the difference between your bootstrap project version and the current one:
-
src\edoras-one-bootstrap\src\main\resources\com\edorasware\bootstrap\config\one.properties
:: three new CMMN properties and property for url backward compatibility encoding added