Repository files navigation

• a plugin system for the JVM
  • written in pure Kotlin, might port to Kotlin Multiplatformsomeday.
• that generates all plugin metadata for you
  • write Java/Kotlin/Scala code,never write error-prone metadata manually
• lets you filter the available plugins based on their metadata
  • defer classloading to the last possible instant
• easy mocking for unit tests

AtPlug has three components:

• a small runtimecom.diffplug.atplug:atplug-runtime
• a buildtime step which generates plugin metadata
  • Gradle plugin:com.diffplug.atplug
  • Contributions welcome for maven, etc.
• a harness for mocking in testscom.diffplug.atplug:atplug-test-harness
  • built-in support for JUnit5, PRs for other test frameworks welcome

It is in production usage atDiffPlug.

Let's say you're building a drawing application, and you want a plugin system to allow users to contribute different shapes. The socket interface might look something like this:

interfaceShape {fundraw(g:Graphics)}

Let's say our system has 100 differentShape plugins. Loading all 100 plugins will take a long time, so we'd like to describe which shapes are available without having to actually load it.

We can accomplish this in AtPlug by adding a method to the socket interface marked with@Metadata. The annotation is a documentation hint that this method should return a constant value which will be used to generate static metadata about the plugin.

interfaceShape {  @Metadatafunname():String  @MetadatafunpreviewSvgIcon():Stringfundraw(g:Graphics)}

The AtPlug runtime stores metadata about a plugin in aMap<String, String> which gets saved into a metadata file. This is the mechanism which allows us to inspect all theShape plugins in the system without loading their classes.

To take advantage of this, we need to an objectShape.Socket : SocketOwner which will take aShape instance and return aMap<String, String>. This will be used during the build step to generate AtPlug metadata files.

interfaceShape {object Socket : SocketOwner.SingletonById<Shape>(Shape::class.java) {constvalKEY_SVG_ICON="svgIcon"overridefunmetadata(plug:Shape)=mapOf(Pair(KEY_ID, plug.name()),Pair(KEY_SVG_ICON, plug.previewSvgIcon()))  }}

Now your users can declare an instance ofShape and annotate it with@Plug(Shape.class).

@Plug(Shape::class)classCircle :Shape {overridefunname()="Circle"overridefunpreviewSvgIcon()="icons/circle.svg"overridefundraw(g:Graphics)= g.drawCircle()}

Now when you run./gradlew jar, you will have a resource file calledATPLUG-INF/com.package.Circle.json with content like this:

{"implementation":"com.package.Circle","provides":"com.api.Shape","properties": {"id":"Circle","svgIcon":"icons/circle.svg"  }}

And the manifest of the Jar file will have a fieldAtPlug-Component which points to all the json files in theATPLUG-INF directory. You never have to edit these files, but there's no magic. Themetadata function which you wrote for the socket generates all the json files.

To use the plugin system, you can do:

Shape.Socket.availableIds():List<String>Shape.Socket.descriptorForId(id:String):PlugDescriptor?Shape.Socket.singletonForId(id:String):Shape?

Which are all public methods ofSocketOwner.SingletonById. You can add more methods too for your usecase.

TheSocket is responsible for:

• generating metadata (at buildtime)
• maintaining the runtime registry of available plugins
• instantiating the actual objects from their metadata

When it comes to the registry of available plugins, there are two obvious design points:

• declare some String which functions as a unique id =>Id
• parse theMap<String, String> into a descriptor class, and run filters against the set of parsed descriptors to get all the plugins which apply to a given situation =>Descriptor.

When it comes to instantiating the actual objects from their metadata, there are again two obvious designs:

• Once a plugin is instantiated, cache it forever and return the same instance each time =>Singleton
• Call the plugin constructor each time it is instantiated, so that you may end up with multiple instances of a single plugin, and unused instances can be garbage collected =>Ephemeral

In most cases, if a plugin has a unique id, then it also makes sense to treat that plugin as a global singleton =>SocketOwner.SingletonById. Likewise, if plugins do not have unique ids, then their concept of identity probably doesn't matter so there's no need to cache them as singletons =>SocketOwner.EphemeralByDescriptor.

Those two classes,SingletonById andEphemeralByDescriptor, are the only two options we provide out of the box - we did not fill the full 2x2 matrix (noSingletonByDescriptor orEphemeralById) because we have not found a need anywhere in our codebase for the other cases. You are free to implementSocketOwner yourself from scratch if you want a different design point.

The public methods ofSingletonById are just above this section.EphemeralByDescriptor doesn't have any public methods, only protected methods which you can use to build an API appropriate to your case.

abstractclassEphemeralByDescriptor<T,ParsedDescriptor> {protectedabstractfunparse(plugDescriptor:PlugDescriptor):ParsedDescriptorprotectedfun <R>computeAgainstDescriptors(compute:Function<Set<ParsedDescriptor>,R>) :Rprotectedfun <R>forEachDescriptor(forEach:Consumer<ParsedDescriptor>)protectedfundescriptorsFor(predicate:Predicate<ParsedDescriptor>):List<ParsedDescriptor>protectedfuninstantiateFor(predicate:Predicate<ParsedDescriptor>):List<T>protectedfuninstantiateFirst(predicateDescriptor:Predicate<ParsedDescriptor>,order:Comparator<ParsedDescriptor>,predicateInstance:Predicate<T>):T?}

The examples above are Kotlin, but you can also use Java. To declare the socket, just have a fieldstatic final SocketOwner socket, as shown below:

publicinterfaceShape {publicstaticfinalSocketOwner.Id<Shape>socket =newSocketOwner.SingletonId<Shape>(Shape.class) {@OverridepublicMap<String,String>metadata(Shapeplug) {Map<String,String>map =newHashMap<>();map.put(KEY_ID,plug.name());returnmap;    }  };}

Sockets don't have to be interfaces - abstract classes or even concrete classes would work fine too.

This project used to be called "AutOSGi", and rather than generating.json it generated metadata compatible with OSGi Declarative Services. We found that OSGi caused more trouble than it was worth, and ended up removing it. However, it would be pretty easy to add it back in, see thegraveyard/osgi tag to get back to the OSGi version. Happy to merge a PR which optionally puts this functionality back in.

Java 8+.

• Maintained byDiffPlug.