Creating Your Own Plugin

How to develop a plugin

Using archetypes

The first step of development is to create a new project using the Maven archetype JBStrap-plugin . This can be done either with Maven tools or by entering the following Maven command.

        mvn archetype:generate -DarchetypeGroupId=com.jbstrap -DarchetypeArtifactId=JBStrap-plugin -DarchetypeVersion=4.0 -DgroupId=org.mycompany -DartifactId=WeatherPlugin
       

Maven commands are entered into a new folder, after which all necessary files are created in the folder. Import the folder into the developer tool as a plugin project. If you create the project within a developer tool, you can start with the development right away.

Plugin main class

The plugin's main class is in the project's root folder, having the same name as the plugin. The main class implements the JBStrapPlugin interface . This interface requires the implementation of methods necessary for the initialization and correct functionality of plugins. The methods are the following:

getPluginName : This method must return a text value that contains the name of the plugin. The name of the plugin can be any text value that will appear in the server log when the application is started, as the name of the loaded plugin.
getPluginVersion : The method must return a text value that contains the version number of the plugin. The version number of the plugin can be in any format and can contain alphanumeric and numeric characters. The version number of the plugin will also appear in the server log after launching the application.
getPluginBuildNumber : The method must return the plugin build number in text format. The plugin build number will appear after the version number in the server log when the plugin is loaded. The build number can also consist of numeric and alphanumeric characters.
getPluginFullName : The method must return the full name of the plugin as a text value.
getPluginAuthor : The method must return the developer's name as a text value
getPluginAuthorURL : The method must return the developer's URL
getDescription : The method should return a short description of the plugin.
init : In this method, the initialization of the plugin must be implemented. This method will be called automatically by the framework after loading the plugin, so here you can make the necessary settings required for the plugin to work. The method may throw an error, in which case the plugin will stop loading, the error will appear in the server log, and the plugin will not work.

The framework does not define any restrictions regarding the structure of plugins, so if you implement one of the classes above, you already have a plugin that can be loaded into the JBStrap framework. After that, all you have to do is make the plugin work.

Implementation

Now that we know the theory of plugin development, let’s create our weather plugin. Our plugin will be named weather plugin.

  Source code for our weather plugin’s main class:  
        
import com.jbstrap.core.plugin.JBStrapPlugin;

/**
 * The application startup class
 */
public class WeatherPlugin implements JBStrapPlugin {

	private static String key = "";

	/**
	 * Gets the name of the plugin.
	 * @return The plugin's unique name
	 */
	@Override
	public String getPluginName() {
		return "Weather plugin";
	}

	/**
	 * Gets the plugin's version number.
	 * @return The string representing the plugin version.
	 */
	@Override
	public String getPluginVersion() {
		return "1.0";
	}

	/**
	 * Gets the plugin's build number.
	 * @return The string representing the plugin build number.
	 */
	@Override
	public String getPluginBuildNumber() {
		return "example build";
	}

	/**
	 * Gets the plugin's full name
	 * @return The plugin's full name
	 */
	@Override
	public String getPluginFullName() {
		return "Example Weather plugin to OpenWeather API";
	}

	/**
	 * Gets the name of the plugin author
	 * @return The name of the plugin author
	 */
	@Override
	public String getPluginAuthor() {
		return "JBStrap";
	}

	/**
	 * Gets the URL (web address) of the plugin author
	 * @return The URL of the plugin author
	 */
	@Override
	public String getPluginAuthorURL() {
		return "http://www.jbstrap.com";
	}

	/**
	 * Gets the plugin description
	 * @return The plugin description
	 */
	@Override
	public String getDescription() {
		return "This plugin is an example plugin that shows how to develop a plugin for the JBStrap framework. " +
				"The plugin uses a RestAPI call to determine the current weather in a city and display it on the interface.";
	}

	/**
	 * Set the API key
	 */
	public static void setApiKey(final String apiKey) {
		key = apiKey;
	}

	/**
	 * Get API key
	 */
	public static String getApiKey() {
		return key;
	}

	/**
	 * Initialize the weather plugin
	 */
	@Override
	public void init() throws Exception {

	}
}

In the main class of the plugin, we implemented the methods required by the JBStrapPlugin interface and added a configuration option. Using this option, you can set and get the API key. The API is free to use, but it requires registration. Upon registration, you will receive an API key that can be set using this method. Click here to complete the registration .

Once the main class is ready, make a simple enum that will configure temperature units to be used. This enum is called Unit .

  The source code of the Unit enum class:  
        
