Version: 4.10.0

v4.0 Migration Guide

Application Structure

Change project structure to a Spring project structure:

[application-name] -> Project files (pom.xml, package.json...) >

src
main
java -> ApplicationBoot + Java classes

     * **resources** -> Properties

application/[application-name] -> XML files

         * config -> AWE Properties overwritten
         * js -> Javascript files
         * css -> CSS files
         * less -> LESS files
         * schemas -> XSD Schemas
         * static -> Images/Fonts
         * webpack -> Webpack configuration
         * sql -> SQL Initialization files
 * test

java -> JUnit Tests

     * *resources* -> Test properties
     * *selenium* -> Selenium suites

Maven

Change POM file:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>com.almis.awe</groupId>
    <artifactId>awe-starter-parent</artifactId>
    <version>4.0.7</version>
    <relativePath/>
  </parent>

  <artifactId>[project-name]</artifactId>
  <groupId>[project-group]</groupId>
  <version>[project-version]</version>

  <name>[Project name]</name>
  <description>[Project description]</description>

  <properties>
    <application.acronym>[project-acronym]</application.acronym>
    <start-class>[project-group].AppBootApplication</start-class>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <project.build.frontend>${project.build.directory}/classes/static/</project.build.frontend>
    <java.version>17</java.version>
  </properties>

  <dependencies>

    <!-- AWE -->
    <dependency>
      <groupId>com.almis.awe</groupId>
      <artifactId>awe-spring-boot-starter</artifactId>
    </dependency>

    <dependency>
      <groupId>com.almis.awe</groupId>
      <artifactId>awe-client-angular</artifactId>
    </dependency>

    <!-- JDBC Drivers (ADD ONLY WHAT YOU NEED) -->

    <!-- ORACLE -->
    <dependency>
      <groupId>com.oracle</groupId>
      <artifactId>ojdbc6</artifactId>
      <version>11.2.0.3</version>
      <scope>runtime</scope>
    </dependency>

    <!-- SQL SERVER -->
    <dependency>
      <groupId>com.microsoft.sqlserver</groupId>
      <artifactId>sqljdbc4</artifactId>
      <version>4.0.0</version>
      <scope>runtime</scope>
    </dependency>

    <!-- HSQL -->
    <dependency>
      <groupId>org.hsqldb</groupId>
      <artifactId>hsqldb</artifactId>
      <version>2.3.3</version>
      <scope>runtime</scope>
    </dependency>

  </dependencies>

  <build>
    <finalName>[project-name]</finalName>
    <resources>
      <resource>
        <directory>src/main/resources</directory>
        <filtering>true</filtering>
      </resource>
    </resources>
    <plugins>

      <!-- Copy static files -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <phase>generate-resources</phase>
            <id>unpack awe-generic-screens</id>
            <goals>
              <goal>unpack-dependencies</goal>
            </goals>
            <configuration>
              <includeGroupIds>com.almis.awe</includeGroupIds>
              <includeArtifactIds>awe-generic-screens</includeArtifactIds>
              <includes>schemas/**,docs/**</includes>
              <outputDirectory>${project.build.frontend}</outputDirectory>
            </configuration>
          </execution>
          <execution>
            <phase>generate-resources</phase>
            <id>unpack awe-client-angular</id>
            <goals>
              <goal>unpack-dependencies</goal>
            </goals>
            <configuration>
              <includeGroupIds>com.almis.awe</includeGroupIds>
              <includeArtifactIds>awe-client-angular</includeArtifactIds>
              <includes>images/**,fonts/**,js/**,css/**,less/**</includes>
              <outputDirectory>${project.build.frontend}</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>

      <!-- Copy images -->
      <plugin>
        <artifactId>maven-resources-plugin</artifactId>
        <version>3.0.2</version>
        <executions>
          <execution>
            <id>copy-images</id>
            <phase>prepare-package</phase>
            <goals>
              <goal>copy-resources</goal>
            </goals>
            <configuration>
              <outputDirectory>${project.build.directory}/classes/static/images/</outputDirectory>
              <resources>
                <resource>
                  <directory>${project.basedir}/src/main/resources/images/</directory>
                </resource>
              </resources>
            </configuration>
          </execution>
        </executions>
      </plugin>

      <!-- Spring boot -->
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <version>${spring-boot.version}</version>
      </plugin>

      <!-- Frontend generation -->
      <plugin>
        <groupId>com.github.eirslett</groupId>
        <artifactId>frontend-maven-plugin</artifactId>
        <version>1.6</version>
        <executions>
          <execution>
            <id>install node and yarn</id>
            <goals>
              <goal>install-node-and-yarn</goal>
            </goals>
            <configuration>
              <nodeVersion>v6.9.1</nodeVersion>
              <yarnVersion>v1.6.0</yarnVersion>
            </configuration>
          </execution>
          <execution>
            <id>yarn install</id>
            <goals>
              <goal>yarn</goal>
            </goals>
            <configuration>
              <arguments>install</arguments>
            </configuration>
          </execution>
          <execution>
            <id>webpack</id>
            <goals>
              <goal>webpack</goal>
            </goals>
            <configuration>
              <arguments>--output-path "${project.build.frontend}"</arguments>
            </configuration>
          </execution>
        </executions>
      </plugin>

      <!-- Xml validation -->
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>xml-maven-plugin</artifactId>
        <executions>
          <execution>
            <id>validate</id>
            <phase>compile</phase>
            <goals>
              <goal>validate</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

      <!-- Build an executable JAR -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.0.2</version>
        <configuration>
          <archive>
            <manifest>
              <addClasspath>true</addClasspath>
              <classpathPrefix>lib/</classpathPrefix>
              <mainClass>${start-class}</mainClass>
            </manifest>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Javascript & CSS generation

Define a webpack file to generate custom javascript and css

XML files

Screens

Regular expressions
Dependency source-type="action" is not needed anymore. Just add your dependency actions and they will be launched on valid conditions.
source-type="none" and target-type="none" attributes are default values, so you don't need to set them.
Remove source-type="action", source-type="none" and target-type="none":

^(.*)source\-type\s*=\s*["']action["']\s*(\S+.*)$ => $1$2
^(.*)source\-type\s*=\s*["']none["']\s*(\S+.*)$ => $1$2
^(.*)target\-type\s*=\s*["']none["']\s*(\S+.*)$ => $1$2

Note: XXXX => YYYY means that you must search for XXXX expression and replace with YYYY expression

Direct replacement:
Fix dependency conditions:

condition="lte" => condition="le"
condition="gte" => condition="ge"

Grid pagination to grid managed pagination:

pagination="true" => managed-pagination="true"

control-empty-cancel action to control-unique-cancel action:

control-empty-cancel => control-unique-cancel

Query & Maintain

Regular expressions
Fix query and maintain filters:

^(\s*<filter.*\s+)value(.*/>.*)$ => $1left-variable$2 -> Replace by left-variable and add the variable name
^(\s*<filter.*\s+)variable(.*/>.*)$ => $1right-variable$2
^(\s*<filter.*\s+)counterfield(.*/>.*)$ => $1right-field$2
^(\s*<filter.*\s+)countertable(.*/>.*)$ => $1right-table$2
^(\s*<filter.*\s+)field(.*/>.*)$ => $1left-field$2
^(\s*<filter.*\s+)table(.*/>.*)$ => $1left-table$2
^(\s*<)field(.*\s+value.*/>.*)$ => $1constant$2

