Construct The Development Environment

To develop web applications based on iPLAss, the gradle project skeleton for Eclipse is provided. This guide will go through the process starting from setting up the Eclipse and compiling the projects, until eventually start the web applications after all the configurations.

In order to construct the development environment, please have the following environment prepared.

JDK

Java SE8/11 or OpenJDK11

AP Server

Tomcat 8.5

DB Server

One of the followings

  • Oracle 11gR2 or higher

  • MySQL 5.7 or higher

  • SQL Server 2012 or higher

  • PostgreSQL 9.6 or higher

Eclipse

Eclipse IDE for Java EE Developers 4.7.3 and higher

Install/Decompress the downloaded installer or compressed files to any directory.

Place the JDBC Driver

Put the JDBC driver of the corresponding Database being used in the lib folder at Tomcat’s directory.

In real-life production environment, there are cases that the Database rely on DataSource for connections. To use DataSource, it is necessary to place the JDBC driver in the directory of Tomcat. This document does not use DataSource, but for the reason depicted above, we want to place the JDBC driver at Tomcat side rather than the project side.

If there is no existing database and tables for iPLAss, then it is necessary to configure the DB in order to start with.

Please follow one of the following methods to create the database and tables.

  • Use Install and Run wizard.

  • Download iPLAss SDK, and execute the DDL included in the package to create the database and tables.

When constructing production environment, please utilize the DDL files from iPLAss SDK. As the method from Install and Run is not recommended in that case. If Java 11 are used, please make sure your Database and JDBC are updated to the newest version. The connection policy was modified to TLSv1.3 in Java 11 so the old versions may not comply with and will throw Exceptions.
  1. Run the downloaded installer.
    If JAVA_HOME was not set, the dialog to select javaw.exe will show up. Please select the javaw.exe in the directory of the installed JDK.

  2. On the started interface page, select Eclipse IDE for Java EE Developers, and install to any directory.

  3. After the installation, start the Eclipse and create the workspace at any directory.

  4. From the menu bar, choose Window > Preference to open the interface for settings.

    1. Settings for Encoding
      At General > Workspace , change the Text file encoding to Other(UTF-8) .

    2. Settings for JDK
      Make sure the installed JDK shows in Java > Installed JREs . If it was not there, add the JDK manually and set it to default. Then, open Java > Compiler and check if Compiler compliance level is 1.8. (It is 11 for Java 11)

    3. Setting for Tomcat
      Add the installed Tomcat in Server > Runtime Environments. Choose Apache Tomcat v8.5, and specify the Tomcat directory that we installed previously.

Project is using the source from GitHub . Clone or download You can either Clone or download the URL, but it is recommended to download the zip file.

The project can be created by the following steps.

  1. Import the project.

  2. Copy the URL from Clone option.

  3. Right click the Project Explorer from Eclipse, and chose Import > Import…​.

  4. Then choose Git > Projects from Git.

  5. Then Clone URI.

  6. Make sure the copied URI is in Location’s URI box, and fill in the username and password for the Authentications.

  7. Choose master branch.

  8. At Destination’s Directory, specify the workspace that was indicated when starting the Eclipse.

  9. Choose Import as general project at project import wizard.

  10. Project Name does not need to be modified, just click Finish.

Delete Git History
  1. From the menu bar, select Window > Perspective > Open Perspective > Other > Git, and open Git Repository.

  2. Right click iplass-skeleton and click Delete Repository.

  3. Check Delete Git repository data and history and click OK.

  4. After deleting the content, refresh the project.

When creating the project by cloning, a Github account is necessary.

The project can be created with the following steps.

Get ZIP File
  1. At Clone or download, click on Download ZIP to download the ZIP file.

  2. Decompress the ZIP file, and move the iplass-skeleton folder to the root directory of your workspace.

Import the Project
  1. Right click the Project Explorer on the top-right of Eclipse, and choose Import > Import…​.

  2. Then General > Projects from Folder or Archive.

  3. For Import source, specify the folder you moved to the workspace, uncheck the Detect and configure project nature and then click Finish.

Create the project with the skeleton project included in iPLAss SDK.

Get iPLAss SDK
  1. Download from Download_Site or from the URL given along with the enterprise edition’s contracts.

  2. Decompress the iPLAss SDK, place the iplass-skeleton folder to the workspace of eclipse.

For the enterprise edition, it is iplass-ee-skeleton.
Replace the configuration file
  1. Open the iplass-ee-skeleton folder and overwrite the existed gradle.properties by the one provided along with the Enterprise Edition’s contracts.

Import the Project
  1. Right click the Project Explorer on top-right of the Eclipse, and choose Import > Import…​.

  2. Then General > Projects from Folder or Archive .

  3. For Import source, specify the folder you moved to the workspace, uncheck the Detect and configure project nature and then click Finish.

Rename The Application
  1. Decide the name for the projects and change it via Refactor > Rename.

  2. Use Refactor > Move to move the project folder corresponding to the project name.

  3. Change the rootProject.name from setting.gradle according to the project name.

