ClientAPI
From APIDesign
(2 intermediate revisions not shown.) | |||
Line 1: | Line 1: | ||
- | |||
- | |||
[[Image:OpenSpace.png|thumb|right]] | [[Image:OpenSpace.png|thumb|right]] | ||
- | As soon as you publish an [[API]], you, as a publisher of your library, want to have a freedom to evolve it to satisfy additional requirements of users of your library. What additional requirements can you expect? In case the | + | There is a difference between [[ClientAPI]] and [[ProviderAPI]] [[evolution]] rules. As soon as you publish an [[API]], you, as a publisher of your library, want to have a freedom to evolve it to satisfy additional requirements of users of your library. What additional requirements can you expect? In case when the [[API]] can only be called, then the obvious requirement is to add more methods and to allow users to call more of such exposed functionality. |
- | This can be envisioned as an '''open space''' which grows with a time. To keep [[BackwardCompatibility]], every method, field or class which has been present in previous releases, needs to stay. New methods can however be added as requested. Those [[ClientAPI|clients]] that used to call the previously existing | + | This can be envisioned as an '''open space''' which grows with a time. To keep [[BackwardCompatibility]], every method, field or class which has been present in previous releases, needs to stay. New methods can however be added as requested. Those [[ClientAPI|clients]] that used to call the previously existing elements, don't need to care about the new ones. [[ClientAPI|Clients]] seeking new functionality will be pleased when it gets exposed in the ''open space'' of your [[ClientAPI]]. |
- | What is the most suitable coding construct in [[Java]] to support an ''open space''? The most safe one is a '''final''' class | + | What is the most suitable coding construct in [[Java]] to support an ''open space''? The most safe one is a '''final''' class (one cannot cause binary [[BackwardCompatibility]] problems by adding new methods into such class). Exposing only '''final''' classes to users of a [[ClientAPI]] makes it bullet-proof: |
<source lang="java"> | <source lang="java"> | ||
Line 19: | Line 17: | ||
</source> | </source> | ||
- | The shape of [[ProviderAPI]] is quite different. | + | The shape of [[ProviderAPI]] is quite different. See [[APIvsSPI]] to understand what happens when you try to merge the ''open space'' with the shape associated with [[ProviderAPI]]. |
- | + | ||
- | + | ||
[[Category:APIDesignPatterns]] | [[Category:APIDesignPatterns]] | ||
[[Category:APIDesignPatterns:Evolution]] | [[Category:APIDesignPatterns:Evolution]] |
Current revision
There is a difference between ClientAPI and ProviderAPI evolution rules. As soon as you publish an API, you, as a publisher of your library, want to have a freedom to evolve it to satisfy additional requirements of users of your library. What additional requirements can you expect? In case when the API can only be called, then the obvious requirement is to add more methods and to allow users to call more of such exposed functionality.
This can be envisioned as an open space which grows with a time. To keep BackwardCompatibility, every method, field or class which has been present in previous releases, needs to stay. New methods can however be added as requested. Those clients that used to call the previously existing elements, don't need to care about the new ones. Clients seeking new functionality will be pleased when it gets exposed in the open space of your ClientAPI.
What is the most suitable coding construct in Java to support an open space? The most safe one is a final class (one cannot cause binary BackwardCompatibility problems by adding new methods into such class). Exposing only final classes to users of a ClientAPI makes it bullet-proof:
public final class Player { public void play(File mp3); public void stop(); /** @since 2.0 we can also control volume */ public void setVolume(int volume); }
The shape of ProviderAPI is quite different. See APIvsSPI to understand what happens when you try to merge the open space with the shape associated with ProviderAPI.