Vote for Nexus/Sonatype component marking annotations

[Tamas Cservenak]

Hi there,

we had internally a chat about new plugin API and how are we doing it.  
As you all know, the @Inject proposal is only about controlling what  
to inject and where. It does _not_ covers the source of them, from  
where or what are those components coming from (in Guice, one of your  
option to add this "extra" info is to write a Binding manually, but  
you have a lot of other choices too). Obviously, the @Inject proposes  
the "common denominator" for Spring and Guice, but as we see, Plexus  
fits in well too.

Our "spicy additive" to the plugin API, which uses @Inject annotations  
are two additional annotations. But in contrary to @Inject stuff,  
these two annotations are meant to _mark_ the components, and not to  
control their DI. Using these annotations, we are actually covering  
just that part that lacks from @Inject: we are defining a set of Java  
classes as "set of components to be used as source for injection".

Also, we had some "internal force" arguing against having two distinct  
annotations that are doing "almost the same thing". I am convinced,  
that this is not the case.

One annotation is defined in spice module plugin-host-api, and -- as  
it's name says -- is meant for "host app developers" (like Nexus Core  
developers are), to mark the "extension points" only. This module  
should _not_ get to plugin developer classpath. Also, this annotation  
defaults to "plural" components, as it is the case in vast majority of  
cases.

Another is defined in spice plugin-api, and is meant for "plugin  
developers" (dev doing plugins for host app, for Nexus), to mark their  
_own_ managed components only. This module should get to plugin  
developer classpath. This annotation default to "singular" components,  
but the user may achieve plural for his own needs, by combining it  
with @Named from @Inject annotations.

Hence, a developer (either host app developer or plugin developer)  
will _never_ meet both annotations in same time. In any time, only  
_one_ of these two will be available to him.

Examples @Managed - for "user" managed components
==

@Managed
public iface MyComponent {
  String getFoo();
}

public class DefaultMyComponent implements MyComponent {
  public String getFoo() {
    return "foo";
  }
}

equals in "plexus world" to:

@Component(role=MyComponent.class, instantiation-strategy="per-lookup")
public class DefaultMyComponent implements MyComponent {
  public String getFoo() {
    return "foo";
  }
}


Another one:


@Managed
@Singleton
public iface MyComponent {
  String getFoo();
}

@Named("foo")
public class DefaultMyComponent implements MyComponent {
  public String getFoo() {
    return "foo";
  }
}

equals in "plexus world" to:

@Component(role=MyComponent.class, roleHint="foo")
public class DefaultMyComponent implements MyComponent {
  public String getFoo() {
    return "foo";
  }
}


Examples @ExtensionPoint - for extending app
==

/// this is in host app
@ExtensionPoint
public iface MyComponent {
  String getFoo();
}

/// this is in plugin
public class DefaultMyComponent implements MyComponent {
  public String getFoo() {
    return "foo";
  }
}

equals in "plexus world" to:

