maven-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kristian Rosenvold <kristian.rosenv...@gmail.com>
Subject Re: Plugin exposing API - best practise?
Date Sun, 18 Jan 2015 13:30:41 GMT
2015-01-18 12:17 GMT+01:00 Lennart J├Ârelid <lennart.jorelid@gmail.com>:
> Hello folks,
>
> I need a best practise here - hope you can assist me with some ideas and
> suggestions.
>
> *APIs for extensible-configuration plugins*
>
> I believe that plugins that exposes extensible configuration options should
> publish the APIs of those options as a separate project, to keep the set of
> transitive dependencies pushed onto any implementors small.
>
> If not extracting the configuration of the plugin to a separate project,
> you force the entire stack of transitive dependencies from the plugin
> project onto the implementing project - which might complicate things
> unnecessarily. I'm making the following assumptions

This is pretty much what we've been discussing within surefire; I've
been calling it "surefire-client-api".
As for the exact scope of the deps of the "client-api" module, we're
all in favour of keeping it tight, but as Igor points out - at some
point reality bites anyway :) I really think it's the api definition
that decides the dependencies; so the "classic" api rules apply.
There's no point in piling up unnecessary stuff :)

>
>
>    1. A plugin (say jaxb2-maven-plugin) should expose its API in a project
>    whose GAV connects it to the plugin project. While the artifactID
>    "jaxb2-maven-plugin-configuration-api" is a mouthful, the naming standard
>    clearly connects it to the plugin project itself.

Standard naming sounds nice.

>    2. The PluginAPI project can contain default implementations - if
>    required - of the  configuration objects which will serve to de-mystify the
>    potentially complex plugin configuration extension implementations.

I'd say anything goes in this respect.


>    3. When generating the documentation within the plugin project, it is
>    nice to have all documentation concerning usage and configuration in the
>    same location.

We have been discussing the issue of java8 lambdas and api's somewhat;
since we're basically inviting for user supplied hooks - and *most* of
our users will be on java8 within a 0-2 years. Assuming straight
service discovery through plexus component.xml definition of
implementations and injection there will be no such thing; one
interface defines a single extension point and the end user implements
this in one java class which is plexus-injected into the host plugin.

Systematically expressing the client-api as single-method interfaces
does not really provide any value as long as you don't change some
premises. It /would/ be possible to use setter-based injection and
make a single interface "SurefireClientExtensions" that would have
several setters to inject all the various extension points for
instance "setNodeProcessor(NodeProcessor nodeProcessor)". The client
extension project would just implement this one interface and supply
"implementations" of whatever interfaces it needs. This actually has
some potential in supplying custom registration methods that provide
"better" registration options; e.g:

SurefireClientExtensions#addNodeProcessors(NodeProcessor... nodeProcessor)
SurefireClientExtensions#setNodeProcessors(NodeProcessor... nodeProcessor)

This would allow the client-api user to use lambdas and all sorts of
modern goodness. But I must admit I am a bit uncertain as to the
overall gain of this approach.

I am a bit torn in this issue. I probably think the service
registration interface may be a better long-term solution; nice place
to keep all the docs about registration details.

Kristian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Mime
View raw message