Direct replacement:
Fix query conditions:

condition="=" => condition="eq"
condition="!=" => condition="ne"
condition="LIKE" => condition="like"
condition="NOT LIKE" => condition="not like"
condition="&amp;gt;" => condition="gt"
condition="&amp;gt;=" => condition="ge"
condition="&amp;lt;" => condition="lt"
condition="&amp;lt;=" => condition="le"
condition="IS NULL" => condition="is null"
condition="IS NOT NULL" => condition="is not null"
condition="IN" => condition="in"
condition="NOT IN" => condition="not in"

Variable identifiers can't be used in field aliases.
CASE and CONCAT definitions must be defined now with the new AWE <case> and <operation> tags. See more at Query Definitions.
Static values must be defined as <constant> tags
AWE now offers more flexibility generating queries and filters:

<query id="testRowNumber">
  <table id="ope"/>
  <field id="l1_nom" alias="name"/>
  <over alias="rowNumber">
    <field function="ROW_NUMBER"/>
  </over>
  <order-by field="l1_nom" type="ASC"/>
</query>

<query id="testCoalesce">
<table id="ope"/>
<field id="l1_nom" alias="name"/>
<operation operator="COALESCE" alias="nameNotNull">
  <field id="l1_trt"/>
  <constant type="NULL"/>
  <field id="l1_nom"/>
