Mail System

Introduction

Ontimize Boot is a framework that allows you to simplify the configuration of a project made with Ontimize EE, in a fast and efficient way. The email system allows you to send mail from the server with a simple configuration.

Prerequisites

There are 2 options to follow this tutorial, clone the repository with the initial state and follow the tutorial step by step, or download the final example and see which files are new and which have been updated.

Initial project

/$ git clone https://github.com/ontimize/ontimize-examples
/ontimize-examples$ cd ontimize-examples
/ontimize-examples$ git checkout boot-mail-initial

Final example

/$ git clone https://github.com/ontimize/ontimize-examples
/ontimize-examples$ cd ontimize-examples
/ontimize-examples$ git checkout boot-mail

Configuring email service with Ontimize Boot

In this complete tutorial, we are going to create a backend for an application from scratch, including the database with different tables, configuring the server, creating the necessary DAO files and implementing the service. At the end of the tutorial, we will even be testing that our mailing system is fully operational and functional.

DB configuration

If the configuration table does not exist in the DB, it can be created with the following command:

Sentencia SQL (HSQL)

1
CREATE TABLE TSETTING(ID_SETTING INTEGER GENERATED BY DEFAULT AS IDENTITY NOT NULL PRIMARY KEY,SETTING_KEY LONGVARCHAR,SETTING_VALUE LONGVARCHAR,SETTING_COMMENTLONGVARCHAR);

We fill in this table with the data that applies to each specific mail server, in this example, we will use the following:

SETTING_KEY	SETTING_VALUE	SETTING_COMMENT
mail_host	localhost	Server host
mail_port	2525	Email server port
mail_protocol	smtp	Mailing protocol
mail_user	my.mail@example.com	User for sending
mail_password	my_password	Mail server password
mail_encoding	UTF-8	Encoding of mails
mail_properties	mail.smtp.auth:true; mail.smtp.starttls.enable:true;	Mail properties

Sentencia SQL (HSQL)

1
2
3
4
5
6
7
INSERT INTO TSETTING (SETTING_KEY, SETTING_VALUE, SETTING_COMMENT) VALUES('mail_host', 'localhost', 'Server host');
INSERT INTO TSETTING (SETTING_KEY, SETTING_VALUE, SETTING_COMMENT) VALUES('mail_port', '2525', 'Email server port');
INSERT INTO TSETTING (SETTING_KEY, SETTING_VALUE, SETTING_COMMENT) VALUES('mail_protocol', 'smtp', 'Mailing protocol');
INSERT INTO TSETTING (SETTING_KEY, SETTING_VALUE, SETTING_COMMENT) VALUES('mail_user', 'my.mail@example.com', 'User for sending');
INSERT INTO TSETTING (SETTING_KEY, SETTING_VALUE, SETTING_COMMENT) VALUES('mail_password', 'my_password', 'Mail server password');
INSERT INTO TSETTING (SETTING_KEY, SETTING_VALUE, SETTING_COMMENT) VALUES('mail_encoding', 'UTF-8', 'Encoding of mails');
INSERT INTO TSETTING (SETTING_KEY, SETTING_VALUE, SETTING_COMMENT) VALUES('mail_properties', 'mail.smtp.auth:true;mail.smtp.starttls.enable:true;', 'Mail properties');

The implementation interface contains multiple methods, to which we must give permissions, if our application has permissions:

Sentencia SQL (HSQL)

1
2
3
4
INSERT INTO TSERVER_PERMISSION (PERMISSION_NAME) VALUES('com.ontimize.jee.server.services.mail.IMailServiceServer/sendMail');
INSERT INTO TSERVER_PERMISSION (PERMISSION_NAME) VALUES('com.ontimize.jee.server.services.mail.IMailServiceServer/sendMailWithoutAttach');
INSERT INTO TROLE_SERVER_PERMISSION (ID_ROLENAME, ID_SERVER_PERMISSION) VALUES((SELECT ID_ROLENAME FROM TROLE WHERE ROLENAME='admin'), (SELECT ID_SERVER_PERMISSION FROM TSERVER_PERMISSION WHERE PERMISSION_NAME='com.ontimize.jee.server.services.mail.IMailServiceServer/sendMail'));
INSERT INTO TROLE_SERVER_PERMISSION (ID_ROLENAME, ID_SERVER_PERMISSION) VALUES((SELECT ID_ROLENAME FROM TROLE WHERE ROLENAME='admin'), (SELECT ID_SERVER_PERMISSION FROM TSERVER_PERMISSION WHERE PERMISSION_NAME='com.ontimize.jee.server.services.mail.IMailServiceServer/sendMailWithoutAttach'));

Adding dependencies

Now we need to add the correct dependency in the correct pom.xml:

ontimize-examples
- projectwiki-api
  - src
    - main
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        api
        
        core
        
        service
        
        ICandidateService.java
        
        IUserService.java
  - pom.xml
- projectwiki-boot
  - src
    - main
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        ServerApplication.java
      - resources
        
        application.yml
  - pom.xml
