Re: Re: [ALL] About binary compatibility

[James Carman]

Perhaps the new ASM-based replacement for CLIRR could have those as one of
its "components" in its TLP?

On Tue, Jun 14, 2016 at 11:00 AM Matt Benson  wrote:

> On Jun 14, 2016 9:55 AM, "Gary Gregory"  wrote:
> >
> >
> > On Jun 14, 2016 7:45 AM, "Matt Benson"  wrote:
> > >
> > > On Tue, Jun 14, 2016 at 2:14 AM, Andrey Loskutov 
> wrote:
> > >
> > > > I like the way Eclipse it does for years:
> > > >
> > > > 1) Everything inside **/internal/ packages is non API by definition
> > > > 2) MANIFEST.MF to use OSGI "Export-Package" attribute for "published"
> > > > packages
> > > > 3) Javadoc @noextend tag for classes not intended to be extended
> > > > 4) Javadoc @noimplement tag for interfaces
> > > >
> > > > If "real" annotations were used for points 3 and 4, they could live
> > > alongside a Java (6) Processor that, if the user had annotation
> processing
> > > enabled, could fail the build (pretty sure this is doable).
> >
> > But where do these annotations live? Does each Commons component
> duplicate them?
> >
>
> I thought about that, and would conclude that they should live in a thin
> compile-time-only dependency library (it may be the case that usable
> versions of these annotations already exist someplace, but the processor
> would still have to be provided in this manner, so it doesn't really change
> anything). No reason this couldn't be used outside Commons either,
> actually.
>
> Matt
>
> > Gary
> >
> > >
> > > Matt
> > >
> > >
> > > > A bonus for libraries with correct MANIFEST.MF is that they can be
> > > > directly used as bundles inside any OSGI container (also Eclipse).
> > > >
> > > > Example:
> > > > /**
> > > >  * An observable value whose changes can be vetoed by listeners.
> > > >  *
> > > >  * @param 
> > > >  *the type of value being observed
> > > >  *
> > > >  * @noextend This interface is not intended to be extended by
> clients.
> > > >  * @noimplement This interface is not intended to be implemented by
> > > > clients.
> > > >  *  Clients should instead subclass one of the classes
> that
> > > >  *  implement this interface. Note that direct
> implementers of
> > > > this
> > > >  *  interface outside of the framework will be broken in
> future
> > > >  *  releases when methods are added to this interface.
> > > >  *
> > > >  * @since 1.0
> > > >  *
> > > >  */
> > > > public interface IVetoableValue extends IObservableValue {
> > > >
> > > > Kind regards,
> > > > Andrey Loskutov
> > > >
> > > > http://google.com/+AndreyLoskutov
> > > >
> > > >
> > > > > Gesendet: Dienstag, 14. Juni 2016 um 09:03 Uhr
> > > > > Von: "Jörg Schaible" 
> > > > > An: dev@commons.apache.org
> > > > > Betreff: Re: [ALL] About binary compatibility
> > > > >
> > > > > Hi,
> > > > >
> > > > > James Carman wrote:
> > > > >
> > > > > > Agree we should have a "source of truth". Is there something
> wrong with
> > > > > > using an "internal" or "impl" package name? The bundle plugin for
> OSGi
> > > > > > doesn't export these by default, which would be a nice side
> effect! :).
> > > > >
> > > > > While it is a step in the right direction, a package scoped
> solution does
> > > > > not solve the problem of a public interface that should not be
> > > > implemented
> > > > > directly (as we've seen with the BCEL visitor). Time for Java 8 and
> its
> > > > > default implementations ...
> > > > >
> > > > > Cheers,
> > > > > Jörg
> > > >
> > > > -
> > > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> > > > For additional commands, e-mail: dev-h...@commons.apache.org
> > > >
> > > >
>

Re: Re: [ALL] About binary compatibility

[Matt Benson]

On Jun 14, 2016 9:55 AM, "Gary Gregory"  wrote:
>
>
> On Jun 14, 2016 7:45 AM, "Matt Benson"  wrote:
> >
> > On Tue, Jun 14, 2016 at 2:14 AM, Andrey Loskutov 
wrote:
> >
> > > I like the way Eclipse it does for years:
> > >
> > > 1) Everything inside **/internal/ packages is non API by definition
> > > 2) MANIFEST.MF to use OSGI "Export-Package" attribute for "published"
> > > packages
> > > 3) Javadoc @noextend tag for classes not intended to be extended
> > > 4) Javadoc @noimplement tag for interfaces
> > >
> > > If "real" annotations were used for points 3 and 4, they could live
> > alongside a Java (6) Processor that, if the user had annotation
processing
> > enabled, could fail the build (pretty sure this is doable).
>
> But where do these annotations live? Does each Commons component
duplicate them?
>

