Setup PBJava Environment

Prerequisites

Installing Java 12

Java Development Kit (JDK) is required to compile and run WebMAP PBJava converted apps, the recommended version is JDK 12.0.2.

1. Navigate to https://jdk.java.net/archive/

2. Look for 12.0.2 version or higher (Recommended version was fully tested)

3. Download Windows 64-bit zip version (x86 for legacy PC or JAR if is a Linux distribution)

4. Extract JDK and add to a folder path closest to root disk path or even better in the same location where Java is installed. (e.g. C:\Program Files\Java\jdk-12.0.2)

Installing Tomcat 9

Tomcat 9 is an application server to run WebMAP PBJava converted apps. The recommended version is 9.0.52.

1. Navigate to https://tomcat.apache.org/download-90.cgi

2. Look for 9.0.52 version or higher (Recommended version was fully tested)

3. Download Core: 64-bit Windows zip version (pgp, sha512)

4. Extract Tomcat and add to a folder path closest to root disk (e.g. C:\apache-tomcat-9.0.26)

Installing Maven 3.6.3

Maven is a builder for Java applications, it helps making the build process easy. The recommended version is 3.6.3

1. Navigate to https://maven.apache.org/download.cgi

2. Look for 3.6.3 version or higher (Recommended version was fully tested)

3. Download Binary Zip archive version

4. Extract Maven and add to a folder path closest to root disk (e.g. C:\apache-maven-3.8.2)

Installing STS 4

STS is a Eclipse IDE flavored with the Spring Framework features, the IDE choice is up to you (Eclipse, Visual Studio Code, etc) however WepMAP recommends STS 4.4.0 because it was fully tested.

1. Dowload STS 4.4.0 or higher from https://spring.io/tools or if your are inside the GAP network can be download from shared folder \\backupserver\itbackup\installers\JAVA

2. Extract STS and add .exe to a folder path closest to root disk (e.g. C:\STS\sts-4.4.0.RELEASE)

3. The STS runs executing the SpringToolSuite4.exe, to simplify execution create a shortcut and then add to Desktop, Start Menu or anywhere with easy access

Adding Environment Variables

The different tools need to be configured to be accessible from Windows OS (For different OS please omit this step) we can use the Windows Environment Variables to solve the access requirement. In previous steps the installation paths of different tools were set, now please make sure those paths match with the paths to add in the following System variables, for this example the paths are the exactly mentioned in steps above:

• CATALINA_HOME -> C:\apache-tomcat-9.0.26

• JAVA_DOC -> %JAVA_HOME%

• JAVA_HOME -> C:\Program Files\Java\jdk-12.0.2

And modify Path variable from User Variables section to add:

• Path -> Add -> C:\Program Files\Java\jdk-12.0.2\bin\

• Path -> Add -> C:\apache-maven-3.8.2\bin

Verifying Maven

Open a CMD and exectute mvn -version it should return the current Maven version:

Increasing STS build memory

STS needs more memory that default value to build WebMAP converted applications, the configuration file SpringToolSuite4.ini is located inside STS folder (e.g. C:\STS\sts-4.4.0.RELEASE), open the file with a text editor and add the next instructions if they are not already in the file:

-Xms1024m
-Xmx4096m

Workspace setup

After WebMAP conversion process the converted app generates a folder with Java Back-end code and Angular Front-end code, this is going to be the STS workspace folder. e.g.

Open the STS and select the folder as a workspace, initially the IDE should have an empty structure and the next steps are going to show how to configure the project correctly.

Adding Tomcat to STS

Add servers view(window that shows information about specific IDE area) to IDE, to add the view go to menu option Window -> Show View -> Other -> Server -> Servers

--->

Then in Servers view click link No servers are available. Click this link to create a new server... it opens the New Server window, select Tomcat v9.0 Server and click Next> button

Browse to Tomcat folder installation (e.g. C:\apache-tomcat-9.0.26) and click Finish button

Import converted projects and helpers project

To add Java WebMAP converted projects to the workspace, the Project Explorer view should be open if is not visible go to Window -> Show View -> Project Explorer and then right click over Project Explorer view, click option Import -> Import

Import window is shown, select Maven -> Exisiting Maven Projects -> Next > browse to workspace folder to select Java WebMAP projects (e.g. ReferenceApplication, Target...) and click Finish button. Repeat steps for each project

PBJavaHelpers

WebMAP PBJava converted applications need PBJavaHelpers project to run, it can be clone from: https://collaboration.artinsoft.com/tfs/Product/Product/_git/PBJavaHelpers be sure that branch develop is selected. After cloning the repository add the project performing the same steps mentioned above to add Java projects to STS workspace.

Increasing time of server Timeouts

Tomcat server has start and end timeouts default values, those values have to be increased to run WebMAP applications correctly. Double click over Tomcat v9.0 Server at localhost and navigate to Timeouts section. Modify both values to recommended value 360 ms

Adding JDK reference

1. Go to Window -> Preferences -> Java -> Installed JREs and click button Add...

2. Select Standard VM and click Next >

3. On JRE home: click Directory... button and find the path where JDK was installed (e.g. C:\Program Files\Java\jdk-12.0.2) and click Finish

4. Installed JREs window prompts with JDK added but not checked as default, please check JDK to set as default and click Apply and Close

Adding webMap.properties file

Converted WebMAP PBJava applications generate a folder with the WebMAP configuration, the folder relative path is ..\ReferenceApplication\configuration, it contains connection.properties and webMap.properties files, the folder has to be added to Tomcat server following next steps:

1. Go to Run -> Run Configurations -> double click over Apache Tomcat -> Classpath -> User Entries -> Advanced ->Add External Folder

2. Browse to configuration folder and select folder then click Apply button and finally click Close button

webMap.properties contains important configuration before run the WebMAP PBJava application, it contains the appstart parameter that indicates what is the main Java class where application should start. Note: Assure that parameter is configured with correct entry point befor run the application.

Building and running converted application

Workspace is ready to start building process, every project needs to be configured using Maven, the steps to configure a project are:

1. Right click over the project and select Run As -> Maven Build

2. Edit configuration and launch. window appears

3. On Goals field add clean install

4. Only for helpers project please check Skip Tests

5. Click Apply button and Run button

Repeat process for each project in workspace except Servers project (We recommend do process for helpers project first)

After build all workspace the projects dependencies need to be updated, it can be do with the next steps:

1. Right click on any part of Project Explorer

2. Maven -> Update Project...

3. Check all existing projects

4. Click OK button

Try to run application right clicking on start project (ReferenceApplication) and Run As -> Run on Server, application will start but in some cases an empty browser appears. The steps to solve this issue is changing Servers -> open server.xml file -> change to Source view instead of Design view -> modify path="/ws" to path="/" on <Context docBase="ReferenceApplication" node and run application again.

Final Steps (Optional)

Application should run correctly by this moment but there are some optional improvements that can be perform to improve develop process.

Configure Chrome as default browser

1. Go to Window -> Preferences -> General -> WebBrowser

2. Select External Browser

3. Select Chrome from browsers list (Chrome must be already installed)

4. Parameters can be added to run application incognito mode -incognito or in a new browser window --new-window

Excluding .js files from Java building to improve compilation time

1. Right click over ReferenceApplication project -> Properties -> JavaScript -> Include Path -> Source

2. Select Front-end deployment folder (ReferenceApplication)

3. Excluded -> Edit -> Exclusion patterns -> Add

4. Add patterns *.js and *.js.map, click OK button

5. Click Finish button