Private is a category for features that are accessible but are not intended for use outside of their component (module). Such features are subject to change with every release and depending on them is risky and should be avoided.

Friend API is used for features accessible to specific components in the system, that help to overcome the lack of a real stable API, but are intended only for use between these friend components and nobody else. Often friend components are developed by the same group of people. A change to this contract can be done every release, but owners of those friend components must be notified in advance. No one else should depend on such features - the author of this API does not have the intent to create a general purpose API.

Under development is a name for a contract that is expected to become a stable API, but that has not yet been finished. The current state serves as a proof of concept, and others are encourage to try it and comment on a dedicated mailing list. Incompatible changes may be done between releases, but should be rare, not radical and properly announced on the mailing list.

Stable interfaces are those that have received a final state and the maintainers are ready to support it forever and never change them incompatibly. The "forever" and "never" should not be taken as absolute: It is possible to change the contract, but only in major versions and only after a careful considerations and in cases where it is imperative that a change be made. Stable contracts should preserve the investments of those entering into them (users of an API).

Official are stable ones and also packaged into one of NetBeans official namespaces: org.netbeans.api or org.netbeans.spi or org.openide. By packaging a contract into this package (and making it part of a release) one notifies others that the contract is stable - with all the consequence (except the conditional support for early adoptions - such modules has code base name that ends with with /0). Also, the impact of possible incompatible changes to official API should be minimized by providing compatibility bridges and keeping binary compatibility even when source one is droped (see the preservation section).

Third party interfaces are provided by other parties that do not follow the NetBeans rules and thus are hard to classify. It is prefered not to expose such interfaces as part of own contracts, in order to insulate users of NetBeans APIs from unexpected changes made in the imported interfaces.

Standard is similar to the third party classification. Also provided by someone out of NetBeans, but by someone expected to evolve the interface in compatible way (for example JSRs). The standard is expected to not change frequently.

Deprecated. After a while, nearly every API, regardless of what state it is, becomes obsoleted. Usually a new, better support for the same task has been developed which replaces the old API. In such case, mark the old API deprecated. A previously stable API that changed its stability to deprecated shall be supported for reasonable amount of time (a release) to communicate to users that they shall migrate from it to the new replacement. After that time the API can be removed from the product, while trying to preserve it for old clients by making it available in alternative ways (e. g. autoupdate centers).

At the beginning of this chapter two different ways have been mentioned how an API can be developed. Doing that spontaneously means in the light of the above API Stability categories to introduce a private or friend API, that is discovered by someone else, found useful and than evolves into stable one as described. An API developed by design is more likely to begin its life with under development API Stability status and after a bit of work can turn into stable API.

It is better to use methods (usually getters and setters) to access fields than to expose them directly. The first reason is that a call to a method can do a lot of additional things, but in contrast an access to a field can only read or write the value. When using getters one can for example do lazy initialization, synchronize the access or compose the value using some computation algorithm. Setters on the other hand allow checks for correctness of assigned value or notification of listeners when the change happens.

The other reason why to prefer methods can be found in the Java Virtual Machine specification. It is allowed to move a method from a class to one of its superclasses and still remain binary compatible. So a method initially introduced as Dimension javax.swing.JComponent.getPreferredSize(Dimension d) can be deleted in new version and moved to Dimension java.awt.Component.getPreferredSize(Dimension d) as the JComponent is a subclass of Component (this really happened in JDK 1.2). Such operation is not allowed for fields. Once a field is defined in a class, it has to stay there forever in order to keep binary compatibility. That is another reason why it is better to keep fields private.

It is more flexible to expose a factory method than to expose constructor. Once a constructor is available as part of an API, it guarantees not only that an instance assignable to a given class will be created, but also that the instance will be of the exact class (no subclasses allowed) and also that a new instance is created every time.

If instead a factory method is provided (usually a static method that takes the same arguments as the constructor and returns instance of the same class the constructor is defined in), one has more possibilities. First of all one does not need to return the exact class, but some subclass - allows to use polymophism and possibly clean up the code. Second avantage is to cache instances. While in case of constructor new instance is created every time, the factory method can cache previously instantiated objects and reuse them in order to save the memory. Another reason is the possibility of proper synchronization when invoking the factory method which is not possible (at least is limited) in case of plain constructor. These are the reasons why one shall prefer factory methods over constructors.

