Installation
- Spring Tool Suite
- Maven Installation
- STS Conventions
- Formatter
- Imports
- Save Actions
- Code Template configuration
- Other configurations
- MySQL Configuration
- STS GitHub configuration
- Configuring Maven in STS
- Configuring SSL certificate
- Properties file Configuration
- Configuration of tomcat for Pentaho
- Run configuration
DB Engine
In this manual you will find the use of the basic tools used for the development of MARLO application. Tools for setting up your local environment are:
- Spring Tool Suite.
- Maven.
- Freemarker.
Spring Tool Suite (STS) is an application development framework built from Eclipse, it provides a work environment based on the model view-controller.
To install Eclipse STS, initially check if you have installed a latest version of Java SE Development Kit (JDK); 7u is recommended or higher; if you do not have, you must download the latest version on the official website and then install it using the instructions on the following website.
http://www.oracle.com/technetwork/es/java/javase/downloads/index.html
Once the JDK is installed, proceed to download the Spring STS tool, entering to the official website https://spring.io/tools where you will be able to download the current version of the installation package, depending on the choice of your machine architecture (32 or 64 bit). Take in mind that Java and STS tool should have the same architecture(32 or 64 bit)
Once you have downloaded the installation file, proceed to unzip the .zip file, with the unzip tools (Winrar, Winzip, 7-zip etc.). After you have unzipped, save it in a safe location as this will contain the files necessary for the implementation of the platform.
For easy file location, it is recommended to create a shortcut to the desktop application, search this path \spring-tool-suite-3.8.1.RELEASE-e4.6-win32-x86_64\sts-bundle\sts-3.8.1.RELEASE and create a shortcut to the desktop of STS.exe file.
This makes it easier to access the program from your desktop, open the STS file, which will display the following welcome application interface.
Once you have configured STS, proceed to configure Maven, the tool used for versioning of libraries and application packaging. Install it using the following steps:
- Download the installation file from the official website, https://archive.apache.org/dist/maven/maven-3/3.3.3/binaries/ and choose the version 3.3.3 (apache-maven-3.3.3-bin.zip).
-
Unzip the file to a folder where you can save it, it is recommended to save it in the filesystem under path C: \ Program Files \ Apache Software Foundation \ apache-maven-3.3.3.
-
Then configure the system environment variables by right clicking on My Computer -> Properties -> Advanced Settings -> Environment Variables
Once on the previous window, set M2_HOME and M2 variables of the Maven tool.
In windows there are two types of environment variables: user variables and system variables.
System variables are always set when a user logs on and can not be changed by any user.
User variables: take precedence on system variables, the user must add, modify or delete them. They have an exceptional rule precedence over the PATH variable, this is necessary for the proper functioning of the application, and is constructed from the concatenation of the system variables + user variables.
User variables: variables take precedence over system, the user must add, modify or delete them. They have an exceptional rule of precedence with respect to the PATH variable, this is necessary for the proper functioning of the application, and is constructed from the concatenation of the system variable + user variable.
To setup project user variables are changed.
To configure them perform the following steps:
- Confirm that the JAVA_HOME variable is functioning properly by reviewing if user variable is created with the correct path of JDK. If this was not created, proceed to configure it.
- After, create the user variable M2_HOME by clicking on NEW, where there options for entering values. In the Variable name field, enter M2_HOME and enter your Maven installation path in the Variable value field as shown in the figure below.
- For the user variable M2, perform the above steps.
- Add the PATH variable and add the same variable M2.
Finally confirm if Maven is installed on your system, open the Windows cmd console and type the command mvn --version as shown in the figure below.
Conventions in the development of MARLO application, are used to manage a standard coding of the content of our STS, they will be governed by parameters that have been initially established; these parameters indicate indentation of code, naming of the variables and format of comments, among others. Now let us demonstrate the procedure for setting these conventions.
The process consists of importing certain established styles in the application code, to import these styles do the following process:
Go to Window-Preferences->Java>Code Style->Formatter
Then import the file containing the code style to use, by clicking on import button and import the file CCAFS-java-style-config.xml from the repository in configuration folder (https://github.com/CCAFS/MARLO/tree/dev/configuration).
Then the Java convention that we have imported appears, click on OK.
For JavaScript perform the above process/steps, but change the configuration path. Window-Preferences->JavaScript>Code Style->Formatter and import the file ccafs-javascript-style.xml. from the repository in configuration folder (https://github.com/CCAFS/MARLO/tree/dev/configuration).
For this enter the path Window-Preferences->Web>CSS Files, where we edit the following options:
Modify the Encoding option ISO 10646/Unicode(UTF-8)
Enter the path Window-Preferences->Web->CSS Files->Editor, and edit the following options:
-
In the Formatting block, set Line width option to 120; then select the three checkboxes (Insert line, Insert whitespace and disable), then select the Indent using spaces option and finally set Indentation size to 2.
-
In the Capitalization style block, select the following options.
Block Identifier-> Uppercase option Block Type selections-> Lowercase option Block Property name-> Lowercase option Block Property value-> Lowercase option
The process consists of organizing the order the imported classes in the Java code. To do this follow these steps:
Go to Window->Preferences->Java>Code Style->Organize Imports
Click on the Import button, then import the attachment CCAFS-java-style.importorder.
Then review the configured options.
This process will help us save automatic code corrections once you save. Go to path Window-Preferences->Java->Editor->Save Actions, enable Perform the selected actions on save -> Format source code -> Format all lines. Then enable Additional actions, then click the configure button, modify the path of each of the options. In the pop-up window Additional Save Actions, modify options on each window tab.
- Select the checkbox Correct indentation.
- Select the Sort members checkbox.
- Then click OK button.
-
In the Control statements block select the checkbox “Use blocks in if/while/for/do statements”- Always option.
-
In the expressions block uncheck the “Use parentheses in expressions’ checkbox and uncheck the ‘Convert for loops to enhanced’.
-
In blocks “Variable declarations” and “Functional interfaces” leave the default options.
-In the ‘Non static accesses’ block, select the ‘Use this qualifier for method accceses’ option and then ‘Always’ option. ‘Always’.
Select the ‘Add missing Annotations’ option.
In this section leave the default options, check those that corresponds to the image below.
Properly review the conventions for the general Save Actions options.
Enter the path Window-Preferences->JavaScript->Editor->Save Actions check Perform the selected actions on save and Additional actions then select the Configure button, and in the pop-up edit the following options:
Select the Use blocks if/while/for/do statements option, then select Always option.
Select all checkboxes in this section except Vars.
Check the Remove trailing whitespace option and then select All lines option.
In this section check if the options were set correctly.
Then configure the default Java files:
Enter the path Window-Preferences->Java>Code Style->Code Template and in the window that appears go to the path Code->New Java Files, then click on the Edit button.
Enter the following header structure for classes in Java and click on OK.
License Text:
/*****************************************************************
* This file is part of Managing Agricultural Research for Learning &
* Outcomes Platform (MARLO).
* MARLO is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* at your option) any later version.
* MARLO is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
* You should have received a copy of the GNU General Public License
* along with MARLO. If not, see <http://www.gnu.org/licenses/>.
*****************************************************************/
- Go to path Window-Preferences->General>Editors->Text Editors, check Show print margin then change Displayed tab width to 2, and Print margin column to 120.
-Perform another configuration in the Workspace, go to path Window-Preferences->General>Workspace, where we set in Other UTF-8 option as shown in the figure below.
MySQL database engine must be installed before the tool accesses the data, in this case MySQL Workbech, create marlodb database; then import the attached marlo db 08-04-2016.sql file sql script.
This database is prepared for system operation.
To configure the GitHub, first have the tool installed on your computer, this can be done from the official website https://windows.github.com/.
Then from the STS, click on File->Import->Git->Project From Git.
Then select Clone URI as shown in the figure below.
In the URL field enter the project path en github https://github.com/CCAFS/MARLO.git
Then add all the branches (dev, master and test) and click Next.
Then configure the Workspace (Path where the project is installed).
Then select Import as general project and Working Directory.
Finally enter the name of the project and click Finish.
Delete the project from Eclipse, but not from the disk:
Select the path File->Import -> Maven -> Existing Maven Projects.
Then click on browse (Root Directory), select Workspace, search for the MARLO folder where the project was downloaded and select all dependencies and click Finish. (The screenshot may be out of date, make sure to always select all dependencies)
Go to path Run -> Run Configurations -> Maven Build and double click. In Maven Runtime click Configure.
Click Add and add the path to Maven installation folder, add a name and click Finish.
Locate the project location into workspace and execute the following command mvn clean install.
The MapStruct library, which is used to map between DTOs, used by our REST api, and our Hibernate entities generates MapperImpl classes in the target/generated-sources/annotations directory. For these classes to be picked up easily and added to the classpath, it's recommended to install the maven-apt-1.4.0 plugin. Simply go to the Eclipse Marketplace and search for the plugin and install it.
You must configure the certificate of the application by copying the attached .keystore file into the …\Workspace\MARLO\marlo-web folder as shown in the figure below. In the File Explorer, rename the keystore file to .keystore. and it will remove the ending '.'
Note this section has changed as we are now using the spring profile functionality to load properties files
We are using spring profiles to configure our environments. This allows us to enable and/or disable functionality easily for different environments. When we start the JVM that MARLO runs in we need to set the spring profile by setting the active profile property as a JVM system property argument, e.g. -Dspring.profiles.active=dev
Locate the marlo-dev.properties.sample file in the package explorer STS placed in the path \ marlo-web \ src \ main \ resources \ config , create a copy of the file, and change the extension of the new file to marlo-dev.properties, after proceed to access the data to the database.
The two other files in this directory are used by maven properties for our test and production environments. If you wish to add a new shared environment just create a new file with the following pattern marlo-xxxx.properties, where xxxx = the name of the spring profile that you will activate via a JVM system property e.g -Dspring.profiles.active=pro Note Sensitive properties such as usernames and passwords should be obfuscated and overriden on the test or prod machines
Make a copy of the file context.xml.sample located under the folder /marlo-web/tomcat/ and paste it in the same folder with the name “context.xml”.
Configure the file with the following database parameters as per the screenshot below:
- userdatabase: Mysql user.
- databasePass: Mysql password.
- url: Hostname, port and database name.
- driver class name: Para mySQL8 usar "com.mysql.cj.jdbc.Driver".
Locate the path Run-> Run configurations on the left side search the Maven Build, right click and edit the settings.
In the main tab, add a base directory by clicking Browse Workspace and add marlo-web. Add Goals: tomcat7:run
-
Uninstall your current MySQL client. If exist
-
Download MySQL Installer community client: https://dev.mysql.com/get/Downloads/MySQLInstaller/mysql-installer-web-community-8.0.17.0.msi
-
Install and start MySQL Installer community client, select a custom setup type
-
Select only the MySQL server 8 product
-
We suggest you install the new MYSQL server in the following folder “D:/MYSQL” as it will facilitate the configuration of the system environment variables.
-
Execute the installation
-
Now, the installer will need to set up the installed database server. Select Standalone MySQL Server.
-
Keep the default network configuration as per the screenshot below. Please keep in mind to have uninstalled the old MySQL server in order to avoid conflicts in the installation.
-
Select legacy authentication method
-
Assign the password for the root account.
-
Check the tick button to Start the MySQL Server at System Startup box
-
Then, proceed to execute the setup in your system
-
Finish the installation and close the MySQL installer.
-
Open the environment variables into the system properties, you will find them using the search tool inside as per the image below.
-
Enter in Environment variables
-
Create a new system variable
-
Fill the system variables out with:
Variable name: MYSQL_HOME Variable Value: D:\MYSQL
-
Search the path system variable and push in edit.
-
Push in new and add the line %MYSQL_HOME%\bin. It depends of the directory installation, check the path of the bin folder.
-
To test if the environment variable was set up successfully, you can run the command mysql --version into the Command prompt, if the Command prompt doesn’t recognize the command, please restart your system.
-
Go to the MySQL folder (C:\ProgramData\MySQL\MySQL Server 8.0) and open the my.ini file in your notepad (notepad++ recommended) , and add the line log_bin_trust_function_creators=1 at the end of the file
-
To enable it this configuration you must restart MySQL service or restart your computer.
-
To finish the setup, modify the PROD and LOCAL migration bat files adding a new argument in the mysqldump, if not exist:
_mysqldump --column-statistics=0 --routines=true --single-transaction=TRUE -u %db_user% -p%db_pass% -h %db_hostname% %db_name% --ignore-table=%db_name%.auditlog > %db_name%backup.sql
It is recommended to use the BDeaver application. You can download it from the official website DBeaver.
To avoid constant loss of connection to the database, when configuring the connection define a keep-alive value of 30.
