Registry API - NetBeans API Javadoc (Current Development Version)

(This part needs to be updated!)

Design Choices

Designing API consists of considering wide rage of possibilities and chosing the particular one for some reason. The important thing to keep in mind is that API as a whole must be consistent and its individual parts must fit into other smoothly and naturally. This often means that solution for one concrete API part which seems as the best cannot be used because it does work well with other parts of the API.

This section tries to summarize some of the dilemmas and choices considered during the design of this API and why some things were done this way and not the other.

Why the Preferences API was not used?

The Preferences API intentionally does not support objects handling. The Preferences API as it names says is suitable for storage of application preferences. However, handling of objects is requirement for NetBeans. The NetBeans platform is customized by the objects registered in the module's layer. The reasonable requirement is to have just one API for manipulation of these objects and also for maniulation with application preferences. At the end they are both just some settings.

However, the Preferences API provider can be written which would use as backend Registry API. This would allow users accustomed to Preferences API use that API even in NetBeans and take advantage of subset of the features of the Registry API.

Why the JNDI API was not used?

The JNDI API was considered for a long time. There even exists experimental implementation of the JNDI over NetBeans configuration system - core/naming module. However this idea was discarded mainly for these reasons:

too heavyweight for our needs. We need just subset of the functionality and even this subset is sort of cumbersome for use in client applications.
JNDI Specification. The clear specification of behaviour of JNDI is of course advantage, but in case of our particular usage of JNDI it could be also limiting disadvantage.
the JNDI originally was designed for enterprice or remote stuff. Therefore exceptions as return values are quite appropriate solution. This is not true for client applications which might query settings frequently and catching exceptions would surely be performance problem.
plain JNDI API is not enough for our needs. We would have to create a few helper APIs anyway, e.g. support for defaults, handling of primitive types, ordering, etc. Not mentioning that direct work with JNDI API requires catching exceptions all the time and so it would be most probably wrapped into some helper class as well.

The result is that we created Registry API which borrows a lot of ideas both from the JNDI API and Preferences API and which suits better our concrete needs in NetBeans.

Binding-based API or binding-less API?

Why there is not just

    public interface Context {

        String getName();

        Context[] getChildrens();

        Object getObject();

        String getAttribute(attrname);

        // ... other methods

    }

one single Context interface which represent both context and binding as well. This is how FileSystem library treats files and folders - the FileObject represents them both. Why the Registry API distinguish contexts and bindings?

This possibility was considered. There is no significant difference between these two concepts. The binding-less concept is more natural to people who are used to NetBeans FileSystem API; the binding-based concept is used in Preferences API, JNDI API and also Windows Registry works the same way. So in this light it was decided that easy of use of API and its intuitiveness is more important. Comparison of these two approaches demonstrated on a few usecases can be found here.

The behaviour of some methods depend on whether the binding name is passed or not.

Yes, all ResettableContext methods accept null as value of the binding name. Passing null value means that methods will operate on the Context itself and not on the concrete binding: binding's attribute versus context's attributes; reset of binding versus reset of whole context.

This design is not nice but it is reasonable compromise. Other solution would be to add several methods without this parameter, but this seems to be worse that current solution.

TBD: mention advantage of API/SPI separation

Links

Archive of discussions about this API.