I thought about that, and would conclude that they should live in a thin
compile-time-only dependency library (it may be the case that usable
versions of these annotations already exist someplace, but the processor
would still have to be provided in this manner, so it doesn't really change
anything). No reason this couldn't be used outside Commons either, actually.

Matt

> Gary
>
> >
> > Matt
> >
> >
> > > A bonus for libraries with correct MANIFEST.MF is that they can be
> > > directly used as bundles inside any OSGI container (also Eclipse).
> > >
> > > Example:
> > > /**
> > >  * An observable value whose changes can be vetoed by listeners.
> > >  *
> > >  * @param 
> > >  *the type of value being observed
> > >  *
> > >  * @noextend This interface is not intended to be extended by clients.
> > >  * @noimplement This interface is not intended to be implemented by
> > > clients.
> > >  *  Clients should instead subclass one of the classes
that
> > >  *  implement this interface. Note that direct
implementers of
> > > this
> > >  *  interface outside of the framework will be broken in
future
> > >  *  releases when methods are added to this interface.
> > >  *
> > >  * @since 1.0
> > >  *
> > >  */
> > > public interface IVetoableValue extends IObservableValue {
> > >
> > > Kind regards,
> > > Andrey Loskutov
> > >
> > > http://google.com/+AndreyLoskutov
> > >
> > >
> > > > Gesendet: Dienstag, 14. Juni 2016 um 09:03 Uhr
> > > > Von: "Jörg Schaible" 
> > > > An: dev@commons.apache.org
> > > > Betreff: Re: [ALL] About binary compatibility
> > > >
> > > > Hi,
> > > >
> > > > James Carman wrote:
> > > >
> > > > > Agree we should have a "source of truth". Is there something
wrong with
> > > > > using an "internal" or "impl" package name? The bundle plugin for
OSGi
> > > > > doesn't export these by default, which would be a nice side
effect! :).
> > > >
> > > > While it is a step in the right direction, a package scoped
solution does
> > > > not solve the problem of a public interface that should not be
> > > implemented
> > > > directly (as we've seen with the BCEL visitor). Time for Java 8 and
its
> > > > default implementations ...
> > > >
> > > > Cheers,
> > > > Jörg
> > >
> > > -
> > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> > > For additional commands, e-mail: dev-h...@commons.apache.org
> > >
> > >

Re: Re: [ALL] About binary compatibility

[Gary Gregory]

On Jun 14, 2016 7:45 AM, "Matt Benson"  wrote:
>
> On Tue, Jun 14, 2016 at 2:14 AM, Andrey Loskutov  wrote:
>
> > I like the way Eclipse it does for years:
> >
> > 1) Everything inside **/internal/ packages is non API by definition
> > 2) MANIFEST.MF to use OSGI "Export-Package" attribute for "published"
> > packages
> > 3) Javadoc @noextend tag for classes not intended to be extended
> > 4) Javadoc @noimplement tag for interfaces
> >
> > If "real" annotations were used for points 3 and 4, they could live
> alongside a Java (6) Processor that, if the user had annotation processing
> enabled, could fail the build (pretty sure this is doable).

But where do these annotations live? Does each Commons component duplicate
them?

Gary
>
> Matt
>
>
> > A bonus for libraries with correct MANIFEST.MF is that they can be
> > directly used as bundles inside any OSGI container (also Eclipse).
> >
> > Example:
> > /**
> >  * An observable value whose changes can be vetoed by listeners.
> >  *
> >  * @param 
> >  *the type of value being observed
> >  *
> >  * @noextend This interface is not intended to be extended by clients.
> >  * @noimplement This interface is not intended to be implemented by
> > clients.
> >  *  Clients should instead subclass one of the classes that
> >  *  implement this interface. Note that direct implementers
of
> > this
> >  *  interface outside of the framework will be broken in
future
> >  *  releases when methods are added to this interface.
> >  *
> >  * @since 1.0
> >  *
> >  */
> > public interface IVetoableValue extends IObservableValue {
> >
> > Kind regards,
> > Andrey Loskutov
> >
> > http://google.com/+AndreyLoskutov
> >
> >
> > > Gesendet: Dienstag, 14. Juni 2016 um 09:03 Uhr
> > > Von: "Jörg Schaible" 
> > > An: dev@commons.apache.org
> > > Betreff: Re: [ALL] About binary compatibility
> > >
> > > Hi,
> > >
> > > James Carman wrote:
> > >
> > > > Agree we should have a "source of truth". Is there something wrong
with
> > > > using an "internal" or "impl" package name? The bundle plugin for
OSGi
> > > > doesn't export these by default, which would be a nice side effect!
:).
> > >
> > > While it is a step in the right direction, a package scoped solution
does
> > > not solve the problem of a public interface that should not be
> > implemented
> > > directly (as we've seen with the BCEL visitor). Time for Java 8 and
its
> > > default implementations ...
> > >
> > > Cheers,
> > > Jörg
> >
> > -
> > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> > For additional commands, e-mail: dev-h...@commons.apache.org
> >
> >

Re: Re: [ALL] About binary compatibility

[Matt Benson]

On Tue, Jun 14, 2016 at 2:14 AM, Andrey Loskutov  wrote:

> I like the way Eclipse it does for years:
>
> 1) Everything inside **/internal/ packages is non API by definition
> 2) MANIFEST.MF to use OSGI "Export-Package" attribute for "published"
> packages
> 3) Javadoc @noextend tag for classes not intended to be extended
> 4) Javadoc @noimplement tag for interfaces
>
> If "real" annotations were used for points 3 and 4, they could live
alongside a Java (6) Processor that, if the user had annotation processing
enabled, could fail the build (pretty sure this is doable).

