Business Logic Components¶

Package Structure¶

The Java project has a directory structure for clear structuring of the various contents. A default is to separate the directory with the source code and the compiled class files. Usually, the folder names for Java EE projects are src and bin.

Notice for Eclipse:

Development environments such as Eclipse translate Java types from src folder into bin folder, and copy resources such as images and NLS files to the src folder on each build. Eclipse supports this structure by default if option Create separate folders for source and class files is activated in the dialog for a new Java project under Project layout.

Notice for NetBeans:

Under NetBeans the default structure is somewhat different and is closely linked to the build tool Ant. The folder src contains the default classes and resources, a second folder test the test classes and resources. The compiled Java classes are stored in the folder build/classes. The result of the build, a jar file in the case of a simple Java project, is located in the dist folder.

The directory structure also has a lib and resource folder. The libraries used by the Business Bot is stored in folder lib. The resource folder is divided into localization for language files, media for multimedial files, and templates for message templates. The project structure looks as follows:

BusinessBot<Projectname>
|- src
   |- Package <country.company.businesslogic.<application name>
   |- Package <country.company.businesslogic.<common>
   |- Package <country.company.businesslogic.<database> (optional)
   |- Package <country.company.businesslogic.plugin (required)
      |- PluginClient.java (required) (Schnittstelle)
   |- Package <country.company.businesslogic.<services>
|- classes
   |- extension.idx (Extension Point for the class loader)
   |- MANIFEST.MF (META Informationen)
|- lib (Bibliotheken)
   |- de.citunius.businesslogic.api-1.0.0.jar (Common API for the Business Bot Platform)
   |- de.citunius.businesslogic.api.messenger-1.0.0.jar (Generic Messenger API for the Business Bot Platform)
   |- de.citunius.businesslogic.api.sfb-1.0.0.jar (Skype for Business API for the Business Bot Platform)
   |- de.citunius.businesslogic.api.telegram-1.0.0.jar (Telegram Messenger API for the Business Bot Platform)
|- resources
   |- localization
      |- string_de.properties (Language labels for German)
      |- string_en.properties (Language labels for English)
      |- string.properties (Detault language labels)
   |- media
      |- images
         |- icon.png (Business Logic Icon)
   |- templates
      |- list.ftl (Template for Instant Messages - Template: List)
   build.xml (Apache Ant Build configuration)
   MANIFEST.MF (Default project META information)
   plugin.properties (META information for the plugin)

Important:

A Business Logic can use either the library Skype for Business API OR Telegram Messenger API, but NOT both libraries may be present in the lib directory of the project.

Plugin Manager¶

The Plugin Manager searches for the META information of the plugin which is defined in the manifest file classes/MANIFEST.MF. The MANIFEST.MF file contains the entries as shown in the following example:

Manifest-Version: 1.0
Implementation-Title: calculator Plugin #1
Implementation-Version: 1.2.0-SNAPSHOT
Plugin-Id: de.citunius.telegram.calculator
Built-By: ME
Created-By: Apache Maven 3.3.9
Plugin-Version: 1.0.0
Plugin-Provider: Citunius GmbH
Plugin-Class: de.citunius.businesslogic.plugin.PluginClient
Plugin-Dependencies: 
Implementation-Vendor-Id: de.citunius.plugins
Build-Jdk: 1.7.0_67
Specification-Title: calculator Plugin #1
Specification-Version: 1.2.0-SNAPSHOT
Archiver-Version: Plexus Archiver

In the sample manifest, a plugin with the Id de.citunius.telegram.calculator was defined with the class de.citunius.businesslogic.plugin.PluginClient and version 0.0.1. The plugin Id must be unique and correspond to the conventions ..., otherwise the registration of the plugin will be rejected. In addition, the plugin version must be compatible with Semantic Versioning (The Business Bot Platform uses jsemver as implementation for SemVer because it supports comparison of versions).

Another internal component of the Plugin Manager is the ExtensionFinder, which describes how the Plugin Manager finds the extension via the Extension Point. The DefaultExtensionFinder looks for the extension with an extension annotation in file META-INF/extensions.idx. The Business Bot Platform uses Java Annotation Processing to compile all classes of the extension at runtime, which are annotated with @Extension and create for this the corresponding Extension Index file.

Plugin Lifecycle¶

Each plugin passes through a pre-defined set of states. The PluginState defines all possible states. The primary plugin states are:

