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
> >>>>
> >>>>
> >>>>
> >>>>
> >>>>
> >>>
> >>>
> >>>
> >
> >
> >
>
