这种客户端的API是大家最喜闻乐见的,说白了就是拿给人直接实现一个功能而调用的。这种API的写法要接受的考验主要是你的用户,因为你一个公开了这个API,谁也无法保证这个API到底使用没有。当然,你只能默认有人用了,所以说你能做的就是只增不减的暴露这个java类的功能来做到向后兼容。
由于这种API无法收敛的性质,我们得不得保留以前版本关联的所有字段、方法和类型。也只有这样用户基于以前写的代码可以沿用并且更新后得到新的“惊喜”。说到这里,应该不难猜出这种API的写法了。
/**
* This is a standard Client API format.
* <li>It is "final" which means it doesn't accept any sort of extension
* one cannot cause binary Backward Compatibility problems by adding new methods into such class</li>
* <li>Exposing only final classes to users of a ClientAPI makes it bullet-proof</li>
*
* @author Big Daydream
*
*/
public final class ClientAPI {
public final void methodVersion1(){
//since 1.0 , modifier final is automatic
}
public final void methodVersion2(){
//since 2.0 , modifier final is automatic
}
}
提供者API
这种API跟上面讲的最大的区别在于,它不仅仅是被调用的,他是用来给用户去实现的。这样的区别让它看起来更像插件或者SPI,然而他的的确确是API因为他跟客户API一样,一旦释放出来就不能收回了。
这样的接口(不仅是语法上的接口,也可能是抽象类等)提供了给用户展现才华的基点,但它内部的调用策略是对用户隐藏的,我们可以在每个版本中控制它的调用方式。这种非final的语法特性决定了任意添加方法不是向后兼容的(据说JAVA8会提供这种语法支持 who knows?)。下面便是这样的API通用的写法:
/**
* This is a recommanded format for ProviderAPI<p>
*
* The choice between the two interfaces clearly defines version which the provider implements.
* One can use instanceof to check whether the provider implemented old contract only or also the new one.
* According to result of the instanceof check, you can switch and behave .<p>
*
* Of course you don't want to spread instanceof calls all over the user's code.
* But if the ProviderAPIVersion1 interface is used only inside of ClientAPI,
* then few additional instanceof checks don't harm any user of the ClientAPI
* (just the API writer, which is always a limited and thus acceptable damage).<p>
*
* The list of additional interfaces that can be implemented is sometimes hard to find.
* As the previous code snippet shows,
* it helps if they are nested interface inside the most general (original) one.
* When the providers write their implementations,
* they directly see all available extensions added in later revisions of the API.<p>
*
* @author Big Daydreamer
*
*/
public interface ProviderAPIVersion1 {
void methodVersion1();
public interface ProviderAPIVersion2 extends ProviderAPIVersion1{
void methodVersion2();
}
}