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 "Xtext/Documentation/API"
m (→API lifecycles and contracts in Xtext) |
|||
| Line 5: | Line 5: | ||
In order to communicate what's stable, we tag interfaces and classes with the annotation @org.eclipse.xtext.Stable. | In order to communicate what's stable, we tag interfaces and classes with the annotation @org.eclipse.xtext.Stable. | ||
| − | In most cases we follow a common pattern, where we tag an interface with @Stable and add a pointer to the abstract class you need to subclass in order to be sure that we don't break your code in future releases. This is because we might want to add additional methods to those interfaces. As long as you also subclass a common base class, we can provide default implementations. | + | In most cases we follow a common pattern, where we tag an interface with @Stable and add a pointer to the abstract class you need to subclass in order to be sure that we don't break your code in future releases. This is because we might want to add additional methods to those interfaces. As long as you also subclass a common base class, we can provide reasonable default implementations or at least throw exceptions, that will be handled by the framework. |
Example: | Example: | ||
| Line 13: | Line 13: | ||
... | ... | ||
} | } | ||
| + | |||
| + | We will not remove any existing method or change its signature without notice. Furthermore their preconditions will not be weakend nor will the postcondition be strengthend. That means, for example, that a method, that never got a null value as an argument, has suddenly to deal with nulls in the next release. If we provide an API, for which the implementor has to fulfil some documented invariants, we will not strengthen them. | ||
==== @Deprecated annotation ==== | ==== @Deprecated annotation ==== | ||
| − | We also use the @java.lang.Deprecated annotation in order to mark API as deprecated. | + | We also use the @java.lang.Deprecated annotation in order to mark API as deprecated. As for the @Stable annotation, this allows to search for references to this annotation in the Xtext framework code, to identify the parts of the API, that are obsolete. Furthermore, we will document deprecation in the javadoc to inform clients about the necessary steps to remain compatible to future versions. |
| + | |||
If a stable API is annotated with @Deprecated it means that we might remove it in the next major release. | If a stable API is annotated with @Deprecated it means that we might remove it in the next major release. | ||
This means that if stable API is annotated with @Deprecated in 0.7.0 it will remain in 0.x but might be removed in 1.x releases. | This means that if stable API is annotated with @Deprecated in 0.7.0 it will remain in 0.x but might be removed in 1.x releases. | ||
| + | |||
| + | If we remove an interface method, that has been marked as deprectated before, we will leave a method stub with the same signature in the abstract base class. This one will be changed to protected visibility and tagged final to ensure compile time errors for existing clients, that didn't refactor their implementation accordingly. | ||
Revision as of 04:09, 6 March 2009
API lifecycles and contracts in Xtext
We distinguish between technically visible and published API. That means not everything which is technically visible is considered as published or stable API. We have lot's of useful things you may want to use, and we think it's important to allow that but at the same time communicate clearly which bits stay as is and which might be changed in future releases.
@Stable annotation
In order to communicate what's stable, we tag interfaces and classes with the annotation @org.eclipse.xtext.Stable.
In most cases we follow a common pattern, where we tag an interface with @Stable and add a pointer to the abstract class you need to subclass in order to be sure that we don't break your code in future releases. This is because we might want to add additional methods to those interfaces. As long as you also subclass a common base class, we can provide reasonable default implementations or at least throw exceptions, that will be handled by the framework.
Example:
@Stable(since="0.7.0", subClass=AbstractScope.class)
public interface IScope {
...
}
We will not remove any existing method or change its signature without notice. Furthermore their preconditions will not be weakend nor will the postcondition be strengthend. That means, for example, that a method, that never got a null value as an argument, has suddenly to deal with nulls in the next release. If we provide an API, for which the implementor has to fulfil some documented invariants, we will not strengthen them.
@Deprecated annotation
We also use the @java.lang.Deprecated annotation in order to mark API as deprecated. As for the @Stable annotation, this allows to search for references to this annotation in the Xtext framework code, to identify the parts of the API, that are obsolete. Furthermore, we will document deprecation in the javadoc to inform clients about the necessary steps to remain compatible to future versions.
If a stable API is annotated with @Deprecated it means that we might remove it in the next major release. This means that if stable API is annotated with @Deprecated in 0.7.0 it will remain in 0.x but might be removed in 1.x releases.
If we remove an interface method, that has been marked as deprectated before, we will leave a method stub with the same signature in the abstract base class. This one will be changed to protected visibility and tagged final to ensure compile time errors for existing clients, that didn't refactor their implementation accordingly.