FlexiCore Plugins Quickstart Guide

What you'll build

You will build a classic “Hello World!” endpoint which any browser can connect to. it will showcase FlexiCore plugins’ capabilities by using a different plugin to provide the hello world string. That is, one plugin depends on another plugin and gets services from it.

The purpose of this tutorial is to show how FlexiCore modularity allows the dependency injection of plugins into other plugins

 

What you’ll need

Development requirements

A Java™ Development Kit (JDK) installed. We recommend AdoptOpenJDK version 11 or 8.

Apache Maven version 3.1 or later installed.

Optional

An Integrated Developer Environment (IDE)

Popular choices include IntelliJ IDEA, Spring Tools, Visual Studio Code, or Eclipse, and many more.

Testing and running requirements

A FlexiCore based server running locally or on an accessible server.

One-click, no prerequisites installation is available for Linux (AMD64, ARM64) and Windows (AMD64) here 

A Docker image with fully installed FlexiCore and prerequisites is available here

Maven based QuickStart

Note: at the end of this page, you can find the required instructions for running this tutorial based on IntelliJ Integrated Development Environment.

Step 1: Create an empty Project

Create a new Maven Project with the following command:

mvn archetype:generate -DgroupId="org.example" -DartifactId=hello-world-service -DarchetypeArtifactId=flexicore-service-archetype -DarchetypeGroupId="com.wizzdi" -DarchetypeVersion="1.0.1" -DinteractiveMode=false

The above command can be used in all operating systems as is. you should now make the project directory the current directory:

cd hello-world-service

Run build

mvn package

The package command should build the project.

Step 1a: Replace the pom.xml file from GitHub

nano pom.xml 

or

notepad pom.xml 

use your favorite text editor or notepad on Windows

make sure your pom.xml matches the one here

Step 1b: Create the service class

Assuming that your current directory is hello-world-service

with your favorite text editor on Linux

mkdir src/main/java/org/example/service

nano src/main/java/org/example/service/HelloWorldService.java

or in Windows

mkdir src\main\java\org\example\service

notepad src\main\java\org\example\service\HelloWorldService.java

now paste the code from here into the editor and save it

package org.example.service;

import com.flexicore.interfaces.ServicePlugin;
import org.pf4j.Extension;
import org.springframework.stereotype.Component;

@Component
@Extension
public class HelloWorldService implements ServicePlugin {

    public String hello() {
        return "Hello World!";
    }

} 

Step 1c: Build and Install the service plugin

now build the plugin and install it into Maven local repository so dependent projects may use it.

mvn install

make sure that the install command completes successfully

Step 2: Create the REST API plugin

change the current directory to the parent 

cd ../

now create a new empty project for our REST API plugin

mvn archetype:generate -DgroupId="org.example" -DartifactId=hello-world-rest -DarchetypeArtifactId=flexicore-service-archetype -DarchetypeGroupId="com.wizzdi" -DarchetypeVersion="1.0.1" -DinteractiveMode=false

Step 2a: Replace the pom.xml file from GitHub

cd hello-world-rest
nano pom.xml 

or

notepad pom.xml

use your favorite text editor or notepad on Windows

make sure your pom.xml matches the one here

Step 2b: Add your code to the REST API plugin

Using your favorite text editor create a new file

mkdir src/main/java/org/example/rest

nano src/main/java/org/example/rest/HelloWorldRESTService.java

or

mkdir src\main\java\org\example\rest

notepad src\main\java\org\example\rest\HelloWorldRESTService.java

and paste the code from the bellow code snippet for HelloWorldRESTService

package org.example.rest;

import org.example.service.HelloWorldService;
import com.flexicore.annotations.OperationsInside;
import com.flexicore.annotations.UnProtectedREST;
import com.flexicore.interfaces.RestServicePlugin;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.pf4j.Extension;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@OperationsInside
@UnProtectedREST
@Path("plugins/helloWorld")
@Tag(name = "HelloWorld")
@Component
@Extension
@Primary
public class HelloWorldRESTService implements RestServicePlugin {

    @Autowired
    private HelloWorldService service;

    @GET
    public String hello() {
        return service.hello();
    }
} 

Step 2c: Few notes on the annotations in the source

Notes regarding the annotations used in the code snippet above:

@UnProtectedREST
Tells FlexiCore to register this class as a JAX-RS – this is registered as an unprotected endpoint as opposed to
@ProtectedREST
When an endpoint is protected only authorized users can access it.
@Path(“plugins/helloWorld”)
tells the JAX-RS layer to register this class REST path plugins/helloWorld
@Component – tells Spring framework that this is a bean.

@Extension– Tells pf4j framework that this is a plugin.

@Tag(“HelloWorld”)– Tells Swagger API interface tagging under which tag this endpoint should be listed, our endpoint will appear under the ‘HelloWorld’ tag.

We are injecting the HelloWorldService using Spring standard @Autowired annotation, FlexiCore injects our service with a hello-world-service plugin instance.

The @GET annotation tells the JAX-RS framework that this method will activate on GET HTTP request

Step 2d: Build and Install the rest service plugin

now build and install the plugin

mvn install

make sure that the operation is successful

Step 3: deploy both plugins into FlexiCore plugins folder