Matt


> A bonus for libraries with correct MANIFEST.MF is that they can be
> directly used as bundles inside any OSGI container (also Eclipse).
>
> Example:
> /**
>  * An observable value whose changes can be vetoed by listeners.
>  *
>  * @param 
>  *the type of value being observed
>  *
>  * @noextend This interface is not intended to be extended by clients.
>  * @noimplement This interface is not intended to be implemented by
> clients.
>  *  Clients should instead subclass one of the classes that
>  *  implement this interface. Note that direct implementers of
> this
>  *  interface outside of the framework will be broken in future
>  *  releases when methods are added to this interface.
>  *
>  * @since 1.0
>  *
>  */
> public interface IVetoableValue extends IObservableValue {
>
> Kind regards,
> Andrey Loskutov
>
> http://google.com/+AndreyLoskutov
>
>
> > Gesendet: Dienstag, 14. Juni 2016 um 09:03 Uhr
> > Von: "Jörg Schaible" 
> > An: dev@commons.apache.org
> > Betreff: Re: [ALL] About binary compatibility
> >
> > Hi,
> >
> > James Carman wrote:
> >
> > > Agree we should have a "source of truth". Is there something wrong with
> > > using an "internal" or "impl" package name? The bundle plugin for OSGi
> > > doesn't export these by default, which would be a nice side effect! :).
> >
> > While it is a step in the right direction, a package scoped solution does
> > not solve the problem of a public interface that should not be
> implemented
> > directly (as we've seen with the BCEL visitor). Time for Java 8 and its
> > default implementations ...
> >
> > Cheers,
> > Jörg
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
>

Re: Re: [ALL] About binary compatibility

[Andrey Loskutov]

I like the way Eclipse it does for years:

1) Everything inside **/internal/ packages is non API by definition
2) MANIFEST.MF to use OSGI "Export-Package" attribute for "published" packages
3) Javadoc @noextend tag for classes not intended to be extended
4) Javadoc @noimplement tag for interfaces

A bonus for libraries with correct MANIFEST.MF is that they can be directly 
used as bundles inside any OSGI container (also Eclipse).

Example:
/**
 * An observable value whose changes can be vetoed by listeners.
 *
 * @param 
 *the type of value being observed
 *
 * @noextend This interface is not intended to be extended by clients.
 * @noimplement This interface is not intended to be implemented by clients.
 *  Clients should instead subclass one of the classes that
 *  implement this interface. Note that direct implementers of this
 *  interface outside of the framework will be broken in future
 *  releases when methods are added to this interface.
 *
 * @since 1.0
 *
 */
public interface IVetoableValue extends IObservableValue {

Kind regards,
Andrey Loskutov

http://google.com/+AndreyLoskutov


> Gesendet: Dienstag, 14. Juni 2016 um 09:03 Uhr
> Von: "Jörg Schaible" 
> An: dev@commons.apache.org
> Betreff: Re: [ALL] About binary compatibility
>
> Hi,
> 
> James Carman wrote:
> 
> > Agree we should have a "source of truth". Is there something wrong with
> > using an "internal" or "impl" package name? The bundle plugin for OSGi
> > doesn't export these by default, which would be a nice side effect! :).
> 
> While it is a step in the right direction, a package scoped solution does 
> not solve the problem of a public interface that should not be implemented 
> directly (as we've seen with the BCEL visitor). Time for Java 8 and its 
> default implementations ...
> 
> Cheers,
> Jörg

-
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org