</operation>
<where>
  <filter condition="eq" ignorecase="true">
    <left-operand>
      <field id="l1_nom"/>
    </left-operand>
    <right-operand>
      <constant value="test"/>
    </right-operand>
  </filter>
</where>
<order-by field="l1_nom" type="ASC"/>
</query>

<query id="testCaseWhenElse">
<table id="AweThm"/>
<case alias="value">
  <when left-field="Nam" condition="eq" right-variable="sunset">
    <then>
      <constant value="1" type="INTEGER"/>
    </then>
  </when>
  <when left-field="Nam" condition="eq" right-variable="sunny">
    <then>
      <constant value="2" type="INTEGER"/>
    </then>
  </when>
  <when left-field="Nam" condition="eq" right-variable="purple-hills">
    <then>
      <constant value="3" type="INTEGER"/>
    </then>
  </when>
  <else>
    <constant value="0" type="INTEGER"/>
  </else>
</case>
<case alias="label">
  <when condition="eq">
    <left-operand>
      <field id="Nam"/>
    </left-operand>
    <right-operand>
      <constant value="sunset"/>
    </right-operand>
    <then>
      <constant value="SUNSET"/>
    </then>
  </when>
  <when condition="eq">
    <left-operand>
      <field id="Nam"/>
    </left-operand>
    <right-operand>
      <constant value="sunny"/>
    </right-operand>
    <then>
      <constant value="SUNNY"/>
    </then>
  </when>
  <when condition="eq">
    <left-operand>
      <field id="Nam"/>
    </left-operand>
    <right-operand>
      <constant value="purple-hills"/>
    </right-operand>
    <then>
      <constant value="PURPLE-HILLS"/>
    </then>
  </when>
  <else>
    <constant value="other"/>
  </else>
</case>
<order-by field="Nam" type="ASC" nulls="FIRST"/>
</query>

<query id="TestFieldDateFunctions">
<table id="ope" alias="awe"/>
<field id="dat_mod" table="awe" alias="year" function="YEAR"/>
<field id="dat_mod" table="awe" alias="month" function="MONTH"/>
<field id="dat_mod" alias="day" function="DAY"/>
<field id="dat_mod" alias="hour" function="HOUR"/>
<field id="dat_mod" alias="minute" function="MINUTE"/>
<field id="dat_mod" alias="second" function="SECOND"/>
<where>
  <filter left-field="l1_nom" condition="eq" ignorecase="true">
    <right-operand>
      <constant value="test"/>
    </right-operand>
  </filter>
</where>
<order-by field="dat_mod" table="awe" function="YEAR"/>
</query>

Services

Web services calls have been changed to microservices calls:

Examples:

<service id="simpleGETMicroservice">
  <microservice name="alu-microservice" method="GET" endpoint="/invoke" content-type="JSON"/>
</service>