In a lot of cases people are not designing for subclassing and still they do not prevent it. If you are writing an API and you explicitly do not want people to subclass or implement your interfaces (also see paragraph about [#design.apiandspi API vs. SPI]) it is better to disallow that.

Simplest solution is to make your class final. Other tricks include non-public constructors (one shall do it anyway in favor of [#design.less.factory factory methods]) or making all (or at least most) methods final or private.

Of course this works only for classes, if you decide to use interfaces you cannot forbid foreign implementations on the level of virtual machine, you can only ask people in JavaDoc not to do it.

Another useful technique to not expose too much in API is to give access to certain functionality (e. g. ability to instantiate a class or to call a certain method) just to a friend code.

Java by default restricts the friends of a class to those classes that are in the same package. If there is a functionality that you want share just among classes in the same package, use package-private modifier in definition of a constructor, a field or a method and then it will remain accessible only to friends.

Sometimes however it is more useful to extend the set of friends to a wider range of classes - for example one wants to define a pure API package and put the implementation into separate one. In such cases following trick can be found useful. Imagine there is a class item (btw. also you can also check out sources from CVS):

that is part of the API, but cannot be instanitated nor listened on outside of the friend classes (but these classes are not only in api package). Then one can define an Accessor in the non-API package:

with abstract methods to access all friend functionality of the Item class and with a static field to get the accessor’s instance. The main trick is to implement the Accessor by a (non-public) class in the api package:

and register it as the default instance first time somebody touches api.Item by adding a static initializer to the Item class:

Then the friend code can use the accessor to invoke the hidden functionality from any package:

Please note that in NetBeans this is very useful in combination with specifying publicly accessible packages in module manifest (OpenIDE-Module-Public-Packages: api.**) and thus disallowing on the class loading level other modules from accessing the impl.Accessor.

Before we start, we should ask a question: Who is the client and who is the provider? Let us do it on an example of XMMS, the media player for _UNIX_es (called WinAmp on another platform).

The player can play audio files, can skip to next song, return to previous one, offers a playlist with possibility to add, remove and reorder songs. The functionality is provided for users, but accessible to other programs as well. So a program can call xmms.pause() or xmms.addToPlaylist(filename). As can be seen, the communication is initiated by the other program that uses the player’s API to instruct it to perform an action. After the execution of the command ends, the control returns back to the caller. Let’s name the caller a client and such an API a client API.

On the other hand, the XMMS' APIs also allows third parties to register output plugin_s. The functionality of the default player can be extended by providing a utility method that writes the played data to a disk, broadcasts it over a network, etc. The communication is in this case initiated by the player itself. After collecting enough data for playback, the program locates the current output plugin and sends it the data to process: plugin.playback (data). After finishing the playback the execution is returned back to the player that can continue in gathering more data and the whole process continues. Is the plugin a client? Well, it is in completely different position than the client in previous paragraph. It does not instruct _XMMS to do something, it increases the list of things XMMS can do. So no, the plugin is not a client. XMMS ability to register plugins is a Service Provider Interface, or SPI.

In this section we will discuss the actual implementation of the API in two sample languages - procedural C and object oriented Java.

The C language is ready and suitable for expressing (client) API. One just writes the methods and announces them in the header files, so others can compile agaist them:

The Java way is not much different:

but one has more choices. It is possible to declare these methods static, to leave them as instance methods, make them abstract, final, etc. But generally speaking, the way C and Java handle client APIs is nearly similar. However the situation is a far different when writing an SPI.

In order to write own plugin for XMMS in C one has to start with a method that will do the playback. So the a plugin must define:

and the player itself has to have some registration method, for example,

that the plugin should call to register itself. ` xmms_register_playback(my_playback)` and its playback function is then called by the XMMS whenever necessary. In Java the contract starts with a definition of playback interface:

then my plugin has to implement that interface MyPlayback implements XMMS.Playback and register that instance to the player:

and that is all. The player can do its calls to the plugin as it could in case of C. The major difference is that writing this kind of code is taught in Java courses without a proper explanation of what it really means.

In the C case, the amount of work to produce an SPI (for example callback) is high enough to prevent beginner from even trying it. One’s knowledge has to grow significantly to get to state when one can (or will need to) design an SPI. But in Java any declared method that is not private, final or static is defacto an invitation for someone to provide a callback and thus an accidental SPI. This is often not well understood by programmers, teachers, and is not part of conventional wisdom. Any Java book introduces public, non-static and non-final methods in one of the first chapters (at least as soon as it starts to talk about Applets) without a proper warning of all consequences. That may be fine for simple development, but when one starts to design APIs, all habits learned at the begining turn into mistakes.

Evolution is a natural part of any contract. After a time everything gets obsoleted, insufficient or broken. APIs and SPIs are not exceptions. So it is better be prepared for evolution at the begining, plan for it and avoid mistakes that would otherwise be hard to undo.

In case of an API that is offering methods to clients, there is no problem with additions. Extending the functionality to offer more functionality to clients cannot hurt them - if they do not want they do not need to use it.

In the cas of an SPI, the situation is exactly the oposite. Adding new method into an interface that others must provide effectively breaks all existing implementations, because they do not implement it! On the other hand it acceptable and valid to stop calling (de facto removal) a method from an SPI. If the operation flow is not part of the contract, not calling one method should not break anything.

So the way of evolution depends on the type of the interface: API additions are fine but removing functionality is not; SPI de-facto removals are allowed, but additions are not. At the begining of producing a contract, one should realize and understand which parts will be API that clients will call, and what will be SPI that will extend the functionality one is writing. The biggest mistake that one can make is to mix API and SPI together into one class. Then there is no room for evolution. Adding a method is forbidden because of the contract for SPIs and removing because of the contract for APIs. Always separate API and SPI.

As an example let us choose DataObject class, a part of the Data System API. It is used for by clients to obtain a logical, representation of a file or set of files, and logically manipulate their contents:

But the problem is that this client API is mixed together with a lot of methods provided just for subclasses (those that are protected in javadoc). They pointlessly clutter the API and moreover prevent the API from being extended in future. Moreover not only do the API and SPI conflict and make evolution difficult, but the execution flow between API and SPI resulted in a lot of flow clashes - deadlocks.

That is why during design of new data systems the DataObject has been reserved just for the API. It is supposed to be final and fully controlled by the implementation. The actual behaviour is provided by a separate SPI:

By separating the API from SPI and fully controlling the flow between them we can evolve the API and SPI independently and moreover add various pre-condition and post-condition checks between the actual client and provider. For example it is simple to add a new method DataObject.move(DataFolder df, String newName) to the API that should move the object and rename it at once and bridge it as move and rename calls into the DataObjectOperator by default and (in case of of new improved operators) to the new method moveAndRename(DataObject obj, DataFolder df, String name) if provided.

The new data systems should be an example of good design that is aware that what’s good for SPI implementors isn’t necessarily good for API clients, tries to give the API a chance to evolve and also restrict SPI implementors as little as possible.

Another example in case you are not yet convinced: AntArtifact was originally made an abstract class, rather than an interface, so that some final methods like getArtifactFile and getScriptFile could be added for clients, and getID could be defaulted. It seemed reasonable at the time. Of course, it turned out that later the SPI part had to be extended to support multiple artifacts and properties. Adding support for properties was easy enough to do compatibly, but adding support for multiple artifacts was messier: we had to deprecate the old single-artifact getters and introduce new getters, while preserving compatibility for old implementations. It would have been simpler to do had there been a final class AntArtifact with a factory method accepting an SPI interface AntArtifactImpl (or the like), since we could have produced a new SPI interface and a new factory method.

The most obvious one is that usage of the type, if implemented as an abstract class, is limited as java doesn’t allow multiple inheritance of classes. This only becomes a problem when a type is huge, or when it significantly enhances developer productivity to be able to subclass and reuse a base implementations. We will call these support classes, where one is expected to subclass and reuse a base class’s implementation.

The second advantage of interfaces is that there is an enforced separation between the API and the implementation. But this can be achieved with abstract classes too, with a bit of self control, while in interfaces that is enforced by the compiler.

The main reason why people prefer to use abstract classes is their ability to evolve in a time - it is possible to add a new method with a default implementation without breaking existing clients or implementors (here we talk about runtime compatibility, not compile time one). Interfaces lack such functionality, so it is necessary to introduce another interface to provide future extensions. So you end up with a lot of interfaces such as interface BuildTargetDependencyEx extends BuildTargetDependency with additional methods. The original interface is still valid, the new one is available.

A second very useful feature of abstract classes is the possibility of restricting access rights. Every method in a public interface is public and everybody can implement the interface. That for example means anybody can implement such interface, but in real life, one often wants to restrict that and have the creation under control. Interfaces lack such restrictions.

Another thing that is possible with abstract classes is that they can contain static methods. Of course that with interface one can create separate classes with factory methods, but the truth is that a class is usually the most natural and reasonable place for factory methods that return instances.

The TopManager is one of the oldest types in the NetBeans Open APIs and was designed to bridge between the org.openide.* packages and their implementation in org.netbeans.core. There is just one instance of the manager (provided by the core) and clients of the API are not at all expected to extend/implement that type.

Analysis shows that this is a typical situation of providing a lot of utility methods to clients with complete control over the implementation, where attention is be paid to ease of use for clients of such API, while permitting dynamic discovery of the implementation (the API is in different compilation unit [openide] than its implementation [core]).

This is a situation where one cannot gain any advantage by using interfaces over using abstract classes. One needs a factory method, one can add new methods, separation between API and implementation is in the right hands and there is also the possibility to prevent instantiation of other instances than the default one. If you happen to be in similar situation, it is best to use an abstract class.

An example what can happen if one chooses to use an interface is located next to TopManager in the same package - the Places interface. In reality it is the same singleton as the TopManager, it is accessed via the factory method TopManager.getDefault().getPlaces(). All its methods could be part of the TopManager as well. We just wanted to logically separate them and we did it using an interface. As a result, as newer "places" that might be useful API were created, we were afraid to add a method there after a time. Since we decided creating a Places2 interface would be overkill, the interface started to be less and less used and now is nearly obsolete.

The cookies are a coding pattern that allows any object to provide a specific feature (called cookie) by calling:

Should the OpenCookie be interface or abstract class? Simple analysis can show that there is a lot of clients, users of the API, and also a lot of providers, often wanting to provide more cookies at once. Moreover the cookie itself contains just one method open. All of the that leads to answer that the type should be an interface. We have the ability for multiple inheritance, and there is no fear of evolving the interface because it has just one method that does it all, no need for static factory methods, no need to prevent subclassing. Thus an interface is the right choice.

Very similar, but also very different example can be shown on another cookie - the InstanceCookie . It is also an interface and it used to have three methods but after few releases we realized a need for another to improve performance. So we were forced to introduced a subclass InstanceCookie.Of extending InstanceCookie and adding method instanceOf. This of course works, but adds a lot of pressure to users of the interface. Everyone using the API has to code as following:

The code is not too simple and moreover is spread over the whole codebase. How much simpler it would be if we could just add a new method into the cookie:

but because java does not allow default methods in interfaces, we are out of luck. Should we have used abstract class? No, we should not, the use cases are similar as with OpenCookie, but there is another trick that (very likely) should have been used.

Instead of adding three methods into the interface we could add just one that would return a class with all necessary information.

This solution seems to combine the best of both worlds. Clients have simple API, providers can implement instead of extend and in the instanceInfo method instantiate the info either with some provided constructor or factory methods or lazily using subclassing. Also when we need to add the instanceOf after few releases, we can. InstanceCookie.Info is a class and as such can be extended by a method with a default implementation.

Of course to make such methods additions safe, it is better to make the class final and provide factory methods that implementors of InstanceCookie could use. Those factory methods could either be simple, e.g. take values for instanceName, instanceClass and instanceCreate methods. Or the factory methods could take another interface with a methods that would be called to lazily handle the invocations of for example Info.instanceCreate. The actual solution depends on the needs of the users of the API.

Please notice that similar pattern is used by java listeners. Every listener is an interface and as such it has a constant (often one) number of methods. But each method takes a subclass of EventObject which is a class and if necessary can be enhanced with a java.awt.datatransfer.Transferable) new method.

Another example from NetBeans is the FileObject (part of the filesystem API). This type usage seems very close to the TopManager example (but is not as obvious): There are very few people directly subclassing FileObject (javadoc’s HttpFileSystem, Kyley and Niclas) and tons of client API users (every NetBeans module).

The amount of people directly subclassing FileSystem is the same as those doing that for FileObject, so it seems fine to choose abstract class for both types, but it is true that the filesystem would probably work as interface too.

Moreover there is a support class, the AbstractFileSystem that most of the people providing filesystem implementations are subclass. Because it is a support class, it needs to be a concrete class or at least a factory method, but it offers five interfaces (Info, Change, Attr, List, Transfer) that are not exposed in the client API for users of filesystems, but users of it may implement to write an filesystem implementation. People who write the own filesystem implement these interfaces most of the time and can use multiple interface inheritance. And because AbstractFilesystem implements the client API contract, anyone subclassing it can be sure they are implementing the full API, but only that API.

Can support classes be provided as interfaces? It is not easy. What kind of support would it be if one would have to provide implementation of each method! So, often abstract classes are used as base for support classes.

But one should carefully separate the support classes from the actual API (as the CloneableEditorSupport is in different package than the EditorCookie which it implements). Such separation ensures basic quality of design and prevents cheating - one needs to use just API methods even in the implementation and cannot rely on non-public hooks.