CREATED (The runtime knows the plugin is there. It knows about the plugin path, the plugin descriptor.)
ENABLED (The plugin can be used.)
DISABLED (The plugin cannot be used.)
STARTED (The Plugin.start() of the business logic has executed. A started plugin may contribute extensions.)
STOPPED (The Plugin.stop() of the business logic has executed.)
RESOLVED (The plugin is created. All the dependencies are created and resolved. The plugin is ready to be started.)

Plugin Lifecycle

The DefaultPluginManager contains the following logic:

All plugins are resolved and loaded
DISABLED plugins are NOT automatically STARTED by the Business Bot Platform, BUT you may manually start (and therefore enable) a DISABLED plugin by calling startPlugin on the Business Bot Platform instead of enablePlugin() + startPlugin()
Only STARTED plugins may contribute extensions. Any other state should not be considered ready to contribute an extension to the running system.

The differences between a DISABLED plugin and a STARTED plugin are:

A STARTED plugin has executed Plugin.start(), a DISABLED plugin has not.
A STARTED plugin may contribute extension instances to the Business Bot Platform, a DISABLED plugin may not.

DISABLED plugins still have valid class loaders and their classes can be manually loaded and explored, but the resource loading - which is important for inspection - has been handicapped by the DISABLED check.

Notice for Eclipse:

If you use Eclipse than make sure annotation processing is enabled at least for any projects registering objects using annotations. In the properties for your new project go to Java Compiler → Annotation Processing, check the Enable Project Specific Settings and make sure Enable annotation processing is checked.

Interface¶

The interconnection point of the Plugin Manager between the Business Bot Platform and the Business Logic takes place in class PluginClient located in package de.citunius.businesslogic.plugin. The class contains the methods start(), stop() and class BusinessBot that implements the interface BusinessBotInterface. This class defines the method handleIncomingMessage() for incoming messages from mobile user and method sendMessage() for outgoing messages from the business system. Parameters are passed using the HashMap pluginMap.

Business Logic Library¶

The following Business Logic libraries are delivered:

de.citunius.businesslogic.api-1.0.0.jar (Common API for the Business Bot Platform)
de.citunius.businesslogic.api.messenger-1.0.0.jar (Generic Messenger for the Business Bot Platform)
de.citunius.businesslogic.api.sfb-1.0.0.jar (Skype for Business API for the Business Bot Platform)
de.citunius.businesslogic.api.telegram-1.0.0.jar (Telegram Messenger API for the Business Bot Platform)

Only one messenger library (file de.citunius.businesslogic.api.<messenger>-<version>.jar) can be used per Business Logic otherwise you will face issues with the class loader. The messenger library contains specific functions that are valid only for the particular messenger such as menu structure.

If you want to create a menu for the Business Logic, you can use the prefabricated functions from the messenger library. The Business Logic must store the UserState to remember the menu or submenu of the user. This can be realized via a database function, which stores the UserState for all the users.

A menu is composed with the object ReplyKeyboardMarkup. Therefore, the object ReplyKeyboardMarkup is instantiated, some properties are given and the buttons are defined. The following programming example is provided for illustration purposes:

/**
 * 
 * @return
 */
 private ReplyKeyboardMarkup getKeyboardPreferencesMainMenu() {
     ReplyKeyboardMarkup replyKeyboardMarkup = new ReplyKeyboardMarkup();
     replyKeyboardMarkup.setSelective(true);
     replyKeyboardMarkup.setResizeKeyboard(true);
     replyKeyboardMarkup.setOneTimeKeyboad(false);

     List<List<String>> keyboard = new ArrayList<>();
     List<String> keyboardFirstRow = new ArrayList<>();
     keyboardFirstRow.add(getCommandLanguages(language));
     keyboardFirstRow.add(getCommandAbout());
     keyboard.add(keyboardFirstRow);
     replyKeyboardMarkup.setKeyboard(keyboard);
     return replyKeyboardMarkup;
 }

In the above example, a Preferences menu is created, which has the buttons Languages and About.

Database Access¶

Business Logics need to implement data management either file-based or using a database. The database-based approach must be implemented individually for each Business Logic. Therefore, you must copy the appropriate library for the access database to the lib directory. For further information regarding implementation, please refer to the documentation of the respective manufacturers.

National Language Processing (NLP)¶

Business Logics can be expanded by the ability of National Language Processing (NLP) and AI (Artificial Intelligence) through appropriate libraries. For example, libraries such as Apache OpenNLP and IBM Watson are suitable for this purpose. For more information, please refer to manufacturer's documentation.