Some additional comments.
a) freezing should include a notion of versioning, similar to what
javadoc does using @since, this allows you to build in from the
beginning a notion of versioning to deal with later changes to frozen
code. Cause it will happen. ;)
b) we need to establish a policy for beehive regarding under
construction, freezing policy, compatibility between releases
(major/minor) of frozen public methods as well as a deprecation policy.
BEA has policies for this already, however Beehive needs to establish
this as well for itself, even if they are initially aligned with what
BEA has decided, they should be published as part of Beehive.
Who would you like to be on point to deliver this?
Cheers
mbg
> -----Original Message-----
> From: Kyle Marvin
> Sent: Monday, October 11, 2004 9:19 AM
> To: Beehive Developers
> Subject: RE: [proposal] frozen/non-frozen interfaces
>
> For externally exposed ("public") interfaces, it is worth
> noting that there are actually two sub-types:
>
> 1. Ones where an end user is expected to provide
> implementation classes of 2. Ones where user code might write
> code against the interface, but doesn't provide the implementation
>
> The Controls runtime has lots of examples of #2... in fact,
> all public APIs are separated out in the
> org.apache.beehive.controls.api package space. Often, there
> are corresponding implementations in
> org.apache.beehive.controls.runtime that are the (private)
> runtime implementation of the public APIs.
>
> For type #1 above, freezing interfaces is important to avoid
> breaking user code. If you add a method, then suddenly all
> user-authored implementations become broken.
>
> For type #2 above, a more relaxed constraint of ensuring that
> the interface remains syntactically and semantically
> compatible seems OK. This is because the public APIs and
> supporting impls will always version and ship together as
> newer versions of the runtime are provided (both live in
> controls.jar). It is OK to add methods here, as long as the
> added methods don't in any way change the behavior of
> existing methods.
>
> -- Kyle
>
> > -----Original Message-----
> > From: Richard Feit
> > Sent: Saturday, October 09, 2004 11:48 AM
> > To: Beehive Developers
> > Subject: Re: [proposal] frozen/non-frozen interfaces
> >
> >
> > That's probably the essence of what we need. So would an
> @frozen (or
> > @incomplete) annotation make sense across the project?
> >
> > Daryl Olander wrote:
> >
> > >I agree that until a major release we should have freedom
> to change
> > >newly introduced APIs. Perhaps we should mark these in some
> > way, such
> > >as the unfrozen annotation.
> > >
> > >
> > >On Sat, 09 Oct 2004 10:21:37 -0600, Richard Feit
> > <[EMAIL PROTECTED]> wrote:
> > >
> > >
> > >>Interesting. In the ServerAdapter case, I can see
> > switching to a base
> > >>class rather than using an interface. But if we do have other
> > >>interfaces or classes that are marked public only for our
> internal
> > >>cross-package use, we should simply have a clear standard for
> > >>identifying which ones are internal.
> > >>
> > >>An unresolved issue, though, is public interfaces that are "under
> > >>construction". I'd argue that even if we do a point release,
> > >>ServerAdapter isn't ready for public (user) use. Brave
> > souls can try
> > >>it, but I'd like for there to be some way to mark an
> > interface as not
> > >>ready for public consumption. Seem like a valid goal?
> > >>
> > >>Rich
> > >>
> > >>
> > >>
> > >>Daryl Olander wrote:
> > >>
> > >>
> > >>
> > >>>In general, I agree except for having unfrozen public
> > exposed interfaces..
> > >>>
> > >>>I think what we really should do is have two classes of code,
> > >>>externally exposed and internal.
> > >>>
> > >>>For all externally exposed classes, we must maintain the
> > >>>public/protected signature of the class. For example,
> in the Tag
> > >>>set, there are a set of base classes and we should
> maintain their
> > >>>public/protected signature (not removing methods, and
> maintaining
> > >>>existing method signatures, maintaining semantics). We
> can add new
> > >>>methods and overloads, and deprecate existing methods.
> We should
> > >>>create a test suite that verifies this signature.
> > >>>
> > >>>For externally exposed interfaces there may be no change
> at all to
> > >>>them. If a change needs to be made we need to introduce a new
> > >>>interface (xxxxEx or xxxx2) which will produce the hell
> MS has in
> > >>>their APIs.
> > >>>
> > >>>For internal packages and classes, these will be clearly
> > marked and
> > >>>we can change them from release to release. Of course, if
> > we find a
> > >>>wide spread use of an internal API, we may be force to not
> > change it
> > >>>also. This is basically community promotion of an
> > internal API to an
> > >>>external API.
> > >>>
> > >>>If we do support "unfrozen" APIs, we need to be very
> > careful and not
> > >>>use this much because we are stating that something is
> > public, but may
> > >>>change and break code. I'm not sure If I really agree
> > with this. I
> > >>>think a better design pattern is to avoid Interfaces and
> > instead use
> > >>>base classes because they may be changed.
> > >>>
> > >>>
> > >>>On Fri, 08 Oct 2004 11:04:30 -0600, Richard Feit
> > <[EMAIL PROTECTED]> wrote:
> > >>>
> > >>>
> > >>>
> > >>>
> > >>>>OK, taking a cue from Mozilla's XPCOM... what do we think
> > about making a
> > >>>>distinction between frozen and non-frozen interfaces?
> Simply put,
> > >>>>frozen interfaces never change, while non-frozen
> > interfaces can change.
> > >>>>I'd imagine that:
> > >>>> a) new interfaces are non-frozen until a release
> > >>>> b) all end-user interfaces (e.g.,
> > >>>>org.apache.beehive.controls.api.bean.Extensible) get
> > frozen at a release
> > >>>> c) internal/advanced interfaces (e.g.,
> > >>>>org.apache.beehive.netui.pageflow.ServerAdapter) don't
> > necessarily get
> > >>>>frozen, so implementors may have to add or change methods
> > when upgrading
> > >>>>to a new release.
> > >>>>
> > >>>>If we did this, we could have a simple annotation to
> denote frozen
> > >>>>interfaces, like @frozen.
> > >>>>
> > >>>>The alternative, of course, is to assume *all* interfaces
> > are frozen at
> > >>>>a release: we can never change signatures, and if we ever
> > want to add
> > >>>>something, we add a new interface (ServerAdapter2,
> > ServerAdapter3, etc.)
> > >>>>in the Microsoft vein.
> > >>>>
> > >>>>Thoughts?
> > >>>>
> > >>>>Rich
> > >>>>
> > >>>>
> > >>>>
> > >>>>
> > >>>>
> > >>>
> > >>>
> > >>>
> > >
> > >
> > >
> >
>
>
