[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[eclipse.org-architecture-council] Fw: [eclipse-dev] API tooling now supports the @noextend restriction on interfaces

Project mentors may want to instruct/guide their projects on this issue.

Darin Wright

----- Forwarded by Darin Wright/Ottawa/IBM on 11/24/2008 09:25 AM -----

Darin Wright/Ottawa/IBM@IBMCA 
Sent by: eclipse-dev-bounces@xxxxxxxxxxx
11/21/2008 02:55 PM
Please respond to
"General development mailing list of the Eclipse project." 
<eclipse-dev@xxxxxxxxxxx>


To
cross-project-issues-dev@xxxxxxxxxxx, eclipse-dev@xxxxxxxxxxx
cc

Subject
[eclipse-dev] API tooling now supports the @noextend restriction on 
interfaces






API tooling now supports the @noextend restriction on interfaces. 
Components with API interfaces should read/follow instructions below.

** What is affected: **

API interfaces defined with the @noimplement restriction.

** Description:  **

In release 3.4 (Ganymede) and earlier, API tooling supported one 
restriction for API interfaces - @noimplement. This restriction indicated 
an interface was not to be implemented *or* extended by clients. To allow 
for more flexibility, Eclipse 3.5 (Galileo) separates these concerns with 
two restrictions - @noimplement and @noextend. This allows an interface to 

be extended when it is not intended to be implemented directly. For 
example, in some cases clients are not allowed to implement an interface 
directly, but can subclass an existing implementation and extend the base 
interface/class with extra function (@see 
https://bugs.eclipse.org/bugs/show_bug.cgi?id=230189 for a discussion and 
examples).

** Action required:  **

Component owners need to decide where to add @noextend tags on existing 
interfaces.

To have exactly the same API contract as specified in 3.4, @noextend tags 
can be added to all interfaces specified as @noimplement. However, this 
can be decided on a case by case basis. Generally, the @noextend can be 
omitted, as clients that extend and implement a @noimplement interface 
will still be flagged with errors. However, if you would like to reserve 
the right to add constants (public static final fields) to an API 
interface in the future, you must add the @noextend tag. This is because 
adding a field to an interface is binary incompatible if clients can 
extend or implement an interface (@see 
http://wiki.eclipse.org/Evolving_Java-based_APIs_2#Evolving_API_Interfaces
). 
Adding an API restriction to a class/interface is usually an error - 
however, API tooling allows you to add @noextend tags without penalty in 
release 3.5, since this specifies the same contract as in 3.4. If you were 

to wait until a later release to add the additional tag, and error would 
be generated.


Darin Wright
_______________________________________________
eclipse-dev mailing list
eclipse-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe 
from this list, visit
https://dev.eclipse.org/mailman/listinfo/eclipse-dev