ignite-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sergi Vladykin <sergi.vlady...@gmail.com>
Subject Re: API stability.
Date Sun, 30 Aug 2015 12:48:13 GMT
Agree, documenting PluginProvider.createCompoment method must be enough
here.

Sergi

2015-08-30 13:17 GMT+03:00 Vladimir Ozerov <vozerov@gridgain.com>:

> PluginProvider has a method "createComponent" which is used during
> processor initialization. And it looks like this is the only place where
> Ignite internals could be visible to plugin developers.
> Lets just add detailed JavaDoc to this method warning users that
> processor's API is internal stuff and subject to potentially incmpatible
> changes.
>
> On Sun, Aug 30, 2015 at 11:26 AM, Sergi Vladykin <sergi.vladykin@gmail.com
> >
> wrote:
>
> > Guys,
> >
> > As I see it we have 3 types of APIs, that require strong backward
> > compatibility, namely the public API itself (Ignite, IgniteCache,
> etc...),
> > SPIs (IndexingSpi, DiscoverySpi, etc..) and plugin API (IgnitePlugin,
> > PluginContext, etc...)
> >
> > None of these interfaces provide access to Ignite internals. And this is
> > correct design.
> > But if some plugin implementation chooses to utilize some private APIs of
> > Ignite
> > like GridGain does with IgniteCacheObjectProcessor it is a problem of the
> > implementor
> > to look after changes in these internal components.
> >
> > As for annotations and compiler warnings - in my experience no one really
> > cares.
> >
> > Sergi
> >
> >
> >
> > 2015-08-30 4:37 GMT+03:00 Raul Kripalani <raul@evosent.com>:
> >
> > > Is it really necessary for the user to be reminded on every
> compilation?
> > >
> > > If I understand correctly, the types of annotation you want to
> introduce
> > > are informative – not necessarily prompting to immediate action like a
> > > @Deprecated annotation. The latter inevitably ends in a removal and
> > > consequent API breakage. But in the circumstances where @Evolving is
> > > applicable, there's no immediate action the user could take: they just
> > have
> > > to live with the transitional nature, and the API may not even change
> > ever.
> > > So there's no point in nagging them with every build, IMHO.
> > >
> > > Just making it part of Javadoc should be enough, to raise awareness
> > about a
> > > possible rocky road ahead...
> > >
> > > *Raúl Kripalani*
> > > Apache Camel PMC Member & Committer | Enterprise Architect, Open Source
> > > Integration specialist
> > > http://about.me/raulkripalani |
> http://www.linkedin.com/in/raulkripalani
> > > http://blog.raulkr.net | twitter: @raulvk
> > >
> > > On Sun, Aug 30, 2015 at 2:19 AM, Konstantin Boudnik <cos@apache.org>
> > > wrote:
> > >
> > > > On Sat, Aug 29, 2015 at 11:07PM, Branko Čibej wrote:
> > > > > On 29.08.2015 00:06, Konstantin Boudnik wrote:
> > > > > > On Fri, Aug 28, 2015 at 05:14PM, Vladimir Ozerov wrote:
> > > > > >> Dima,
> > > > > >>
> > > > > >> I'm not suggesting doing this, they are already not stable.
For
> > > > example,
> > > > > >> take a look at IgniteCacheObjectProcessor. This is a component
> > which
> > > > can be
> > > > > >> injected through plugins, thus it is "semi-public". However,
it
> is
> > > > under
> > > > > >> heavy changes and if some unlucky guy is to implement a
plugin
> > using
> > > > this
> > > > > >> processor, he will face compilation errors with each new
Ignite
> > > > release.
> > > > > >>
> > > > > >> My suggestion is to define policies for things like that.
One of
> > > > possible
> > > > > >> solutions - is to annotate APIs so that developers are aware
of
> > > > potential
> > > > > >> problems.
> > > > > >>
> > > > > >> One more example from Hadoop:
> > > > > >> 1) org.apache.hadoop.fs.FileSystem: @Public, @Stable
> > > > > >> 2) org.apache.hadoop.fs.AbstractFileSystem: @Public, *@Evolving*
> > > > > > I think having those annotations aren't making developers more
> > aware
> > > > about
> > > > > > potential compatibility problems, nor enforce any kind of policy
> > > > mechanism
> > > > > > around API compatibility. There's a plenty of examples in Hadoop
> > > (YARN
> > > > in 2.4
> > > > > > and some other stuff before it) where incompatible changes were
> > > > introduced in
> > > > > > minor releases and had to be quickly corrected in a consequent
> > patch
> > > > release.
> > > > > >
> > > > > > What these annotations might help with is to quickly settle
the
> > > > argument that
> > > > > > certain APIs shouldn't have been used in the first place, because
> > > they
> > > > were
> > > > > > @Evolving or otherwise. It's more like a UML diagram: if
> something
> > > > goes wrong
> > > > > > ppl have a common ground to find our who has screwed up and
why;
> > but
> > > it
> > > > > > doesn't prevent the screw-up itself.
> > > > > >
> > > > > > Perhaps relying on public APIs as the only fully approved for
3rd
> > > party
> > > > > > software developers is the only recourse in this case.
> > > > >
> > > > > There's nothing inherently wrong with publishing experimental
> public
> > > > > APIs, as long as they're clearly marked as such. Subversion does
> > that,
> > > > > on rare occasions; we don't loose sleep over people writing code
> > > against
> > > > > those APIs, they get ample warning at compile time and in the docs.
> > > Once
> > > > > the APIs are finalized, we remove the experimental annotation.
> > > >
> > > > I agree in principle. However, having some mechanism to enforce the
> > > > warning on
> > > > the experimental APIs is very handy. I think in Java something like
> > this
> > > >     https://github.com/pushtorefresh/javac-warning-annotation
> > > > could you be used to generate compile-time warnings. It is
> conveniently
> > > > under
> > > > ASL2 and has its artifacts on maven central.
> > > >
> > > > Cos
> > > >
> > > >
> > > >
> > > >
> > >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message