Get JDBC Driver
  1. As mentioned before, the JDBC driver placed in Tomcat directories will be used when running the web applications. It is also used when running the Tenant tools which will be discussed later.

    • Oracle(ojdbc8.jar)'s case
      From the vendor’s download site, you can download the jar file, please put it in the lib folder directly under the directory of the project.

    • Any of MySQL, PostgreSQL, SQLServer
      Uncomment the relative line from build.gradle.

Enable the Gradle
  1. Right click the project, and click Configure > Add Gradle Nature to turn the project to a gradle project.

  2. Click the Gradle > Refresh Gradle Project to start downloading the dependencies.

Modify Settings of the Project
  1. Get to the project’s Properties window, and do the following operations.

  2. Modify the context root from Web Project Settings according to the project name.

  3. On the page of Project Facets, check the following items and set the versions.

Project FacetVersion

Runtimes

Apache Tomcat v8.5

Java

1.8 (11 for Java 11)

Dynamic Web Module

3.1

Settings for mtp-service-config.xml
  1. Modify the settings from src/resources/mtp-service-config.xml. Please change the following items.

<serviceDefinition>
    <inherits>/mtp-core-service-config-oracle.xml</inherits> (1)
    <!-- If use mysql, inherits mtp-core-service-config-mysql.xml for convenience. -->
    <!--
    <inherits>/mtp-core-service-config-mysql.xml</inherits>
    -->
    <!-- If use postgresql, inherits mtp-core-service-config-postgre.xml for convenience. -->
    <!--
    <inherits>/mtp-core-service-config-postgre.xml</inherits>
    -->
    <!-- If use sqlserver, inherits mtp-core-service-config-sqlserver.xml for convenience. -->
    <!--
    <inherits>/mtp-core-service-config-sqlserver.xml</inherits>
    -->

    ・・・

    <service>
        <interface>org.iplass.mtp.impl.rdb.connection.ConnectionFactory</interface>
        <!-- DriverManager base ConnectionFactory -->
        <class>org.iplass.mtp.impl.rdb.connection.DriverManagerConnectionFactory</class>

        <!-- ■ your rdb setting 1 ■ -->
        <!-- for oracle --> (2)
        <property name="url" value="jdbc:oracle:thin:ADDRESS:PORT:DB" /> (3)
        <property name="user" value="XXXXX" />
        <property name="password" value="XXXXX" />
        <property name="driver" value="oracle.jdbc.driver.OracleDriver" />

        ・・・

    </service>

    ・・・

    <service>
        <interface>org.iplass.mtp.impl.lob.LobStoreService</interface>

        <!--
            To save Binary data in files, uncomment the following comments.
            FileLobStore is mandatory for MySQL and PostgreSQL.
            ※The following setting is to store Binary data in file, and LongText data in RDB.
            If it is need to store LongText data in files, please also set the setting of longTextStore to FileLobStore.
         -->
        <!--
        <property name="binaryStore" class="org.iplass.mtp.impl.lob.lobstore.file.FileLobStore"> (4)
            <property name="rootDir" value="[setYourBinaryFileStoreRootPath]" /> (5)
            <property name="overwriteFile" value="false" />
        </property>
        <property name="longTextStore" class="org.iplass.mtp.impl.lob.lobstore.rdb.RdbLobStore">
        </property>
         -->

        ・・・

    </service>

    ・・・

    <service>
        <interface>org.iplass.mtp.impl.mail.MailService</interface>

        ・・・

        <!-- ■ for develop only (additional="true) ■ -->
        <!-- To enable the debug mode for sending mails, Please uncomment the following code.-->
        <!--
        <property name="listener" class="org.iplass.mtp.mail.listeners.LoggingSendMailListener" additional="true"/> (6)
        -->
    </service>

    ・・・

</serviceDefinition>
1Change depending on the DB in use.
2Comment/Uncomment depending on the DB in use.
3Change along with the created DB scheme.
4Uncomment it if using MySQL or PostgresSQL.
5Set the path to store binary files.
6Uncomment it only for development environment.

At this point, the project is successfully deployed.

Tenant is like the conceptual division of the server. We have to specify which tenant to access when using iPLAss. Let’s use the GUI tools to create a Tenant.

  1. Run the Gradle task runTenantBatch .

  2. Click the Create Default Tenant on the shown interface.

  3. On the dialog, input name, AdminUserId, AdminUserPassword and click Create.

before creating the tenant, please make sure to configure mtp-service-config.xml and set the DBA user with corresponding privileges.

We will start the server, and access the Tenant from the browser.

  1. Right click the root of the project in Eclipse, choose Run As > Run on Server. (Later on you can start from Server tab)

  2. Select Tomcat v8.5 Server then click on [Finish]. If Always use this server when running this project is checked, the server will directly go for the same setting on forth.

  1. Once the server is running, access the following URL by the browser.

http://localhost:8080/Context_Name/Tenant_Name/gem/

For instance, if the project was created with contextRoot being sampleApp, and tenant being sampleTenant, then the URL will be:

http://localhost:8080/sampleApp/sampleTenant/gem/

If the web application started normally, the following login page will be presented. Please use the manager ID and password specified when creating the tenant to log in.

execute login en

For the people who are first time with iPLAss, please begin your journey with our Tutorial.