Introduction

The BIMserver project aims to provide many possibilities for external developers by providing the Service Interface (implemented in SOAP and Protocol Buffers) but some logic will only work when running within the BIMserver, that's where plugins come into play.

Types of plugins

All plugins implement the Plugin interface:

public interface Plugin {
	void init(PluginManager pluginManager) throws PluginException; // Initialization code, if your plugin requires other plugins, this is the time to check for them, be sure to throw a PluginException when something is wrong
	String getName(); // A short name of this plugin
	String getDescription(); // A short description of this plugin
	String getVersion(); // A version, not used for dependencies (yet)
	boolean isInitialized(); // Should return whether this plugin is successfully initialized
}

Do not implement the Plugin class directly, there are sub-interfaces for the different purposes plugins can have.

Serializers

A serializer serializes an object model to a stream of data. Among the default serializers are: IFC2x3, IfcXml, CityGML and others. Most serializers will output a textbased format but that is not required.

Serializer plugins must implement org.bimserver.plugins.serializers.SerializerPlugin interface

public interface SerializerPlugin extends Plugin {
	EmfSerializer createSerializer(); // The actual method that will create a serializer. Have a look at subclasses of EmfSerializer to see how to build one
	String getDefaultSerializerName(); // A default name, this user can change this
	String getDefaultExtension(); // A default extension, the user can change this
	String getDefaultContentType(); // A default contentType, the user can change this
}

Deserializers

To deserialize a stream of data to an object model.

public interface DeserializerPlugin extends Plugin {
	EmfDeserializer createDeserializer();
	boolean canHandleExtension(String extension);
}

ObjectIDMs

An ObjectIDM helps other code to decide whether to follow a relation/reference or not. This can be used to define subsets of models, based on a given starting point.

public interface ObjectIDMPlugin extends Plugin {
	ObjectIDM getObjectIDM();
	String getDefaultObjectIDMName();
}

Schema Plugins

A schema plugin provides the calling code with information about a schema. There is currently only one implementation, and that one can read an express schema file.

public interface SchemaPlugin extends Plugin {

SchemaDefinition getSchemaDefinition(); File getExpressSchemaFile();

IFC Engines

An IFC Engine makes it possible to convert an IFC file to triangulated geometry.

public interface IfcEnginePlugin extends Plugin {
	IfcEngine createIfcEngine() throws IfcEngineException;
}

So how to develop a plugin

Note: This tutorial assumes you use eclipse, but other IDEs should also work.

Note: The easiest way to learn is to look how other people have done things, there are quite a few plugins already, so have a look at them.

1. Create a new java project for your plugin, for example "PluginTest"

1. Create your plugin class, this class must implement the plugin interface you want to write a plugin for, make sure you implement all methods correctly. For this example we will create a serializer and we will name the plugin "TestSerializerPlugin" in the package "test".
2. Create a plugin folder under your project
3. Create a plugin.xml file under the plugin folder, the content should like like this:

<?xml version="1.0" encoding="utf-8"?>
<PluginDescriptor>		
	<PluginImplementation>
		<interfaceClass>org.bimserver.plugins.serializers.SerializerPlugin</interfaceClass>
		<implementationClass>test.TestSerializerPlugin</implementationClass>
	</PluginImplementation>
</PluginDescriptor>

Now to test your plugin locally you will have to tell the BIMserver where your plugin can be found. Edit "LocalDevPluginLoader.java" and look for the lines with loadPluginFromEclipseProject. Add

pluginManager.loadPluginsFromEclipseProject(new File("../PluginTest"));

Now you can start the BIMserver and your plugin should be available as yet another way to serialize models.

To make your plugin available on deployed BIMservers (either WAR or JAR), you have to create a JAR file of your plugin. It should contain the compiled code, your plugin folder (+plugin.xml), and any required JAR files. The place of jar files doesn't matter, as long as they have the extension ".jar".

License

The license under which the BIMserver.org software is released is a combination of Affero GPL, GPLv3 and/or LGPL (for binaries) from the GNU project. The different projects in our SVN repository are diffently licensed. More info on that can be found on our wiki.

Part of this license outlines requirements for derivative works, such as Plugins, GUI (themes), ObjectIDMs and (de)Serializers. Derivatives of BIMserver.org code inherit the Affero and/or GPL license. There is some legal grey area regarding what is considered a derivative work, but we feel strongly that Plugins, Themes, ObjectIDMs and (de)Serializers are derivative work and thus inherit the Affero or GPL license. If you disagree, you might want to consider a different (open or closed source) project. We suggest some at http://osbim.org/projects/