- projectwiki-model
  - src
    - main
      - db
        
        templateDB.properties
        
        templateDB.txt
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        model
        
        core
        
        dao
        
        CandidateDao.java
        
        UserDao.java
        
        UserRoleDao.java
        
        service
        
        CandidateService.java
        
        UserService.java
      - resources
        
        dao
        
        CandidateDao.xml
        
        placeholders.properties
        
        RoleDao.xml
        
        RoleServerPermissionDao.xml
        
        ServerPermissionDao.xml
        
        UserDao.xml
        
        UserRoleDao.xml
  - pom.xml
- projectwiki-ws
  - src
    - main
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        ws
        
        core
        
        rest
        
        CandidateRestController.java
        
        MainRestController.java
        
        TestRestController.java
        
        UserRestController.java
  - pom.xml
- .gitignore
- pom.xml
- README.md

...
<dependencies>
...	
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mail</artifactId>
  </dependency>
...
</dependencies>
...

Server Configuration

To configure this service, a new configuration fragment shall be added to the application.yml file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
ontimize:
   mail:
      ref-repository: OCSettingsDao
      filter-column-name: SETTING_KEY
      value-column-name: SETTING_VALUE
      query-id: default
      filter-column-value-encoding: mail_encoding
      filter-column-value-host: mail_host
      filter-column-value-port: mail_port
      filter-column-value-protocol: mail_protocol
      filter-column-value-user: mail_user
      filter-column-value-password: mail_password
      filter-column-value-java-mail-properties: mail_properties
      engine: default

This configuration indicates the keys and values to be stored in the database. The database table is the one corresponding to the bean described in the refRepository: OCSettingsDao attribute (in this case, OCSettingsDao), which can be seen in the table TSETTING attribute (for this example, TSETTING) of the *.xml configuration file of the bean (OCSettingsDao.xml). The keys would be stored in the SETTING_KEY column, the values in the SETTING_VALUE column and the rest of the attributes map the keys that exist in the database.

In addition, the packet that will be scanned to look for the implementation of the email service is indicated.

Creation of DAO files

Let’s create a DAO (Data Access Object) in the projectwiki-model module to use as a model of this database table. The DAO is composed by 2 files, a file with extension *.xml and a *.java file.

ontimize-examples
- projectwiki-api
  - src
    - main
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        api
        
        core
        
        service
        
        ICandidateService.java
        
        IUserService.java
  - pom.xml
- projectwiki-boot
  - src
    - main
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        ServerApplication.java
      - resources
        
        application.yml
  - pom.xml
- projectwiki-model
  - src
    - main
      - db
        
        templateDB.properties
        
        templateDB.txt
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        model
        
        core
        
        dao
        
        CandidateDao.java
        
        OCSettingsDao.java
        
        UserDao.java
        
        UserRoleDao.java
        
        service
        
        CandidateService.java
        
        UserService.java
      - resources
        
        dao
        
        CandidateDao.xml
        
        OCSettingsDao.xml
        
        placeholders.properties
        
        RoleDao.xml
        
        RoleServerPermissionDao.xml
        
        ServerPermissionDao.xml
        
        UserDao.xml
        
        UserRoleDao.xml
  - pom.xml
- projectwiki-ws
  - src
    - main
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        ws
        
        core
        
        rest
        
        CandidateRestController.java
        
        MainRestController.java
        
        TestRestController.java
        
        UserRestController.java
  - pom.xml
- .gitignore
- pom.xml
- README.md

In our *.xml file we will indicate the database table for which DAO belongs, the data source from which we collect the information (e.g. the database connection that contains this table) and the schema to which the table belongs.

OCSettingsDao.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?xml version="1.0" encoding="UTF-8"?>
<JdbcEntitySetup
    xmlns="http://www.ontimize.com/schema/jdbc"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.ontimize.com/schema/jdbc http://www.ontimize.com/schema/jdbc/ontimize-jdbc-dao.xsd"
    catalog="" schema="${mainschema}" table="TSETTING"
    datasource="mainDataSource" sqlhandler="dbSQLStatementHandler">
    <DeleteKeys>
        <Column>ID_SETTING</Column>
    </DeleteKeys>
    <UpdateKeys>
        <Column>ID_SETTING</Column>
    </UpdateKeys>
    <GeneratedKey>ID_SETTING</GeneratedKey>
</JdbcEntitySetup>

In the *.java file we indicate that it is a repository whose name will be OCSettingsDao, through the annotation @Repository. With the annotation @Lazy, we will indicate that the load is delayed until it is completely necessary (improving in that way the performance), and the annotation @ConfigurationFile allows us to configure this DAO using the XML file and an additional file where some common characteristics to several DAOs can be stored. like the scheme to which they belong.

OCSettingsDao.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
package com.ontimize.projectwiki.model.core.dao;

import org.springframework.context.annotation.Lazy;
import org.springframework.stereotype.Repository;

import com.ontimize.jee.server.dao.common.ConfigurationFile;
import com.ontimize.jee.server.dao.jdbc.OntimizeJdbcDaoSupport;

@Repository("OCSettingsDao")
@Lazy
@ConfigurationFile(configurationFile = "dao/OCSettingsDao.xml", configurationFilePlaceholder = "dao/placeholders.properties")
public class OCSettingsDao extends OntimizeJdbcDaoSupport {

