ClientAPI
From APIDesign
| Line 8: | Line 8: | ||
What is the most suitable coding construct in [[Java]] to support an ''open space''? The most safe one is a '''final''' class. As such it is suggested to expose only '''final''' classes to users of [[ClientAPI]]. | What is the most suitable coding construct in [[Java]] to support an ''open space''? The most safe one is a '''final''' class. As such it is suggested to expose only '''final''' classes to users of [[ClientAPI]]. | ||
| + | |||
| + | <source lang="java"> | ||
| + | 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); | ||
| + | } | ||
| + | </source> | ||
The shape of [[ProviderAPI]] is quite different. Can you imagine the result, when you mix goals of your [[API]] and create a single class which serves as [[ClientAPI]] as well as [[ProviderAPI]]? You'll be trying to fit an ''open space'' into a singular point (natural representation of a [[ProviderAPI]]). The result is that you'll be forbidden to [[evolution|evolve]] your [[API]] in any way. If you publish non-final class, or even interface, you'll face [[evolution]] problems as described at [[ExtendingInterfaces]]. | The shape of [[ProviderAPI]] is quite different. Can you imagine the result, when you mix goals of your [[API]] and create a single class which serves as [[ClientAPI]] as well as [[ProviderAPI]]? You'll be trying to fit an ''open space'' into a singular point (natural representation of a [[ProviderAPI]]). The result is that you'll be forbidden to [[evolution|evolve]] your [[API]] in any way. If you publish non-final class, or even interface, you'll face [[evolution]] problems as described at [[ExtendingInterfaces]]. | ||
Revision as of 20:14, 19 March 2011
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 the only use of your API is to be called, then the obvious requirement is to be to add more methods and to allow the users to call more of 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 one, don't need to care about the new ones. Clients seeking for new functionality will be pleased when it appears 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. As such it is suggested to expose only final classes to users of ClientAPI.
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. Can you imagine the result, when you mix goals of your API and create a single class which serves as ClientAPI as well as ProviderAPI? You'll be trying to fit an open space into a singular point (natural representation of a ProviderAPI). The result is that you'll be forbidden to evolve your API in any way. If you publish non-final class, or even interface, you'll face evolution problems as described at ExtendingInterfaces.
Follow