<service id="simpleGETMicroservice2">
<microservice name="alu-microservice2" method="GET" endpoint="/invoke" content-type="JSON"/>
</service>

<service id="simpleGETMicroserviceWithWrapper">
<microservice name="alu-microservice" method="GET" endpoint="/invoke"
              wrapper="com.almis.awe.service.dto.ServiceDataWrapper" content-type="JSON"/>
</service>

<service id="simpleGETMicroserviceWithParameter">
<microservice name="alu-microservice" method="GET" endpoint="/invoke" content-type="JSON">
  <service-parameter name="param1" type="STRING"/>
</microservice>
</service>

<service id="simpleGETMicroserviceWithWildcard">
<microservice name="alu-microservice" method="GET" endpoint="/invoke/{param1}" content-type="JSON">
  <service-parameter name="param1" type="STRING"/>
</microservice>
</service>

<service id="simpleGETMicroserviceWithWildcardAndParameter">
<microservice name="alu-microservice" method="GET" endpoint="/invoke/{param1}" content-type="JSON">
  <service-parameter name="param1" type="STRING"/>
  <service-parameter name="param2" type="STRING"/>
</microservice>
</service>

<service id="simplePOSTMicroserviceWithParameters">
<microservice name="alu-microservice" method="POST" endpoint="/invoke" content-type="JSON">
  <service-parameter name="param1" type="STRING"/>
  <service-parameter name="param2" type="STRING"/>
</microservice>
</service>

<service id="simplePUTMicroserviceWithParameters">
<microservice name="alu-microservice" method="PUT" endpoint="/invoke" content-type="JSON">
  <service-parameter name="param1" type="STRING"/>
  <service-parameter name="param2" type="STRING"/>
</microservice>
</service>

<service id="simpleDELETEMicroserviceWithWildcard">
<microservice name="alu-microservice" method="DELETE" endpoint="/invoke/{param1}" content-type="JSON">
  <service-parameter name="param1" type="STRING"/>
</microservice>
</service>

Locales

Rename Local-XX.xml files to Locale-XX.xml
Direct replacement:

<locals => <locales
</locals> => </locales>
<local => <locale
</local> => </locale>

Properties

Encode again the properties encoded with ENC(xxxx) at the Encrypt util screen.

Java files

Package refactorization

Direct replacement:
Packages

com.almis.awe.core.services.data.global.XMLWrapper => com.almis.awe.model.entities.XMLFile
com.almis.awe.core.services.data.global.XMLElement => com.almis.awe.model.entities.XMLFile
com.almis.awe.core.services.data.service.ServiceData => com.almis.awe.model.dto.ServiceData
com.almis.awe.core.services.controller.DataController => com.almis.awe.service.QueryService
com.almis.awe.core.services.controller.MaintainController => com.almis.awe.service.MaintainService
com.almis.awe.core.util.DateUtil => com.almis.awe.model.util.data.DateUtil
com.almis.awe.core.beans.ComponentAddress => com.almis.awe.model.entities.actions.ComponentAddress
com.almis.awe.core.services.data.action.ClientAction => com.almis.awe.model.entities.actions.ClientAction
com.almis.awe.dto => com.almis.awe.model.dto
com.almis.awe.core.services.data.global => com.almis.awe.model.dto
com.almis.awe.type => com.almis.awe.model.type
com.almis.awe.core.services.data.query => com.almis.awe.model.entities.queries
com.almis.awe.core.services.data.maintain => com.almis.awe.model.entities.maintain
com.almis.awe.core.exception => com.almis.awe.exception
XMLElement => XMLWrapper
AWEConstants => AweConstants
AweConstants.PARAMETER_MAX => AweConstants.COMPONENT_MAX

Logging

Remove com.almis.awe.core.util.LogUtil
Import org.apache.logging.log4j.LogManager and org.apache.logging.log4j.Logger
Create a static logger field:

  // Logger
private static Logger logger=LogManager.getLogger(MyClass.class);

