Hello plugin

This tutorial will guide you with creating a new Blue Mind plugin.

We will extend one of Blue Mind many extension points and add a small hypothetical feature.

Our extension

In the hello company, there is a very strict user login policy: They must start with hello.

We will enforce this policy with a Blue Mind plug-in.

Dev environment setup

To create our plug-in, we need to import Blue Mind source code and extension points definitions into eclipse. This tutorial was written with this version of eclipse:

Clone the git repository

First you need to clone our git repository using a command like this one:

git clone http://git.blue-mind.net

This is a 300MB download.

Import the source code

One your clone is done, it is time to start eclipse.

In eclipse menus, select File > Import...:

Existing project into workspace, next, then point it to the plugins directory inside your Blue Mind git clone.

Select all the projects, and finish.

Create hello plug-in

In eclipse menus, select File > New > Plug-in project.

A plug-in name is most of the time a valid java package name. You should stick to this convention. In the next screen, just fill in the missing informations as show below and click finish.

Extend Blue Mind

In your newly created plug-in, select the MANIFEST.MF file. The should auto-open for you just after you created your plug-in.

Select the extensions tab at the bottom of the manifest editor and click on Add. The extension window should appear:

Un-check Show only extensions from the required plug-ins and type net.bluemind.core.s in the extension filter. Select the net.bluemind.core.sanitycheckerfactory extension point in the list below. Your screen should look like the next screenshot.

Validate using Finish. A pop-up should appear. Answer Yes.

Then save your manifest without leaving the editor. Click on the implementation link to create your plug-in implementation.

The new class windows appears. Choose a name and validate as below:

Finish and eclipse should show your a "red" editor, and an unsaved manifest editor.

To fix those problems, go back to your manifest editor and switch to the dependencies tab. Click on add from the required plug-ins table.

Add the net.bluemind.core.common plugin to the dependencies as show:

Your final dependencies should look like below. Don't forget to save your manifest.

Now go back to your code editor and select the quick fix light bulb on the class declaration line. From the pop-up menu select "Add un-implemented methods" as shown:

Save. Your code should look like this.

Your first plugin is now mostly complete. It is time to write some code to make it do something.

Implementation

HelloAtStartChecker

			package net.bluemind.hello.logincheck;

import net.bluemind.core.api.AccessToken;
import net.bluemind.core.api.Entity;
import net.bluemind.core.api.fault.ServerFault;
import net.bluemind.core.api.user.User;
import net.bluemind.core.sanity.ISanityChecker;

public class HelloAtStartChecker implements ISanityChecker {

	@Override
	public void preCreateCheck(AccessToken at, Entity e) throws ServerFault {
		ensureLoginStartsWithHello(e);
	}

	@Override
	public void preUpdateCheck(AccessToken at, Entity prev, Entity e)
			throws ServerFault {
		ensureLoginStartsWithHello(e);
	}

	private void ensureLoginStartsWithHello(Entity e) throws ServerFault {
		User u = (User) e;
		if (!u.getLogin().startsWith("hello")) {
			throw new ServerFault("Login must start with 'hello' !");
		}
	}

	@Override
	public void preDeleteCheck(AccessToken at, Entity e) throws ServerFault {
	}

}

HelloCheckerFactory

			package net.bluemind.hello.logincheck;

import net.bluemind.core.api.Entity;
import net.bluemind.core.api.user.User;
import net.bluemind.core.sanity.ISanityChecker;
import net.bluemind.core.sanity.ISanityCheckerFactory;

public class HelloCheckerFactory implements ISanityCheckerFactory {

	public HelloCheckerFactory() {
	}

	@Override
	public ISanityChecker create() {
		return new HelloAtStartChecker();
	}

	@Override
	public boolean supports(Entity e) {
		return e instanceof User;
	}

}

Building and deploying

The code is now complete. Eclipse will build and package it for us. Right click on your plug-in project and select Export...

Deployable plug-ins and fragments. Then ensure your plug-in is selected and select a directory for the output.

In the chosen directory, you will find a build jar file for your plug-in under a plugins folder:

To deploy your plug-in, copy this jar to the /usr/share/bm-core/plugins folder on your Blue Mind server, then restart bm-core. Your logs should show lines like the on below.

2012-10-31 14:37:05,485 n.b.c.u.RunnableExtensionLoader INFO - HelloCheckerFactory loaded.
[...]
2012-10-31 14:37:05,486 n.b.c.u.RunnableExtensionLoader INFO - Loaded 8 implementors of net.bluemind.core.sanitycheckerfactory
	

Log with an admin user into the Admin Console an try to update a user. You should see our plug-in doing its job as shown below:

You built and deployed your first Blue Mind plug-in using one of the core extension points.