Rodin 3.0 Plug-in Migration Guide: Difference between revisions

From Event-B
Jump to navigationJump to search
← Older editNewer edit →
imported>Vinmont
imported>Laurent
Line 7: Line 7:


== AST Library ==
== AST Library ==
=== Type Environments ===


Type environments have changed in Rodin 3.0 in order to reinforce their good use and their robustness.  
Type environments have changed in Rodin 3.0 in order to reinforce their good use and their robustness.  
Line 15: Line 17:
Let's consider that you dispose of a new type environment of type '''ITypeEnvironmentBuilder''', in some cases you will need to provide it as a parameter and you will face 3 options depending on the parameter Java type:
Let's consider that you dispose of a new type environment of type '''ITypeEnvironmentBuilder''', in some cases you will need to provide it as a parameter and you will face 3 options depending on the parameter Java type:
* It is a '''ISealedTypeEnvironment''': you must provide an immutable snapshot of your type environment using method ''makeSnapshot()''.
* It is a '''ISealedTypeEnvironment''': you must provide an immutable snapshot of your type environment using method ''makeSnapshot()''.
* It is a '''ITypeEnvrionmentBuilder''': here two choices are possible, you could give your object reference as parameter and it will be modified if a further treatment is made on it or you could give a copy of your object using method ''makeBuilder()'' to prevent side effect on your object.
* It is a '''ITypeEnvironmentBuilder''': here two choices are possible, you could give your object reference as parameter and it will be modified if a further treatment is made on it or you could give a copy of your object using method ''makeBuilder()'' to prevent side effect on your object.
* It is a '''ITypeEnvrionment''': it is a convenient way to have genericity since it is the super type of both precedent you could choose every precedent options explained. It must be known that, as described in API documentation, we explicitly prohibit to cast from ITypeEnvironment to one of its children types. As a consequence you should consider that your type environment will not be modified. But since it is a weak guarantee, respect of this guideline could be ensured by us only in the Rodin core part.
* It is a '''ITypeEnvrionment''': it is a convenient way to have genericity since it is the super type of both preceding ones. You can opt for any options above. There is a convention that a parameter of type ITypeEnvironment is not modified by the callee, but this is not enforced. If you want a strong guarantee that the type environment that you pass cannot be modified, pass it as a sealed environment.


Reciprocally, if you ask a type environment as parameter, those 3 options are available:
Reciprocally, if you ask for a type environment as parameter, these 3 options are available:
* Use a '''ISealedTypeEnvironment''': if you need the guarantee that no side effect will modify the received type environment
* Use a '''ISealedTypeEnvironment''': if you want to provide a strong guarantee that you will not modify the parameter.
* Use a '''ITypeEnvrionmentBuilder''': in all cases you will need to modify the received type environment
* Use a '''ITypeEnvrionmentBuilder''': if you need to modify the received type environment by side effect
* Use a '''ITypeEnvrionment''': in case you will not directly modify the type environment and allow the user to provide the most convenient type for him. You have to notice that if the guideline forbids you to cast it to its children types, which forbids modification of the type environment for you, the provider could modify it if its implementation has the '''ITypeEnvironmentBuilder''' type.
* Use a '''ITypeEnvrionment''': in case you will not modify the type environment and allow the user to provide the most convenient type for him. You must not later cast the parameter to type '''ITypeEnvironmentBuilder'''.


Finally regarding methods, you could return a type environment and only 2 choices must be used ('''ITypeEnvironment''' is discouraged since it provides no information and both children types could be casted further):
Finally regarding return type of methods, you should use only one of the two following choices ('''ITypeEnvironment''' is discouraged since it provides no information about what is actually returned):
* Return a '''ISealedTypeEnvironment''': it guarantees that the type environment will not mutate and allow to share its reference as long as no modification is needed.
* Return a '''ISealedTypeEnvironment''': it guarantees that the type environment will not mutate and allow to share its reference as long as no modification is needed.
* Return a '''ITypeEnvrionmentBuilder''': it allows modifications and must be use in case no reference is kept on the object or if you want to share the modifications on it.
* Return a '''ITypeEnvrionmentBuilder''': it allows modifications and must be used in case no reference is kept on the object or if you want to share the modifications on it.


And the last case but not the least, if you create a type environment field you have also 2 options:
And the last case but not the least, if you create a type environment field you have also 2 options:
* You should use a '''ISealedTypeEnvironment''' in one of these cases:
* You should use a '''ISealedTypeEnvironment''' in one of these cases:
** It is never modified or has an immutable behavior expected.
** It is never modified or has an expected immutable behavior.
** The type environment is built all at once and is not modified later.
** The type environment is built all at once and is never modified later.
** You need to return a copy of it often (allow to share the reference) and modify it only rarely.
** You need to return a copy of it often (allows to share the reference) and modify it only rarely.
* You should use a '''ITypeEnvironmentBuilder''' in one fo these cases:
* You should use a '''ITypeEnvironmentBuilder''' in one of these cases:
** The field is only internal to the class (and has builder type at least one time).
** The field is only internal to the class (and has builder type at least one time).
** The type environment is built to be returned externally and the reference can be shared.
** The type environment is built to be returned externally and the reference can be shared.


 
Those precendent cases are only the most general examples that you will face and are made to give an idea of the new API good usage, but finally the developper is the only person that can decide of the better option to choose.  
Those precendent cases are only the most general examples that you will face and are made to give an idea of the new API good use, but finally the developper is the only person that can decide of the better option to choose.  


[[Category:Developer documentation]]
[[Category:Developer documentation]]

Revision as of 10:33, 18 December 2012

Release 3.0 of the Rodin platform introduces important changes to the Rodin Platform API. These changes make the core platform stronger and fix some erroneous design decisions that were taken in previous Rodin releases.

This guide details the actions that plug-in developers must take in order to port their plug-ins from the 2.7 API to the 3.0 API.

AST Library

Type Environments

Type environments have changed in Rodin 3.0 in order to reinforce their good use and their robustness. One of these changes concerns their mutability state and has an important impact on type environments use.

The general principle is the following, if you want to create and build a type environment then you have to use a ITypeEnvironmentBuilder which is the only type providing methods that could modify the type environment. Then in some case you could need to guarantee that your type environment will not mutate anymore and make a snapshot of type ISealedTypeEnvironment.

Let's consider that you dispose of a new type environment of type ITypeEnvironmentBuilder, in some cases you will need to provide it as a parameter and you will face 3 options depending on the parameter Java type:

  • It is a ISealedTypeEnvironment: you must provide an immutable snapshot of your type environment using method makeSnapshot().
  • It is a ITypeEnvironmentBuilder: here two choices are possible, you could give your object reference as parameter and it will be modified if a further treatment is made on it or you could give a copy of your object using method makeBuilder() to prevent side effect on your object.
  • It is a ITypeEnvrionment: it is a convenient way to have genericity since it is the super type of both preceding ones. You can opt for any options above. There is a convention that a parameter of type ITypeEnvironment is not modified by the callee, but this is not enforced. If you want a strong guarantee that the type environment that you pass cannot be modified, pass it as a sealed environment.

Reciprocally, if you ask for a type environment as parameter, these 3 options are available:

  • Use a ISealedTypeEnvironment: if you want to provide a strong guarantee that you will not modify the parameter.
  • Use a ITypeEnvrionmentBuilder: if you need to modify the received type environment by side effect
  • Use a ITypeEnvrionment: in case you will not modify the type environment and allow the user to provide the most convenient type for him. You must not later cast the parameter to type ITypeEnvironmentBuilder.

Finally regarding return type of methods, you should use only one of the two following choices (ITypeEnvironment is discouraged since it provides no information about what is actually returned):

  • Return a ISealedTypeEnvironment: it guarantees that the type environment will not mutate and allow to share its reference as long as no modification is needed.
  • Return a ITypeEnvrionmentBuilder: it allows modifications and must be used in case no reference is kept on the object or if you want to share the modifications on it.

And the last case but not the least, if you create a type environment field you have also 2 options:

  • You should use a ISealedTypeEnvironment in one of these cases:
    • It is never modified or has an expected immutable behavior.
    • The type environment is built all at once and is never modified later.
    • You need to return a copy of it often (allows to share the reference) and modify it only rarely.
  • You should use a ITypeEnvironmentBuilder in one of these cases:
    • The field is only internal to the class (and has builder type at least one time).
    • The type environment is built to be returned externally and the reference can be shared.

Those precendent cases are only the most general examples that you will face and are made to give an idea of the new API good usage, but finally the developper is the only person that can decide of the better option to choose.

Core Event-B Plug-in

All constants, methods and classes that were marked as deprecated in the API have been removed. If you were using one of these, please read its Javadoc in Rodin 2.7 which describes an alternative implementation.

Retrieved from ‘https://wiki.event-b.org/index.php?title=Rodin_3.0_Plug-in_Migration_Guide&oldid=6961’