Use static logger. For example:

  logger.log(Level.INFO,"[{}] No books defined for this treatment",treatment.getID());

Alternate logger: Lombok

Add @Slf4j annotation on top of the class:

@Slf4j
public MyClass{
       ...
       } 

Use lombok logger:

  log.error("My error message {}",moreInformationInVariables,exception);

AWE packages

There are two main packages in AWE 4.0: awe-spring-boot-starter and awe-model.
awe-spring-boot-starter is the core package of AWE. AWE based web applications must import this package.
To call AWE services, autowire services from com.almis.awe.services (No more Controller calls)
awe-model is the interface package of AWE. AWE related applications (communication modules, microservices, etc) can import this package to gain access to interface classes.

Java services must be migrated to Spring architecture

Remove all controllers if they don't do anything
Class structure in AWE has been changed radically. Check your Java imports
Move manager package to service package
Rename all XxxManager.java classes to XxxService.java classes
Add @Service annotation to XxxService.java classes
Use Spring methodology (@Autowired constructors, @Value to retrieve properties, etc)
Extend all XxxService classes from ServiceConfig if they are using:
com.almis.awe.core.singleton.LocalSingleton => Extend from com.almis.awe.config.ServiceConfig and call getLocale methods
com.almis.awe.core.singleton.PropertySingleton => Extend from com.almis.awe.config.ServiceConfig and call getProperty methods (And best of all use @Value instead of getProperty methods)
com.almis.awe.core.services.controller.SessionController => Extend from com.almis.awe.config.ServiceConfig and call getSession
com.almis.awe.core.services.data.global.Context => Extend from com.almis.awe.config.ServiceConfig and call getRequest to retrieve request parameters
Remove also ContextUtil.getContext() access
Use also getRequest().getTargetAction() to retrieve the action target called.
More information on Locale retrieval, Property retrieval , Session retrieval and Request retrieval.
Adapt custom authentication if overwritten in application
Use QueryService instead of DataController. All launchQuery methods now return ServiceData beans instead of DataList. You can retrieve the DataList with serviceData.getDataList() method.
Use MaintainService instead of MaintainController.

Locale retrieval

Extending from ServiceConfig you get access to getLocale methods:

  getLocale("ERROR_TITLE_LAUNCHING_MAINTAIN");

You can pass variables to replace on locale simply by adding them as arguments:

  getLocale("ERROR_TITLE_LAUNCHING_MAINTAIN",treatment.getID(),task.getID());

Property retrieval

Extending from ServiceConfig you get access to getProperty methods:

  getProperty("var.trt.thd.sug.tim",100);

Anyway it's more legible and faster to retrieve properties the Spring way:

  @Value("${var.trt.thd.sug.tim:100}")
private Integer suggestTime;

Session retrieval

Extending from ServiceConfig you get access to getSession methods:

  getSession().getParameter(AweConstants.SESSION_DATABASE);

Request retrieval

Extending from ServiceConfig you get access to getRequest methods instead of retrieving them from Context:

  getRequest().getParameter(AweConstants.PARAMETER_MAX).textValue();

  getRequest().getParameterAsString(AweConstants.PARAMETER_MAX);

You can also add some variables to the request:

  getRequest().setParameter("someList",someList);

Datalist type

DataList getRows method has changed its' signature from ArrayList<HashMap<String, CellData>> to a more generic signature: List<Map<String, CellData>>.

Beans

Use copy constructor instead of Cloneable interface:

public class MyClass implements Copyable<MyClass> {

  private String myProp1;
  private String myProp2;

  /**
   * Default constructor 
   */
  public MyClass() {
  }

  /**
   * Copy constructor 
   */
  public MyClass(MyClass other) {
    this.myProp1 = other.myProp1;
    this.myProp2 = other.myProp2;
  }

  /**
   * Copy method
   * @return Copy of this object
   */
  public MyClass copy() {
    return new MyClass(this);
  }
}

