c0d3d / easy-plugins

Annotation directed service providers, made easy!

Easy Plugins

easy-plugins is a library that lets you easily develop using a seamless service based architecture in Java!

Example

To use easy plugins simply annotate an annotation that you write with @Service. @Service has three required values and one optional one. They are:

1. value: This is the name of the service you are creating
2. serviceInterface: This the Class object for the interface that each of your providers must implement. Abstract classes are also permitted.
3. outputPackage: This is the output package for all the generated classes used to support your new services.
4. (optional) serviceNameKey: This is the name of the field inside the annotation the @Service is annotating to look for the name of each service provider.

Here is an example usage:

import com.nlocketz.Service;

@Service(value = "AdderService",
	 serviceInterface = Adder.class,
	 outputPackage = "com.nlocketz.adders.generated")
public @interface AdderService {
	String value();
}

This example assumes that you have a class named Adder which easy-plugins will use to generate the service interface. Here is our interface:

public interface Adder {
	int add(int x, int y);
}

That is all you need to do to create a new service!

The problem now is you don't have any actual Adders to use, so let's make one.

@AdderService("AccurateAdder")
public class Adder1 implements Adder {
	@Override
	public int add(int x, int y) {
		return x+y;
	}
}

and another one.

@AdderService("InaccurateAdder")
public class Adder2 implements Adder {
	@Override
	public int add(int x, int y) {
		return x - y;
	}
}

Now you have a service with two providers named AccurateAdder, and InaccurateAdder.

To access them you use the class AdderServiceRegistry which has been generated as a result of annotating AdderService with @Service.

Here we use both to add two numbers:

Adder accurate = AdderServiceRegistry.getAdderServiceByName("AccurateAdder");
Adder inaccurate = AdderServiceRegistry.getAdderServiceByName("InaccurateAdder");
assertEquals(3, accurate.add(1, 2));
assertEquals(-1, inaccurate.add(1, 2));

AdderServiceRegistry also contains another static method called getAdderServiceByNameWithConfig which takes a name and an Object which it pass to your provider as a kind of configuration.

Your provider can choose to subscribe to these configuration calls by created a constructor that consumes an argument. If you don't have one, the default constructor will be called. If you don't have a default constructor and getAdderServiceByName is called, a default value (an empty map for Map, and empty list for List, 0 for numbers, false for booleans, and null for other objects) will be provided as the argument to the one-argument constructor. Annotating a constructor with @ConfigurationConstructor will override this behavior and cause that constructor to be used when creating with a configuration.

Here is an example Adder that uses configuration information:

import java.util.Map;
import com.nlocketz.adders.api.Adder;
import com.nlocketz.adders.api.AdderService;

@AdderService("OffsetAdder")
public class Adder4 implements Adder {
    private int offset;

    public Adder4(Map<String, String> config) {
        offset = Integer.parseInt(config.get("offset"));
    }


    @Override
    public int add(int x, int y) {
        return y + x + offset;
    }
}

and the usage is like this:

Adder offset = AdderServiceRegistry.getAdderServiceByNameWithConfig("OffsetAdder",
	Collections.singletonMap("offset", "3"));
Adder accurate = AdderServiceRegistry.getAdderServiceByNameWithConfig("AccurateAdder",
	Collections.singletonMap("offset", "3"));
Adder inaccurate = AdderServiceRegistry.getAdderServiceByNameWithConfig("InaccurateAdder",
	Collections.singletonMap("offset", "3")););
assertEquals(3, accurate.add(1, 2));
assertEquals(-1, inaccurate.add(1, 2));
assertEquals(3, offset.add(0, 0));

Plugins

easy-plugins also has an experimental plugin API of its own, which can be used to extend the behavior of generated classes. For example, the Guice Plugin extends the framework to include methods which accept Guice injectors. For example, one can do the following:

import com.google.inject.Inject;
import com.google.inject.name.Named;
import com.nlocketz.adders.api.Adder;
import com.nlocketz.adders.api.AdderService;

@AdderService("OffsetAdder")
public class AdderN implements Adder {
    private int offset;

    public Adder4(int offset) {
        this.offset = offset;
    }

    @Inject(optional = true)
    public void setOffset(@Named("offset") Integer offset) {
        this.offset = offset;
    }

    @Override
    public int add(int x, int y) {
        return y + x + offset;
    }
}

Additionally, there is a Jackson Plugin, which adds a Jackson deserializer to the generated registry. For example, the above class can be deserialized from the following JSON string (corresponding to a construction with no configuration):

"OffsetAdder"

If a configuration is desired, it can be used using the configuration type's JSON serialization:

{"OffsetAdder": 5}

easy-plugins's Issues

Make Repository Public

In order to enable Travis (unless you feel like setting up a Jenkins server), we will need to make this repository public.

OSGi-Friendly Plugins

cc: @c0d3d
easy-plugins works well within a single-classloader environment, but there are challenges involved with running things across OSGi boundaries. In particular, the *Registry classes are only able to discover services via the ServiceLoader API, meaning that the only way of wiring things up in a cross-bundle scenario is via the OSGi service mediator (in theory). Worse, this requires users to break the easy-plugins abstraction by specifying the auto-generated interface in provider bundles' OSGi manifests. To overcome these issues, we should provide better support for wiring up services. Some ideas:

• Ability to manually register services with registries (Solves issue 1 but not issue 2). In combination with an OSGi service tracker, this would remove the need for the service mediator.
• Automatically add the auto-generated service to the OSGi manifest during compilation (which should make the service mediator "just work"...?)
• Add a method to the registry which returns a service tracker for its associated interface. This has the following benefits: (a) it is a "robust" abstraction which still hides many details, (b) it can be implemented by a plugin.

Additionally, there may be good solutions not listed here.

Update repo URL in pom

Existing META-INF/services Files are Garbled

When running easy-plugins, any existing META-INF/services files that easy-plugins tries to update have all newlines removed.
(fix is to add writer.write('\n') after this line)