Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "PDE/API Tools/Restrictions"
(New page: {{API_Tools}} Special Javadoc tags are used to annotate code with API information. The Javadoc tags are intended to replace existing <code>component.xml</code> files (which have to be mai...) |
m (Cwindatt.ca.ibm.com moved page PDE/API Tools/Javadoc Tags to PDE/API Tools/Restrictions: Restrictions can be specified using Javadoc tags or annotations) |
(No difference)
| |
Latest revision as of 15:01, 5 June 2014
| API Tools | |
| Website | |
| Download | |
| Community | |
| Mailing List • Forums • IRC • mattermost | |
| Issues | |
| Open • Help Wanted • Bug Day | |
| Contribute | |
| Browse Source |
Special Javadoc tags are used to annotate code with API information. The Javadoc tags are intended to replace existing component.xml files (which have to be maintained manually). The tooling defines a fixed set of restrictions that can be assocaited with an extensible set of javadoc tags. The restrictions currently supported are:
-
@noreference- Indicates that other bundles must not reference this member by name. I.e., the member is internal. This tag is intended to be used very rarely when a public class wants to restrict access to one of its members, but is not intended for general usage. When this tag is applied to a type (class, interface, enum or annotation) it acts as though it has been applied to all of the members of that type. If the tag is applied to a type it does not apply to final fields. -
@noimplement- Indicates that other bundles must not implement this interface. This tag is ignored for all types except for interfaces. -
@noextend- Indicates that other bundles must not extend the class or interface it appears on. This tag is ignored for all members that are not interfaces or classes. -
@noinstantiate- Indicates that other bundles must not create instances of this class. This tag is ignored for all other types that are not classes. -
@nooverride- Indicates that other bundles must not extend (re-implement with a call to the overridden parent) or re-implement (with no call to the overridden parent) this method. This tag is ignored for all other members except method declarations.
Defining API Restrictions
API Tools provides Javadoc tags to explicitly document and restrict the use of API. The following tables summarize the Javadoc tags supported by each member and the semantics of each tag.
A client refers to a plug-in or bundle that requires the bundle where the associated API is defined. Restrictions are not applied in the same bundle where API is defined. For example, a bundle that defines an interface as @noimplement is also allowed to provide an implementation of that interface.
| Class | Interface | Enum | Annotation | Method | Constructor | Field (non-final) | |
|---|---|---|---|---|---|---|---|
| @noimplement | |||||||
| @noextend | |||||||
| @noinstantiate | |||||||
| @nooverride | |||||||
| @noreference |
When applied to a type or member, each tag has a specific meaning. The following table describes what each tag means when applied.
| @noimplement | Indicates that clients must not implement this interface. Any class using the implements keyword for the associated interface or parent of the associated interface where there is no implementing superclass will be flagged with problem. |
|---|---|
| @noextend | Indicates that clients must not extend this class or interface. Any class or interface using the extends keyword for the associated type will be flagged with a problem. |
| @noinstantiate | Indicates that clients must not instantiate this class. Any code that instantiates the associated class with any constructor will be flagged with a problem. |
| @nooverride | Indicates that clients must not redeclare this method. Any subclass that defines a method that overrides the associated method will be flagged with a problem. |
| @noreference | Indicates that clients must not reference this type (class, interface, enum, or annotation), method, constructor, or non-final field. Any code that directly invokes the associated method or constructor or references the associated non-final field will be flagged with a problem.
When the tag is used on a type, it behaves as though the tag was added to any of the types members. For example adding the tag to class will flag any references to any methods or non-final fields from that class. |
Links
Ant Tasks - Description of the Ant Tasks available in API Tools
API Tooling Architecture - High level description of the tooling's architecture.
Evolving Java-based APIs - What is considered an API in Eclipse.
Version Numbering - Guidelines on versioning plug-ins
PDE/Incubator - New projects that might be incorporated into PDE in future.
PDE UI Home Page - The main PDE UI web site.