  public OCSettingsDao() {
    super();
  }

}

Implementation in an existing service

To use this service in another service (e.g. to send a mail when a new record is created), just add a variable of type com.ontimize.jee.common.services.mail.IMailService and annotate it with @Autowired.

ontimize-examples
- projectwiki-api
  - src
    - main
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        api
        
        core
        
        service
        
        ICandidateService.java
        
        IUserService.java
  - pom.xml
- projectwiki-boot
  - src
    - main
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        ServerApplication.java
      - resources
        
        application.yml
  - pom.xml
- projectwiki-model
  - src
    - main
      - db
        
        templateDB.properties
        
        templateDB.txt
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        model
        
        core
        
        dao
        
        CandidateDao.java
        
        OCSettingsDao.java
        
        UserDao.java
        
        UserRoleDao.java
        
        service
        
        CandidateService.java
        
        UserService.java
      - resources
        
        dao
        
        CandidateDao.xml
        
        OCSettingsDao.xml
        
        placeholders.properties
        
        RoleDao.xml
        
        RoleServerPermissionDao.xml
        
        ServerPermissionDao.xml
        
        UserDao.xml
        
        UserRoleDao.xml
  - pom.xml
- projectwiki-ws
  - src
    - main
      - java
        
        com
        
        ontimize
        
        projectwiki
        
        ws
        
        core
        
        rest
        
        CandidateRestController.java
        
        MainRestController.java
        
        TestRestController.java
        
        UserRestController.java
  - pom.xml
- .gitignore
- pom.xml
- README.md

...
import com.ontimize.jee.common.services.mail.IMailService;
...
@Service("CandidateService")
@Lazy
public class CandidateService implements ICandidateService {
...
@Autowired
private IMailService mailService;
 ...
@Override
public EntityResult candidateInsert(Map<String, Object> attrMap) throws OntimizeJEERuntimeException {
	EntityResult toRet = this.daoHelper.insert(this.candidateDao, attrMap);

	if ((toRet.getCode() != EntityResult.OPERATION_WRONG)) {

		Runnable runnable = () -> {

		List<String> receiverList = new ArrayList<String>();
		receiverList.add("receiver@example.com");
		StringBuilder builder = new StringBuilder();
		builder.append("Created new user.");
		try {
			this.mailService.sendMailWithoutAttach("my.mail@example.com", receiverList, "New candidate",
				builder.toString());
		} catch (OntimizeJEEException e) {
	}
	};
			
  DelegatingSecurityContextRunnable wrappedRunnable = new DelegatingSecurityContextRunnable(runnable);
	  new Thread(wrappedRunnable).start();
  }

return toRet;
}
 ...

Note: For space reasons, the entire files are not included, only the code snippets related to the tutorial. The … in the code snippets indicate that there may be unrelated code before or after them.

Checking the sending of mails

In order to check that the created service is indeed sending mails, we will use an external service called FakeSMTP, is a free Fake SMTP Server with GUI for testing emails in applications easily.

To do this, we enter this link and clone the repository it indicates into the workspace where we have our project.

We launch the DB and the server. Next, open a console and move to the path where FakeSMTP was downloaded:

1
2
3
...\FakeSMTP> mvn package-Dmaven.test.skip
...\FakeSMTP> cd target
...\FakeSMTP\target> java -jar fakeSMTP-2.1-SNAPSHOT.jar -s -p 2525

Command	Meaning	34
fakeSMTP-VERSION.jar	Downloaded version.
-s	Launch the server.
- p 2525	Launch the application on the port indicated.

Now we can use an application like Postman to execute different REST requests to our project.

Use REST request

The requests contains the following structure: localhost:33333/candidates/candidate

Element	Meaning
localhost:33333	Indicates the host
/candidates	Indicates the service to be queried
/candidate	Indicates the DAO that will access that service

The request types can only be GET, POST, PUT, DELETE.

Below are examples of request for candidates (CANDIDATES).

The authorization used for these requests is authorization of the type BASIC.

In both cases, the access must be done with a user and password example:

    User: demo
Password: demouser

Request type	Query	URL	Service method	Body request
POST	insert	localhost:33333/candidates/candidate	candidateInsert	Example below

Body request:

{
    "data": {
        "PHONE": "555-444-8888",
        "BIRTHDAY": 788224700000,
        "SURNAME": "Wilson",
        "EMAIL": "wwiilsoon@example.org",
        "SPECIALTIES": "C#",
        "NAME": "William",
        "DNI": "88643946Z"
    },
    "sqltypes": {
        "SPECIALTIES": 12,
        "LINKEDIN": 12,
        "PHONE": 12,
        "EXPERIENCE_LEVEL": 4,
        "STATUS": 4,
        "EMAIL": 12,
        "WAGE_LEVEL": 2,
        "DNI": 12,
        "ID": 4,
        "ORIGIN": 4,
        "EDUCATION": 4,
        "COMMENT": 12,
        "PROFILE": 4,
        "SURNAME": 12,
        "NAME": 12,
        "BIRTHDAY": 91
    }
}