Step by step instructions for creating a module

This guide shows how to easily create a new module with Skill-Up. For this a machine can be implemented as simple Java classes and only need to be supplemented by a few annotations.

Contents

1. Setup a Maven project for the module
2. Necessary extensions to the pom.xml
3. Create the module class
4. Build the module project
5. Use the the module

Create Maven project for the module

Open Eclipse and go to File -> New -> Other. The following window opens, in which you select maven project:

In the new window check the box for simple project. Choose a workspace location (default or other) and if desired a working set.

Now a groupId and artifactId are required. The groupId uniquely identifies your project across all projects. A groupId should follow Java's package name rules. The artifactId is the name of the jar without version. Name and description are optional. Your maven project is created!

Extend the pom.xml

In the package explorer the last entry in the new maven project should be the pom file. At first the file should look like this:

To create a skill, the following dependency is necessary. This dependency allows to use annotations, which are necessary to recognize the module as such and thus make it usable. Also, the packaging must be added. Defined as a bundle, this bundle can be added to the others in the OSGi framework. But let's first add the dependency. Inside the <dependencies> section, add the annotation dependency.

    <!-- Beginning of the POM left out-->
    <dependencies>
        <dependency>
	    <groupId>io.github.aljoshakoecher.skillup</groupId>
	    <artifactId>skillup.annotations</artifactId>
            <version>1.0.0</version>
	</dependency>
    </dependencies>

    <!-- Rest of your POM -->
</project>

In order to compile the project into an OSGi bundle which can be picked up by the SkillUp runtime, a special build plugin has to be added. Make sure to add this to your POM. Make also sure to set "packaging" to "bundle. This snippet shows the dependency as well as the build plugin and the packaging setting:

<!-- Beginning of the POM left out-->
    <dependencies>
        <dependency>
	    <groupId>io.github.aljoshakoecher.skillup</groupId>
	    <artifactId>skillup.annotations</artifactId>
            <version>1.0.0</version>
	</dependency>
    </dependencies>
    
    <packaging>bundle</packaging>
   
    <build>
        <plugins>
	    <plugin>
                <groupId>org.apache.maven.plugins</groupId>
		<artifactId>maven-compiler-plugin</artifactId>
		<version>3.8.0</version>
		<configuration>
		    <release>11</release>
		</configuration>
            </plugin>
	    <plugin>
	        <groupId>org.apache.felix</groupId>
		<artifactId>maven-bundle-plugin</artifactId>
		<extensions>true</extensions>
		<configuration>
		    <instructions>
		        <_dsannotations>*</_dsannotations>
		    </instructions>
		</configuration>
	    </plugin>
	</plugins>
    </build>

</project>

Create the module class

In Package Explorer under the new maven project, right-click on src/main/java -> New -> Package. Add a name for the package.

Right-click on the new package -> New -> Class. Add a name for the class that represents the module.

Now the actual module code can be created. The created class Module must be provided with an annotation @Module from the dependency added in the pom.xml, so that the module is also recognized by Skill-Up and is prepared for execution. If the annotation is not found yet refresh (F5) or maven -> update project (Alt+F5). @Module has three properties: While the moduleIRI is required for unique identification, capabilityIri and description are optional.

package module;

import skillup.annotations.Module;

@Module(moduleIri = "https://my-example-module.com/#ExampleModule", description = "MyModule")
public class ExampleModule {
}

Build the module project

Now the module is almost finished. Click on Run -> Run Configurations -> Right Click on Maven Build -> New Configuration and fill it in as shown in the picture. It is important that the project of the new module is selected in the base directory. Then click on apply and run. With this the module is ready.

Use the module

In package explorer, a jar file should have been created in your module project under the target folder. This file can now be placed in the apache felix folder in the include folder.

To use the module, further preparations must be made...

As soon as the startFelix.bat is started, this module is also registered and provided or if felix is already running, the module is also provided.