FlexiCore Quickstart Guide

Create a new Maven Project with the following command:

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.

Inter-dependencies among plugins is one of the important features of FlexiCore. 

What you’ll need

Development requirements

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

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

The installer installs all prerequisites, once the installer completes installation successfully the flexicore service should be running. 

Note that startup time may be a few minutes depending on the hardware used.

The installer installs Java and the two databases FlexiCore uses, these are PostgresSQL and MongoDB. Both services should be running after installation.

 

 

Step 1: Create Hello World Service Plugin

what we will build?

We will create a service plugin that returns a single string. This service plugin doesn’t depend on other plugins.

Note: the API plugin we will build in step 2 is dependent on the service plugin.

Which tools do we need?

for building the plugin we need Java JDK installed (Java 11 LTS recommended) and Maven installed.

Closer to the end of this page there is the required sequence for working with IntelliJ IDE.

 

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=maven-archetype-quickstart -DarchetypeVersion="1.4" -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 pacakge

The package command should build the project, the project is empty and has no dependencies on FlexiCore yet.

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

nd should build the project, the project is empty and has no dependencies on FlexiCore yet.

Adding the dependencies is best done by replacing the pom.xml in your folder with the pom from here

Step 1B: Create the service class

Assuming that your current directory is hello-world-service

Maven has created a single Java file here, delete it

rm src/main/java/org/example/App.java 
or
del src\main\java\org\example\App.java 

with your favorite text editor on Linux

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

or in Windows

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

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

package org.example;

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.rest" -DartifactId=hello-world-rest -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion="1.4" -DinteractiveMode=false

cd hello-world-rest
nano pom.xml 

use your favorite text editor or notepad on Windows

replace the content of the pom.xml with the one from here

Step 2.a: Add your code to the REST API plugin

package org.example.rest;
import org.example.HelloWorldService;
import com.flexicore.annotations.OperationsInside;
import com.flexicore.annotations.UnProtectedREST;
import com.flexicore.annotations.plugins.PluginInfo;
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;

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

@Autowired
private HelloWorldService service;

@GET
public String hello() {
return service.hello();
}
}
remove the java class Maven has created by default.
rm src/main/java/org/example/rest/App.java
or

del src/main/java/org/example/rest/App.java

Using your favorite text editor create a new file

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

or

notepad.exe src\main\java\org\example\rest\HelloWorldService.java

and paste the code from the above code snippet for HelloWorldRESTService

now build and install the plugin

mvn install

make sure that the operation is successful

Step 2.b: 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 3: Install both plugins into FlexiCore plugins folder

The default plugins folder for Linux installation 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 the plugins

Restarting Flexicore 

MacOS/Linux (without service installed):

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

 

Open up the project in your IDE and locate the HelloWorldService.java file in the src/main/java/com/example/folder. Now change the contents of the file by adding the extra method and annotations shown in the code below. You can copy and paste the code or just type it.

Step 2: Create Hello World REST Plugin

Step 2.a: Start FlexiCore Plugin Project

Create a new Maven Project with the following structure:

quickstart-service-tree

Open up the project in your IDE and locate the DemoApplication.java file in the src/main/java/com/example/demo folder. Now change the contents of the file by adding the extra method and annotations shown in the code below. You can copy and paste the code or just type it.

update your pom.xml from here

MacOS/Linux:

Step 2.b: Add your code

quickstart-service-tree

Step 2.c: Install the REST plugin

Let’s build the plugin. Open a command line (or terminal) and navigate to the folder where you have the hello-word-rest project files. We can build the plugin by issuing the following command:

Windows:

mvn install
copy target/hello-world-rest-1.0.0.jar /home/FlexiCore/plugins

mvn install
copy target/hello-world-rest-1.0.0.jar /home/FlexiCore/plugins

Windows (without service installed):

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