import java.util.Arrays;

public enum Unit {
	METRIC, IMPERIAL;

	public static Unit fromName(final String name) {
		return Arrays.asList(Unit.values()).stream().filter(u -> u.toString().equals(name)).findFirst().orElse(null);
	}

}

Once this has been done, create a class calling Rest API. This class is used as a service. It will generate a URL for the query and will execute the query itself. The class is named RestService .

  The source code of the RestService class:  
        
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Map;
import java.util.Objects;
import java.util.Scanner;
import java.util.concurrent.ConcurrentHashMap;
import java.util.stream.Collectors;

public class RestService {

	private final String url;
	private final Map<String,String> queryParams = new ConcurrentHashMap<>();
	private String response;

	public RestService(final String baseUrl) {
		this.url = Objects.requireNonNull(baseUrl, "The API base URL is required");
	}

	public RestService addParam(final String name, final String value) {
		if (name == null || name.isEmpty()) {
			throw new IllegalArgumentException("The query parameter name is required");
		}
		queryParams.put(name, value == null ? "" : value);
		return this;
	}

	public String getParam(final String name) {
		return queryParams.get(Objects.requireNonNull(name, "The query parameter name is required"));
	}

	public int execute() throws Exception {
		final URL url = new URL(
				this.url + (queryParams.isEmpty() ? "" :
					"?" + String.join("&", queryParams.entrySet().stream().map(entry -> entry.getKey() + (entry.getValue().isEmpty() ? "" : "=" + entry.getValue())).collect(Collectors.toList()))
						)
				);
		final HttpURLConnection connection = (HttpURLConnection)url.openConnection();
		final InputStream stream = connection.getResponseCode() == HttpURLConnection.HTTP_OK ? connection.getInputStream() : connection.getErrorStream();
		try (Scanner scanner = new Scanner(stream).useDelimiter("\\A")) {
			this.response = scanner.hasNext() ? scanner.next() : "";
			scanner.close();
		} catch (final Exception e) {
			stream.close();
			throw new IllegalArgumentException("Can not read response stream");
		}
		stream.close();
		connection.disconnect();
		return connection.getResponseCode();
	}

	public String getResponse() {
		return this.response;
	}
}

When creating the class, you must specify a default address used for the query. You can then add parameters to the class that will be included in the URL as a query parameter. The remote server will send a response based on these parameters. We will use the RestService execute method to execute your query. The return value of the method will be the status of the HTTP request. Depending on the status of the request, in this example, we will receive either an HTML content or a JSON content. If the query is successful, the HTML content containing the current weather conditions for the specified city is returned. In the event of an error, the call returns a JSON with the error message text in the message attribute. The result obtained in this way can be requested from RestService using the getResponse method.

We now have everything we need to describe the weather in a city. In the plugin, also create a component that will display the city weather or, in the event of an error, the text of the error message. This component is called CityWeather , and when you create it, you will need to specify a city. Extend the component from the DIV component, in which the information will be displayed using an HTMLFlow component.

  The source code of the CityWeather component:  
        
import java.net.HttpURLConnection;
import java.util.Objects;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import com.jbstrap.ui.Clickable;
import com.jbstrap.ui.Draggable;
import com.jbstrap.ui.HandleMouseEvents;
import com.jbstrap.ui.components.Div;
import com.jbstrap.ui.components.HTMLFlow;

public class CityWeather extends Div implements Clickable<CityWeather>, HandleMouseEvents<CityWeather>, Draggable<CityWeather> {

	private final HTMLFlow html = new HTMLFlow("");
	private String cityName;
	private final RestService service = new RestService("http://api.openweathermap.org/data/2.5/weather");
	private Unit unit = Unit.METRIC;

	/**
	 * Create new City Weather component
	 */
	public CityWeather(final String cityName) {
		super();
		// Set up Rest API call
		setCityName(Objects.requireNonNull(cityName, "The city name is required"));
		service.addParam("appid", WeatherPlugin.getApiKey());
		service.addParam("mode", "html");
		service.addParam("q", "London");
		addComponent(html);
	}

	/**
	 * Set city name and refresh the component value
	 */
	public CityWeather setCityName(final String cityName) {
		if (this.cityName == null ? cityName != null : !this.cityName.equals(cityName)) {
			this.cityName = cityName;
			refresh();
		}
		return this;
	}

	/**
	 * Get current displayed city name
	 */
	public String getCityName() {
		return this.cityName;
	}

