How to create a plugin

A plugin is just a maven project compiled as a "fat jar", that means all external dependencies of the plugin must be contained in that jar.

Project Setup

Generally there is no difference between a predefined Amy plugin in this repository and a 3rd party plugin. But because of the slightly different build process(multi plugin build) in this repository there are two setup guides. One for internal plugin setup and one for 3rd party plugin setup.

Internal plugin

Maven POM

The basic pom of a plugin looks like this:

<project xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <artifactId>amy-plugin-example</artifactId>
        <name>insert name here</name>
        <description>Description here</description>
        <parent>
                <groupId>io.github.amyassist</groupId>
                <artifactId>amy-plugin-internal-preset</artifactId>
                <version>current amy version here</version>
                <relativePath>../plugin-internal-preset.xml</relativePath>
        </parent>
        <!-- Optional blocks like dependencies here -->
</project>

For the plugin to be part of the Amy project, modify the pom.xml in the top level directory of the project.
In the block <modules> add a line like <module>pathto/plugin</module>.

Easy way

The easiest way of creating a new plugin in this repository is to copy the example plugin folder, change the pom to fit the plugin name and description, and add it to the modules like stated above.

Now you can import the project into eclipse. Then just remove the classes of the example plugin from within eclipse.

Add the plugin to the list of plugins in config/plugin.config.properties.

Finally start implementing the new plugin.

3rd party plugin

Maven POM

Using the amy-plugin parent pom

You can use the amy-plugin pom as parent. Everything needed to build the project is in this amy-plugin pom. So the basic pom of your plugin looks like this:

<project xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <artifactId>amy-plugin-example</artifactId>
        <name>insert name here</name>
        <description>Description here</description>
        <parent>
                <groupId>io.github.amyassist</groupId>
                <artifactId>amy-plugin</artifactId>
                <version>current amy version here</version>
        </parent>
        <!-- Optional blocks like dependencies here -->
</project>

Adding the maven plugin config by hand

Instead of having the amy-plugin as parent, you may use your own parent pom. Then you have to setup the build process in the pom by your self. This is how the build config looks like in the amy-plugin pom.

<build>
	<plugins>
		<plugin>
			<artifactId>maven-shade-plugin</artifactId>
			<version>3.1.1</version>
			<executions>
				<execution>
					<phase>package</phase>
					<goals>
						<goal>shade</goal>
					</goals>
					<configuration>
						<outputFile>build/${project.artifactId}.jar</outputFile>
						<transformers>
							<transformer
								implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
								<manifestEntries>
									<Specification-Title>${project.artifactId}</Specification-Title>
									<Specification-Version>${project.version}</Specification-Version>
									<Implementation-Title>${project.name}</Implementation-Title>
									<Implementation-Version>${project.version}</Implementation-Version>
									<Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
									<PluginID>${project.groupId}.${project.artifactId}</PluginID>
									<PluginDescription>${project.description}</PluginDescription>
								</manifestEntries>
							</transformer>
							<transformer
								implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
								<resource>META-INF/io.github.amyassist.amy.core.di.Services</resource>
							</transformer>
							<transformer
								implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
								<resource>META-INF/javax.ws.rs.Path</resource>
							</transformer>
							<transformer
								implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
								<resource>META-INF/javax.persistence.Entity</resource>
							</transformer>
							<transformer
								implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
								<resource>META-INF/io.github.amyassist.amy.core.console.Console</resource>
							</transformer>
						</transformers>
					</configuration>
				</execution>
			</executions>
		</plugin>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-clean-plugin</artifactId>
			<version>2.4.1</version>
			<configuration>
				<followSymLinks>false</followSymLinks>
				<filesets>
					<fileset>
						<directory>${project.basedir}/build</directory>
					</fileset>
				</filesets>
			</configuration>
		</plugin>
	</plugins>
</build>

There are two plugins maven-shade-plugin and maven-clean-plugin. The maven-shade-plugin bundles all dependencies and DDs into a jar in the build/ directory were it then can be executed. It also adds Metadata to the Manifest so the plugin can be loaded by Amy. The maven-clean-plugin deletes the build/ directory.

So the easiest way to setup your plugin pom is to copy this plugin configuration to your pom. You may have to set the Java version for details see Setting the Java Compiler. Note: supported Java Version

Run/Debug the plugin

The plugin does not contain the main method. The main Method is included in the Amy Application Server, in our case io.github.amyassist.amy.core.Main. So to run the plugin we must start the Amy Application Server and tell them to load the plugin. The Amy Application Server can be downloaded from the GitHub releases. Download amy-master-node.jar to a persistent location.

Eclipse Setup

1. Create a new Run Configuration
2. set the Main class to io.github.amyassist.amy.core.Main
3. add the Amy Application Server jar to the classpath of the Run configuration
4. create the config file .dev/config/plugin.config.properties with the content

   pluginDir=build
   plugins=all
   

5. set Programm arguments of the Run Configuration -c .dev/config
6. next create a new Maven Build Configuration with the goal install
7. create a Launch Group that first runs the Maven Build(Step 6) and than the Java Run Configuration(Step 1) Now you can Run and Debug your plugin by running the Launch Group.

Development

Basic Structure of the Code

The basic structure of the code for a plugin is as follows:

• Services
• a natural language class (more information about this you can read here
• resources like depoyment descriptors(DD)

optional components:

• REST Resource
• console handler
• Message Receiver

Service class

the service class is not only used internally in your plugin it can be used by other plugins. It's best practice to create an interface of the service. Take note of the possible Annotations needed for Dependency Injection. Annotations Wiki Article
A complete example can be found here