or use Lombok:

@Data
@Builder(toBuilder = true)
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
public class MyClass {
  private String myProp1;
  private String myProp2;
}

... and clone it with the builder:

MyClass myNewClass=myOldClass.toBuilder().build();

Remove from beans all methods which uses any external class. A bean only should have methods which interact over their own fields.

`fill` client action now has only one parameter: `datalist`, which will contain the full DataList:

serviceData.addClientAction(new ClientAction("fill")
        .setAddress(address)
        .addParameter("datalist",datalist)
        .setAsync(true));

... but it's simpler to use the new ClientAction builders:

serviceData.addClientAction(new FillActionBuilder(address,datalist).setAsync(true).build());

`FileData` bean has now a new implementation:

Use FileUtil.fileDataToString to generate a token:

public String fileDataToString(FileData fileData)

Use FileUtil.stringToFileData to retrieve a FileData bean from a token:

public FileData stringToFileData(String fileStringEncoded)

Note: FileUtil is an autowireable @Component

Web services ↪️ Microservices

Adapt web service interface as microservice

Awe has a new service connector layer to make requests to microservices and rest services. See services doc.

caution

Note: To migrate the existing web services in the applications that used with AWE 3, you have to take into account the following points:

Parameter sending:

Maintains: The attribute name of service-parameter has to be the same as the attribute id of variable field of serve elements.

maintains.xml
<target name="MyMaintain">
   <serve service="MyService">
     <variable id="id1" type="STRING" name="criterion1.selected"/>
     <variable id="id2" type="STRING" name="criterion2.selected"/>
     <variable id="id3" type="STRING" name="criterion3.selected"/>
  </serve>
</target>

global/Services.xml
<service id="CtrEvnDetIsuCnfSer">
 <microservice name="alu-microservice" method="POST" endpoint="/maintain/myMicroservice" content-type="JSON">
   <service-parameter name="id1" type="STRING" list="true"/>
   <service-parameter name="id2" type="STRING" list="true"/>
   <service-parameter name="id3" type="STRING" list="true"/>
 </microservice>
</service>

webservice/services.xml
 <service name="myMicroService" type="MAINTAION" call="myWebService">
   <param list="false" name="id1" type="STRING"/>
   <param list="false" name="id2" type="STRING"/>
   <param list="false" name="id3" type="STRING"/>
 </service>

Queries: The attribute name of service-parameter has to be the same as the attribute id of query field. Usually, you have to add alias field with the name to describe that field.

queries.xml
 <query id="MyQuery" service="MyService">
   <field id="id1" alias="alias1"/>
   <field id="id2" alias="alias2"/>
   <field id="id3" alias="alias3"/>
   ...
</query>      

global/services.xml
 <service id="MyService">
   <microservice name="alu-microservice" method="POST" endpoint="/data/myMicroService" content-type="JSON">
     <service-parameter list="false" name="id1" type="STRING"/>
     <service-parameter list="false" name="id2" type="STRING"/>
     <service-parameter list="false" name="id3" type="DATE"/>
   </microservice>
</service>

webservice/services.xml
 <service name="myMicroService" type="DATA" call="myWebService">
   <param list="false" name="id1" type="STRING"/>
   <param list="false" name="id2" type="STRING"/>
   <param list="false" name="id3" type="DATE"/>
 </service>

The number of service-parameters must be equal to param of service element (webservice).
The order of service-parameters matters.

Application Structure​

Maven​

Javascript & CSS generation​

XML files​

Screens​

Query & Maintain​

Services​

Locales​

Properties​

Java files​

Package refactorization​

AWE packages​

Java services must be migrated to Spring architecture​

Locale retrieval​

Property retrieval​

Session retrieval​

Request retrieval​

Datalist type​

Beans​

fill client action now has only one parameter: datalist, which will contain the full DataList:​

FileData bean has now a new implementation:​

Web services ↪️ Microservices​