/// this is in plugin
@Component(role=MyComponent.class,  
roleHint="org.example.DefaultMyCompany" instantiation-strategy="per-
lookup")
public class DefaultMyComponent implements MyComponent {
  public String getFoo() {
    return "foo";
  }
}


Another one:

/// this is in host app
@ ExtensionPoint
@Singleton
public iface MyComponent {
  String getFoo();
}

/// this is in plugin
@Named("foo")
public class DefaultMyComponent implements MyComponent {
  public String getFoo() {
    return "foo";
  }
}

equals in "plexus world" to:

@Component(role=MyComponent.class, roleHint="foo")
public class DefaultMyComponent implements MyComponent {
  public String getFoo() {
    return "foo";
  }
}


The most obvious difference between @Managed and @ExtensionPoint is  
their "singular" vs "plural" nature. The 1st sets roleHint _only_ if  
it is explicitly set, the latter sets roleHint always, by default to  
FQN of implementor class, unless explicitly set. @Named always wins.

Ideally, both should be used in Java Interfaces, to make the code  
cleaner and more readable, but they work on classes too. But in  
contrary to Guice's @ImplementedBy -- which is used on interface --  
you are "delaying" the choice of implementation and not wiring it in,  
like @ImplementedBy annotation does.

Any non-abstract class, that directly or indirectly implements  
interface marked with one of these two annotations (having both of  
them should be managed as compile time error? -- TBD), should be taken  
as component, and pass it to IoC container to manage it (which is now  
Plexus, in future Guice+Peaberry most probably).


Nomenclature
==

As always, I proved "bad godfather". Stuart convinced me, that our  
current annotations have too "generic" and probably misleading names  
(@Managed and @ExtensionPoint). Prof. Igor also stated, that  
@ExtensionPoint confuses with Eclipse "extension points", which are  
totally different beasts.

Hence, I'd like to call for a vote about renaming these annotations.  
Goals:

* make it clear to _anybody_ (sonatype insider or any OSS developer  
from outside) reading these annotations, that they are something  
"private", "sonatype inhouse" solution (annos and gleaning utilities  
are in spice, and are meant to be reused across multiple sonatype apps  
in the future).
* make it clear by reading their name what about are them, "what are  
they doing"
* not mislead developers that this is anyhow related to Eclipse  
"extension points"

So, we could have something like:

@SpiceManaged
@SpiceExtension

@SonatypeManaged
@SonatypeExtension

@ComponentManaged
@ComponentExtention

@ManagedComponent
@ComponentExtension

@ManagedBean
@BeanExtension

or?


Please send your proposals to this list!

Thanks,
~t~

---------------------------------------------------------------------
To unsubscribe, e-mail: nexus-dev-unsubscribe@...
For additional commands, e-mail: nexus-dev-help@...

[Ringo De Smet]

Hello Tamas,

2009/7/8 Tamas Cservenak <cstamas@...>:
>
> Hence, a developer (either host app developer or plugin developer) will
> _never_ meet both annotations in same time. In any time, only _one_ of these
> two will be available to him.

Even after reading the proposal multiple times, I'm still having a
hard time figuring out how this maps to writing Nexus plugins.

> As always, I proved "bad godfather". Stuart convinced me, that our current
> annotations have too "generic" and probably misleading names (@Managed and
> @ExtensionPoint). Prof. Igor also stated, that @ExtensionPoint confuses with
> Eclipse "extension points", which are totally different beasts.

Maybe implementation wise these are different beasts, but conceptually
they map quite nicely:

- an @ExtensionPoint is a declaration of a pluggable part in an
application, e.g Repository types, Indexer implementations, ...
- an @Extension is an implementation of an @ExtensionPoint.

For me, the two annotations above are the application-level
annotations related not only to Nexus, but to any Sonatype "host-app".
Why no also have an ExtensionPoint "HostApplication" where NexusApp is
an Extension? I think Eclipse has proven that such a scheme works and
works quite well (personal opinion!).

This doesn't prevent to use tools like @Inject, @Named, but I consider
these much more low-level. Both Nexus as well as my plugin could use
these annotations to wire everything together as part of the
implementation.

> * not mislead developers that this is anyhow related to Eclipse "extension points"

Don't consider this too much of a problem. Together with some examples
of how the above annotations should be used, they would work very well
in my opinion.

Ringo

---------------------------------------------------------------------
To unsubscribe, e-mail: nexus-dev-unsubscribe@...
For additional commands, e-mail: nexus-dev-help@...

[Anders Hammar]

Hi,

Just some quick comments:

> * make it clear to _anybody_ (sonatype insider or any OSS developer from
> outside) reading these annotations, that they are something "private",
> "sonatype inhouse" solution (annos and gleaning utilities are in spice, and
> are meant to be reused across multiple sonatype apps in the future).

I think that this will be clear by the package names. I assume that
the annotations will be in the org/com.sonatype context? At first I
thought that SpiceXXX was good, but then I realized that 'spicy'
probably will be part of the package, right?

> * make it clear by reading their name what about are them, "what are they
> doing"

This is where I got surprised. Before your post, I just assumed that,
for example, the annotation for a realm implementation would be
"Realm" (or similar). But I see that your thinking about much more
general annotations. I guess that that has some advantages and maybe a
better path, but I just wanted to mention it.
In any case, I think that Ringo's proposal of ExtensionPoint and
Extension is good.
Regarding Managed: I don't really get the difference; it's too late
for my brain I'm afraid... However, "Managed" could mean anything.
Probably not a very informative name.

> * not mislead developers that this is anyhow related to Eclipse "extension
> points"

Aren't Java developers used to check the package names (as there is
nothing about eclipse in there, it shouldn't be misunderstood)?
"Conflicting" names exists everywhere.

/Anders

---------------------------------------------------------------------
To unsubscribe, e-mail: nexus-dev-unsubscribe@...
For additional commands, e-mail: nexus-dev-help@...