	/**
	 * Set the units
	 */
	public CityWeather setUnit(final Unit unit) {
		if (this.unit != (unit == null ? Unit.METRIC : unit)) {
			this.unit = unit == null ? Unit.METRIC : unit;
			refresh();
		}
		return this;
	}

	/**
	 * Get the units
	 */
	public Unit getUnits() {
		return this.unit;
	}

	/**
	 * Refresh the component value
	 */
	public void refresh() {
		service.addParam("units", this.unit.toString().toLowerCase());
		service.addParam("q", this.cityName);
		try {
			final Pattern pattern = Pattern.compile(service.execute() == HttpURLConnection.HTTP_OK ? ".*<body>([\\s\\S]*)<script>.*" : ".*message\":\"([\\s\\S]*)\".*");
			final Matcher matcher = pattern.matcher(service.getResponse());
			html.setHTML(matcher.find() ? matcher.group(1) : "Illegal response format");
		} catch (final Exception e) {
			html.setHTML("Exception in get weather information");
		}
	}
}

You will be able to place the component made in this way on any page and display the current weather in a specific city. If you change the unit of measure or the name of the city on the component, it will automatically query the data again and will already display the new data. If you want to manually update the data, you must call the refresh method for the component.

We can assign click event handlers, mouse cursor event handlers to the component, and the component also supports drag & drop.

At this point, the plugin is ready to use. Now all you have to do is compile the plugin you created and you can load it into the application. You can also compile the plugin from the development tool you are using, or enter the following maven statement in the folder containing the plugin's source code:

Whether compiled with the development tool or using the code above, the compilation will produce a JAR file that will be included in our local maven repository. Then the plugin needs to be added to the pom.xml file of our application and also loaded into the framework. You can do this by following these steps:

  Adding the plugin dependency to the pom.xml file:  
        
<dependency>
    <groupId>org.mycompany</groupId>
    <artifactId>weather-plugin</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

  Loading the plugin in the application’s Startup class, in the loadPlugin method (the plugin will be loaded and initialized, meaning that all of its functions are operational, and can be used in the application):  
        
@Override
public void loadPlugins() {
	try {
		// Load and initialize the Weather plugin
		JBStrap.loadPlugin(WeatherPlugin.class);
		// Set up Weather plugin: Set the registered API key
		WeatherPlugin.setApiKey("<your registered API key>");
	} catch (final Exception e) {
		LOG.error("Can not load weather plugin.", e);
	}
}

If you're ready with that, create a page in the application with an input field where the user can enter a city name. Also, place a combo box into the application, listing measurement units to display data. A plugin component on the page will display weather data. London is set as a default location for weather data.

  Source code of the page displaying the weather information:  
        
import com.jbstrap.test.CityWeather;
import com.jbstrap.test.Unit;
import com.jbstrap.ui.BasePage;
import com.jbstrap.ui.Icon;
import com.jbstrap.ui.authorization.Public;
import com.jbstrap.ui.components.button.Button;
import com.jbstrap.ui.components.form.items.ComboboxItem;
import com.jbstrap.ui.components.form.items.TextItem;

/**
 * The main page that appears after application opened
 */
@Public
public class MainPage extends BasePage {

	CityWeather weather;

	@Override
	public void build() {

		weather = new CityWeather("London");

		final ComboboxItem cbxUnit = new ComboboxItem("unit", "Unit");
		cbxUnit.addElement(Unit.METRIC.toString(), "Celsius");
		cbxUnit.addElement(Unit.IMPERIAL.toString(), "Fahrenheit");
		cbxUnit.setValue(Unit.METRIC.toString());
		cbxUnit.addValueChangeHandler(event -> weather.setUnit(Unit.fromName((String)cbxUnit.getValue())));

		final TextItem cityName = new TextItem("city", "City name");
		cityName.setValue("London");
		cityName.addValueChangeHandler(event -> weather.setCityName(cityName.getValue()));

		final Button apply = new Button(Icon.FLASH, "Apply");
		apply.addClickHandler(event -> {
			weather.setCityName(cityName.getValue());
			weather.setUnit(Unit.fromName((String)cbxUnit.getValue()));
		});

		addComponents(cbxUnit, cityName, apply, weather);
	}

	@Override
	public void afterDraw() {
		weather.refresh();
	}
}

If the user rewrites the name of the city on the page and presses ENTER or changes the measurement unit, weather data will be queried automatically. The current data is also queried when the user clicks the ' Apply ' button.