README.md

Artifact Adapters

This folder contains the artifact adapter projects.

How to add a new ECCO plugin

First, create a new project folder for your plugin. This folder's name should represent what the plugin supports. I.e., the folder containing the plugin that supports Golang source files is simply called "golang". When you create a new plugin project, make sure to enable Gradle as it's build system. This step is important if the project is created with an IDE such as IntelliJ.

Create a package at.jku.isse.ecco.adapter.<your plugin name> and a resource folder META-INF/services. In the first package, you want to create four files. A -Reader file, that handles parsing whatever artefact types your plugin supports and building an ECCO tree. A -Writer file, that handles parsing an ECCO tree and reconstruction of the previously read artefacts. A -Module file, that registers the files above with the Guice dependency injection framework. And finally a -Plugin file, that stores metadata about your plugin. Those files should all have a fitting prefix, mentioning what it is that you are supporting. For example, the plugin supporting Golang artefacts contains the files GoReader, GoWriter, GoModule, and GoPlugin.

In the resource folder, create a file named at.jku.isse.ecco.adapter.ArtifactPlugin. The content of this file must be the fully qualified class name of your -Plugin file. For example, the Golang plugin's ArtifactPlugin-file contains the string at.jku.isse.ecco.adapter.golang.GoPlugin.

After this step, the folder structure should look similar to the following:

• ecco
  • adapter
    • <your plugins project folder>
      • src
        • main
          • java
            • at.jku.isse.ecco.adapter.<your plugin name>
              • <Name>Reader
              • <Name>Writer
              • <Name>Module
              • <Name>Plugin
          • resources
            • META-INF.services
              • at.jku.isse.ecco.adapter.ArtifactPlugin
      • build.gradle

If your IDE didn't create the build.gradle file yet, now is the time to do so. Then, insert the following text, replacing any other text that might have been created.

plugins {
  id 'java'
}

group = 'at.jku.isse.ecco'
version = '0.1.9'
ecco.adapter = true

repositories {
  mavenCentral()
}

dependencies {
  implementation project(':ecco-service')
  testImplementation platform('org.junit:junit-bom:5.9.1')
  testImplementation 'org.junit.jupiter:junit-jupiter'
}

test {
  useJUnitPlatform()
}

Now, implement the necessary interfaces and extend the necessary classes. Make your reader class implement ArtifactReader<Path, Set<Node.Op>> and your writer class ArtifactWriter<Set<Node>, Path> and implement the respective methods. For now, it suffices that they return some default value. After implementing those interfaces extend the module and plugin classes with AbstractModule and ArtifactPlugin respectively. If your IDE cannot resolve those classes, try rebuilding the project using gradle.

In your plugin class, put the following code, making changes as necessary:

public class <Name>Plugin extends ArtifactPlugin {
    public static final String DESCRIPTION = "Adds support for ... artefacts";

    private final <Name>Module module = new <Name>Module();

    @Override
    public String getPluginId() {
        return <Name>Plugin.class.getName();
    }

    @Override
    public Module getModule() {
        return module;
    }

    @Override
    public String getName() {
        return  <Name>Plugin.class.getSimpleName();
    }

    @Override
    public String getDescription() {
        return DESCRIPTION;
    }
}

In your module class, put the following code, making changes as necessary. This code configures the Guice dependency injection framework such that it is aware of your reader and writer classes.

public class <Name>Module extends AbstractModule {
    @Override
    protected void configure() {
        super.configure();

        final Multibinder<ArtifactReader<Path, Set<Node.Op>>> readerMultibinder =
                Multibinder.newSetBinder(
                        binder(),
                        new TypeLiteral<>() {
                        });

        readerMultibinder.addBinding().to(<Name>Reader.class);

        final Multibinder<ArtifactWriter<Set<Node>, Path>> writerMultibinder =
                Multibinder.newSetBinder(
                        binder(),
                        new TypeLiteral<>() {
                        });

        writerMultibinder.addBinding().to(<Name>Writer.class);
    }
}

Finally, for your plugin to be built and picked up by the gui project, locate the settings.gradle file in the root folder of the ECCO project and the build.gradle file in the gui project's folder. In the first one, add the lines include 'adapter-<name>' and project(':adapter-<name>').projectDir = file('adapter/<name>') to the already existing, similarly looking lines. In the second file, add the line runtimeOnly project(':ecco-adapter-<name>') to the dependency-block. Again, there should already exist lines that look similar, just append it there. If you run gradle run ecco:gui and open or initialise a new ECCO-repository, your plugin should show up in status view. If it does not, review this documentation.

If, after reviewing the documentation, your plugin still does not show up, then this documentation is missing something. In that case, please create a new GitHub-Issue with a link to your branch or fork, so that it can be investigated.