Táto služba realizuje posielanie emailov cez SMTP protokol. Služba sa štartuje z adresára D2000_EXE/bin64/smtp.exe (alebo v prípade Linuxu: D2000_EXE/bin64/smtp).

Parametre

...

príkazového riadku

Parametre služby sú nasledovné:

• -c <connectionString> – adresa, na ktorej počúva proces D2Connector.exe na príchádzajúce JAPI spojenia. Ak je JAPI spojenie šifrované, za bodkočiarkou sa nachádza cesta k súboru s certifikátom. Ak je využitá redundancia, parameter je možné zadať viackrát a vymenovať tak všetky body pripojenia. Príklady hodnoty parametra:
  server.domain.sk:3120
  172.16.1.3:3121
  srvapp120v:3120;certifikat.crt
• -w <applicationName> – voliteľné meno inštancie služby, implicitne je to SMTP SELF(.SVCEMS -EMail Service)
• --logging-logDir directory <logging directory> - voliteľná cesta k logovaciemu adresáru, implicitne je hodnota nastavená na relatívnu cestu ../log do logovacieho adresára D2000. Pokiaľ adresár na tejto relatívnej ceste neexistuje loguje sa do vytvoreného adresára ./log v pracovnom adresári, pod ktorým je proces spustený
• --reconnectTimeout <number of seconds> - počet sekúnd za koľko sa proces pokúsi znova pripojiť na D2Connector.exe, implicitná hodnota je 10 sekúnd sekúnd

Okrem parametrov zadávaných v príkazovom riadku je možne konfigurovať aj samotný JVM proces, v ktorom služba beží cez súbor smtp.cfg, ktorý sa musí nachádzať v tom istom adresári - D2000_EXE/bin64/. V súbore je možné zadefinovať parametre spôsobom zdokumentovaným pre Jar2Exe nástroj. Napríklad zapnutie ladenia celej sieťovej komunikácie pre JVM je možné nasledujúcou konfiguráciou smtp.cfg.

option -Djavax.net.debug=all

ESL rozhranie pre posielanie mailov

Služba poublikuje publikuje funkcionalitu cez nasledovné ESL rozhranie:

RPC PROCEDURE [_hTC, TC_B] OpenConnection(IN TEXT _host, IN INT _port, IN TEXT _fromdefaultFrom, IN BOOL _enableSsl, IN TEXT _userName, IN TEXT _password, IN BOOL _disablePlainAuthenticationSend, IN TEXT _additionalProperties)
RPC PROCEDURE [_hTC, TC_B] OpenConnectionFromProps(IN TEXT _properties)  
RPC PROCEDURE [_hTC, TC_C] SendMail(IN INT _mailId, IN TEXT _from, IN TEXT _to, IN TEXT _cc, IN TEXT _bcc, IN TEXT _subject, IN TEXT _body) 
RPC PROCEDURE [_hTC, TC_E] CloseConnection    

...

RPC PROCEDURE [_hTC, TC_C] OnConnectionOpened
RPC PROCEDURE [_hTC, TC_E] OnConnectionClosed(IN BOOL _closedWithError, IN TEXT _errorMessage, IN TEXT _errorDetail)
RPC PROCEDURE [_hTC, TC_C] OnMailSent(IN INT _mailId)
RPC PROCEDURE [_hTC, TC_C] OnMailSendingFailed(IN INT _mailId, IN TEXT _errorMessage, IN TEXT _errorDetail)     

Otvorenie SMTP spojenia cez metódy OpenConnection a OpenConnectionFromProps

Metóda OpenConnection realizuje pripojenie na SMTP server cez parametre metódy. Interne je posielanie emailov realizované cez knižnicu JavaMail , ktorá sa konfiguruje cez množinu vyše 50 konfiguračných parametrov. Väčšinu z nich je potrebné explicitne  zadávať  iba vo výnimočných prípadoch. Z tohto dôvodu RPC metóda OpenConnection má iba najpoužívanejšie parametre , zvyšok je možné zadefinovať cez parameter _additionalProperties vo formáte .properties súborov. Alternatívne je možné inciovať SMTP spojenie iba výlučne cez tieto nastavenia metódou OpenConnectionFromProps cez textový parameter _properties s nasledovným obsahom:

mail.smtp.host=mail.xyz.com
mail.smtp.port=445
mail.smtp.from= abc@xyz.com 
mail.smtp.user=abc
mail.smtp.password=abcPassword 
mail.smtp.ssl.enable=true


# debugovanie posielanych mailov do logu
mail.debug=true

Uspešné otvorenie SMTP spojenia cez metódy OpenConnection/OpenConnectionFromProps je notifikované volaním metódy OnConnectionOpened v rámci interfacu I.SMTP_Client_v1, ktorý musí klient implementovať. Ukončenie SMTP spojenia alebo jej zlyhania je notifikované cez metódu OnConnectionClosed.

