# Setup PBJava Environment

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

### 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.&#x20;

1. Navigate to [https://jdk.java.net/archive/](< 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.52)

### Installing Maven 3.8.2

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

1. Navigate to <https://maven.apache.org/download.cgi>
2. Look for 3.8.2 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 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:&#x20;

* CATALINA\_HOME              -> C:\apache-tomcat-9.0.52
* 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:

<figure><img src="/files/zA5RiFkaP7zTn12VkFIy" alt=""><figcaption></figcaption></figure>

### 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:&#x20;

```
-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.

<figure><img src="/files/MruS41efOMQTMAnTezzV" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="/files/d61tqKykAMNRliNE6B4e" alt=""><figcaption></figcaption></figure>

### 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**

![](/files/bKX37Klgfd2OLdqJMWge)--->![](/files/ANhVOUh8VLkLjUp96k0H)

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

<figure><img src="/files/k7lEdHRwFsGnKrjkLoeS" alt=""><figcaption></figcaption></figure>

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

&#x20;                                              <img src="/files/lIRwxiEkn2UNOrDBZkbR" alt="" data-size="original">

### 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**

<figure><img src="/files/F27mUbTvtjSI5hR7jGdw" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/1lYiOEYEaEBgEuEdtDKp" alt=""><figcaption></figcaption></figure>

#### 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**

<figure><img src="/files/jM8RScHim3BPtQ1TyY6D" alt=""><figcaption></figcaption></figure>

### Adding JDK reference

1. Go to **Window -> Preferences -> Java -> Installed JREs** and click button **Add...**&#x20;
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**

&#x20;                                                       ![](/files/xnp7e8DCvarh61Y0n82r)

### 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 before run the application. It will be the entry Java class where converted application starts e.g. com.project.project.mainclass***

## 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gapvelocity.ai/webmap/powerbuilder-to-java/post-conversion/setup-pbjava-environment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.