Plugins should be installed on the server running FlexiCore. The default plugins folder for Linux deployment is:
/home/flexicore/plugins
and for Windows
c:\wizzdi\server\flexicore\plugins
copy each of the two plugins into the plugins folder Assuming that your current folder is hello-world-service main folder where the pom.xml is
for Windows
cp  target\hello-world-service-1.0.0.jar \wizzdi\server\flexicore\plugins
for Linux
cp target/hello-world-service-1.0.0.jar  /home/flexicore/plugins
The hello-world-rest-1.0.0.jar plugin is dependent on hello-world-service-1.0.0.jar plugin. This is why both should be copied into the plugin folder. Now copy the other service (REST API), assuming that your current folder is hello-world-rest 
for Windows
cp  target\hello-world-rest-1.0.0.jar \wizzdi\server\flexicore\plugins
for Linux
cp target/hello-world-rest-1.0.0.jar  /home/flexicore/plugins
Make sure that the plugins folder includes only one copy of each plugin, FlexiCore supports multiple versions of the same plugin, however, it requires small code modification in the plugin annotation which is beyond the scope of this tutorial

Step 4: Test your work

New plugins are detected by the FlexiCore server when it is restarted.  

Restarting Flexicore 

MacOS/Linux (without service installed):

note: if the server was installed by Wizzdi setup or Docker is used, FlexiCore runs as a service on both Operating Systems

java -Dloader.main=com.FlexiCore.init.FlexiCoreApplication -Dloader.path=file://home/FlexiCore/entities/ -jar /home/FlexiCore/FlexiCore-4.0.18-exec.jar

MacOS/Linux (with service installed):

service flexicore restart

tail -f /var/log/flexicore/flexicore.log

Windows:

Windows (without service installed):

java -Dloader.main=com.FlexiCore.init.FlexiCoreApplication -Dloader.path=file://wizzdi/server/FlexiCore/entities/ -jar /wizzdi/server/FlexiCore/spring/FlexiCore-4.0.18-exec.jar

Windows (with service installed):

sc stop flexicore

sc start flexicore

get-content -wait  \wizzdi\server\flexicore\logs\flexicore.log

 

You should see some output that looks very similar to this:
FlexiCore-started
FlexiCore-is-up

The last couple of lines here tell us that FlexiCore has started. FlexiCore’s embedded Undertow server is acting as a webserver and is listening for requests on localhost port 8080. Open your browser and in the address bar at the top enter http://localhost:8080/FlexiCore/rest/plugins/helloWorld. You should get a nice friendly response like this:

hello-world-worked

Note: if your server is installed on a different machine or as a Docker based image, replace the loclahost above with the correct ip.

Accessing the API via Swagger user interface is now possible using the following URL:
localhost:8080/FlexiCore.

The username for accessing Swagger is: admin@flexicore.com. The password can be obtained for the firstRun.txt file in

/home/flexicore

or 

c:\wizzdi\server\flexicore

 

IntelliJ based QuickStart

The steps below are detailed and can be carried out by developers new to IntelliJ. 

If you are an experienced IntelliJ user, both plugins can be built in only few steps.

IntelliJ is a popular IDE for Java and can be obtained here

Step 1: Create the Service Plugin

Step 1a: Create FlexiCore Plugin Project

In this stage we will create the service plugin. The service plugin provides a single service, that is, returning a ‘hello world’ message. In IntelliJ, start a new project  , select Maven 

Step 1b: Replace the pom.xml file from GitHub

The project is created with a default pom.xml file. Update your pom.xml from here

After the POM file is updated, you need to invoke reload project . This option is available on the project right click menu when selecting maven

Step 1c: Add your code

In the Java folder created by IntelliJ add a new package: org.example

In this package create a new class named: HelloWorldService , then paste the code from here and make sure no errors are flagged by the IDE. 

package org.example.service;

import com.flexicore.interfaces.ServicePlugin;
import org.pf4j.Extension;
import org.springframework.stereotype.Component;

@Component
@Extension
public class HelloWorldService implements ServicePlugin {

    public String hello() {
        return "Hello World!";
    }

} 

Step 1d: Build and Install the service plugin

The hello-world-service plugin has two uses in this QuickStart context, it must be available to our REST API plugin while the latter is being build, and it should be inside the server plugins folder so the service will be available in runtime.

Add Maven Install configuration

Now build the project, if successfully built, the plugin is available in the target folder and is installed in the local Maven repository.

Step 2: Create the REST API Plugin

In this stage we will create the REST API plugin. This plugin is dependent on the service plugin developed earlier.

Step 2a: Start FlexiCore Plugin Project

In IntelliJ, start a new project  , select Maven .

Step 2b: Replace the pom.xml file from GitHub

The project is created with a default pom.xml file. Update your pom.xml from here

After the POM file is updated, you need to invoke reload project . This option is available on the project right click menu when selecting maven

Click on the java folder and add a new package:org.example

Add an new java class in this package:

HelloWorldRESTService

Copy and paste the code below into the editor.

Step 2c: Add your code

package org.example.rest;

import org.example.service.HelloWorldService;
import com.flexicore.annotations.OperationsInside;
import com.flexicore.annotations.UnProtectedREST;
import com.flexicore.interfaces.RestServicePlugin;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.pf4j.Extension;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@OperationsInside
@UnProtectedREST
@Path("plugins/helloWorld")
@Tag(name = "HelloWorld")
@Component
@Extension
@Primary
public class HelloWorldRESTService implements RestServicePlugin {

    @Autowired
    private HelloWorldService service;

    @GET
    public String hello() {
        return service.hello();
    }
} 

Step 2d: Build the plugin.

As the hello-world-rest plugin is not injected into any other plugin so no other plugin needs it as a dependency, Maven Package  is used.

Now, build the plugin by clicking on the build button.

Make sure that the build is successful.

Step 2e: Deploy the new plugins and restart the server

The two new plugins are available each in its project respective target folder. 

these are the files:

hello-world-service-1.0.0.jar

and 

hello-world-rest-1.0.0.jar

You may continue deployment as described in Step 3 above.

Thank you for joining the beta, you will be notified by our team soon