Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "Xtext/Documentation/API"

(→‎Binary but not source compatibility)
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
=== API lifecycles and contracts in Xtext ===
+
=== Binary but not source compatibility ===
−
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 ====
+
Xtext versions with minor increments are '''binary compatible''' with early releases of the same major version
−
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.  
+
That is you will be able to run any code, which was developed '''and compiled''' against API from 2.x with any 2.y (where y>=x) version. However you might run into compatibility problems
 +
if you try to compile or even regenerate source code which was developed against a previous version, because only micro increments (i.e. 2.x.y -> 2.x.z , where z >= y ) are also guaranteed source compatible.
  
−
Example:
+
Only if the major version increments API might be removed, replaced or changed in *binary incompatible* ways.
−
 
+
−
@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.
+

Latest revision as of 07:11, 30 January 2012

Binary but not source compatibility

Xtext versions with minor increments are binary compatible with early releases of the same major version

That is you will be able to run any code, which was developed and compiled against API from 2.x with any 2.y (where y>=x) version. However you might run into compatibility problems if you try to compile or even regenerate source code which was developed against a previous version, because only micro increments (i.e. 2.x.y -> 2.x.z , where z >= y ) are also guaranteed source compatible.

Only if the major version increments API might be removed, replaced or changed in *binary incompatible* ways.

Retrieved from "https://wiki.eclipse.org/index.php?title=Xtext/Documentation/API&oldid=287348"

This page was last modified 07:11, 30 January 2012 by Sven Efftinge. Based on work by Sebastian Zarnekow and Moritz Eysholdt.

Back to the top