Poslanie mailu - metóda SendMail

Metóda SendMail implementuje posielanie emailu. Prvý parameter _mailId označuje identifikátor mailu ktorý vyplní klient pri volaní SendMail metódy. O úspechu resp. zlyhaní poslania mailu je klient notifikovaný cez metódy OnMailSent a OnMailSendingFailed rozhrania I.SMTP_Client_v1.

Príklad použitia ESL rozhrania na posielanie mailov

Nasledovný kód predstavuje príklad jednoduchej mailovej služby v aplikácii. Pre poslanie mailu stačí zavolať RPC procedúru SendMail. Event E.MailService interne používa konverzáciu s procesom SELF.EMS, ktorú udržuje otvorenú a pri rozpade spojenia ju automaticky obnoví. Zároveň, aby nedošlo k zahodeniu nejkého mailu, v kontajneri uchováva všetky doteraz neodoslané maily a pri opätovnom nadviazaní spojenia s procesom SELF.EMS sa ich automaticky pokúsi znova odoslať.

IMPLEMENTATION I.SMTP_Client_v1

INT _hCnt, _hTC, _nextMailId
BOOL _hasTC

; Po nadviazaní spojenia so SMTP serverom sa pokúsi odoslať všetky doteraz neodoslané maily
IMPLEMENTATION RPC PROCEDURE [_hTC, TC_C] I.SMTP_Client_v1^OnConnectionOpened
  RECORD NOALIAS (SD.MailData) _mail
  INT _count, _i

  _hasTC := @TRUE
  CNT_CNVTOARRAY _hCnt
  CNT_GETNR _hCnt, _count
  FOR _i = 1 TO _count DO_LOOP
    CNT_GETITEM _hCnt, _i, _mail
    CALL Internal_SendMail(_mail)
  END_LOOP
END OnConnectionOpened

IMPLEMENTATION RPC PROCEDURE [_hTC, TC_E] I.SMTP_Client_v1^OnConnectionClosed(IN BOOL _closedWithError, IN TEXT _errorMessage, IN TEXT _errorDetail)
  IF _closedWithError THEN
    LOGEX _errorMessage
  ENDIF
  CALL [_hTC] I.SMTP_Service_v1^CloseConnection
  _hasTC := @FALSE
END OnConnectionClosed

; Pri úspešnom odoslaní mailu ho vymaže z kontajneru
IMPLEMENTATION RPC PROCEDURE [_hTC, TC_C] I.SMTP_Client_v1^OnMailSent(IN INT _mailId)
  CNT_DELETE _hCnt, _mailId
END OnMailSent

; Pri neúspešnom odoslaní mailu zaloguje chybu
IMPLEMENTATION RPC PROCEDURE [_hTC, TC_C] I.SMTP_Client_v1^OnMailSendingFailed(IN INT _mailId, IN TEXT _errorMessage, IN TEXT _errorDetail)
  LOGEX _errorMessage
END OnMailSendingFailed

RPC PROCEDURE [_hTC, ERROR] OnConversationAborted
  _hasTC := @FALSE
END OnConversationAborted

; Nadviazanie spojenia so SMTP serverom, ak už neexistuje
PROCEDURE Internal_InitConnection
  IF !_hasTC THEN
    CALL [(0)] I.SMTP_Service_v1^OpenConnection("mail.example.com", 25, "", @FALSE, "user", "secret", @FALSE, "") ASYNC ON SELF.EMS TC_B _hTC
  ENDIF
END Internal_InitConnection

PROCEDURE Internal_SendMail(IN RECORD NOALIAS (SD.MailData) _mail)
  TEXT _from
  _from := "no-reply@ipesoft.com"
  CALL [_hTC] I.SMTP_Service_v1^SendMail(_mail[1]^id, _from, _mail[1]^to, "", "", _mail[1]^subject, _mail[1]^message) ASYNC TC_C
END Internal_SendMail

; RPC volaná "z vonku"
RPC PROCEDURE SendMail(IN TEXT _to, IN TEXT _subject, IN TEXT _message)
  RECORD NOALIAS (SD.MailData) _mail

  _mail[1]^id := _nextMailId
  _mail[1]^to := _to
  _mail[1]^subject := _subject
  _mail[1]^message := _message
  CNT_INSERT _hCnt, _mail[1]^id, _mail
  _nextMailId := _nextMailId + 1

  CALL Internal_InitConnection
  IF _hasTC THEN
    CALL Internal_SendMail(_mail)
  ENDIF
END SendMail

; Inicializačná časť - vytvorenie kontajnera a konverzácie
BEGIN
  CNT_CREATE _hCnt
  _hasTC := @FALSE
  _nextMailId := 1
  CALL Internal_InitConnection
END