You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@beehive.apache.org by Richard Feit <ri...@bea.com> on 2004/10/08 19:04:30 UTC
[proposal] frozen/non-frozen interfaces
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
Re: [proposal] frozen/non-frozen interfaces
Posted by Richard Feit <ri...@bea.com>.
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 <ri...@bea.com> 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 <ri...@bea.com> 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
>>>>
>>>>
>>>>
>>>>
>>>>
>>>
>>>
>>>
>
>
>
Re: [proposal] frozen/non-frozen interfaces
Posted by Daryl Olander <do...@gmail.com>.
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 <ri...@bea.com> 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 <ri...@bea.com> 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
> >>
> >>
> >>
> >
> >
> >
>
Re: [proposal] frozen/non-frozen interfaces
Posted by Richard Feit <ri...@bea.com>.
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 <ri...@bea.com> 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
>>
>>
>>
>
>
>
Re: [proposal] frozen/non-frozen interfaces
Posted by Daryl Olander <do...@gmail.com>.
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 <ri...@bea.com> 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
>