Utility Classes

Not all of the classes in this package are of interest for all module writers, but some of them may or even are as they are used through out our sources.

Package org.openide.util

  1. NbBundle as our specialized support for localization and replacement to ResourceBundle.
  2. Task and especially RequestProcessor which is our way to manage pools of thread workers and execute asynchronous computations.
  3. BaseUtilities which contain a lot of methods of possible interest. For example topologicalSort, activeReferenceQueue, translate.
  4. Enumerations provide enhacened support for manipulation with Enumerations and especially their on-demand generation.

Services Registration and Lookup API

For lookup, this centers around Lookup and helper implementations in org.openide.util.lookup.

Contents

Lookup

The whole NetBeans platform is moving toward installation of services via XML layer or (via the @ServiceProvider annotation on classes) META-INF/services. Layer-based installation is more flexible in many ways.

The need for having a standard interface to access such registrations gave rise to the lookup system first introduced in NetBeans 3.2 and expanded upon for NetBeans 3.3. The center of this API from the client perspective is very simple - you can look up a class, and get an instance of that class (or a collection of them). The service provider side of it is more complex but useful lookup implementations are already provided in the core system; for common cases you can register an object into lookup just by adding one simple file to an XML layer or META-INF/services/classname in your module JAR file.

This section of the Services API will first discuss what instances are and how to create them from files, as this is the core concept for service providers. It will discuss how you can manually retrieve sets of instances as a client, which is not used very frequently in new code but helps to understand what lookup is doing behind the scenes. Then lookup itself is discussed, and how the standard instance lookup works and how it relates to JDK's standard for service provider registration. Lookup templates, which separate the provision of instances from the provision of categories, will be explained.

Working with Instances

Central to the management of services and many other aspects of NetBeans' configuration is the notion of instances. An instance is just any Java object, generally of a particular type appropriate to its use, which is provided from some object (generally, a data object) using InstanceCookie. As an example, menu items may be added by inserting data objects that provide this cookie into the proper folder, and having the instance be a system action (or other things). Or an XML DTD may be registered by placing an object with an instance of org.xml.sax.EntityResolver in the proper folder.

Where do these instances come from? Technically, it is up to you to decide how to provide InstanceCookie; you could if really necessary create your own data loader that provides it according to some unusual scheme, and add files recognized by that loader to the right folder. Practically, the APIs provide implementations of this cookie sufficient for normal purposes.

The most common way to provide an instance is using InstanceDataObject. This is a type of data object whose sole purpose is to provide the instance cookie. It typically does so based on a class name you supply. There are several styles of instance file; all are empty (i.e. the file contents are of zero length, and just the file name and attributes matter). There are then other ways of providing instances which rely on the file contents. Here are the methods of providing instances defined in the APIs:

Default instance - InstanceDataObject

If there is a file with the extension *.instance, then its name (minus extension) will be converted to a class name by replacing dashes with dots; and a fresh instance of that class will be created and used as the instance. For example, com-mycom-mymodule-MyAction.instance produces an instance of the class com.mycom.mymodule.MyAction.

Since reflection is used to create the new instance, just as in the realm of JavaBeans, the class must be loadable from your module or otherwise from within NetBeans (technically, via the classloader found by querying Lookup for ClassLoader); public; and have a public no-argument constructor. (Or be a SharedClassObject.) This form is often used for singleton classes such as system actions: there is no need to specify any parameters to the constructor, any instance will suffice.

Default instance with separate class - InstanceDataObject

Rather than shoving the class name into the file name, you can name the file more normally and specify the class with a file attribute. Then the class name is specified as a string-valued attribute on the instance named instanceClass. For example, a keyboard shortcut could be registered as follows in an XML layer:

<file name="C-F6.instance">
    <attr name="instanceClass" stringvalue="com.mycom.mymodule.MyAction"/>
</file>

In addition to instanceClass you may specify an additional attribute instanceOf giving the name of a superclass (or implemented interface) of the instance class. In fact it may be a comma-separated list of superclasses and interfaces. While its purpose is explained more fully below, essentially it lets you give the system a hint as to what this instance is for before your instance class is even loaded into the VM. For example:

<file name="com-me-some-service.instance">
    <attr name="instanceClass" stringvalue="com.me.FactoryForEverything"/>
    <attr name="instanceOf"
     stringvalue="org.xml.sax.EntityResolver,org.openide.cookies.ExecCookie"/>
</file>
Non-default instance - InstanceDataObject

A powerful way of providing instances is to use the expressiveness of the XML layer syntax to handle the instance creation. In this case the file attribute instanceCreate can be defined and the attribute value becomes the instance. Typically the attribute value would be specified using the methodvalue syntax of layers. For example:

<file name="com-me-some-service.instance">
    <attr name="instanceClass" stringvalue="com.me.FactoryForEverything"/>
    <attr name="instanceCreate" methodvalue="com.me.FactoryForEverything.configure"/>
    <attr name="myParam" urlvalue="nbres:/com/me/config-1.properties"/>
    <attr name="instanceOf"
     stringvalue="org.xml.sax.EntityResolver,org.openide.cookies.ExecCookie"/>
</file>

According to the general system for XMLFileSystem, you now need a method configure in FactoryForEverything which must be static; the method need not be public (if you do not want other Java code to see it). It may take a file object as argument if you wish - this will be the instance file; typically you use this to pass extra configuration from the layer, useful if you want to create multiple instances with the same creation method. The argument may also be a map. So for example you might implement such a method like this:

public class FactoryForEverything extends SomeBaseFactory
        implements EntityResolver, ExecCookie {
    public FactoryForEverything(Map props) {
        // ...
    }
    // ...
    // Called directly from XML layer. Pass URL to
    // properties file from attr 'myParam'.
    private static Object configure(Map<String,?> inst) throws IOException {
        URL u = (URL)inst.get("myParam");
        Properties p = new Properties();
        p.load(u.openStream());
        return new FactoryForEverything(p);
    }
}
Serialized beans

A simple way to provide an instance is to serialize it as a JavaBean, into a file with the extension *.ser. This is not very useful from a layer, because you should avoid putting binary data into a layer, but may be useful in some circumstances.

XML-based instances

EntityCatalog

Again, modules may also have additional ways of providing instances from files. For example, currently the utilities module enables any URL file (*.url) to be used directly in a menu, as the URL file provides an instance of Presenter.Menu.

As an interactive demonstration of these things, first go into Filesystem Settings and make the system filesystem (first in the list) visible; then explore its contents in Filesystems, going into some subdirectory of Menu. Note the various actions and menu separators; these are all by default instance data objects. You may find some of these on disk in your installation directory under system/ if you have customized them, but by default they live in memory only. You may copy-and-paste these instances from one place to another; create new ones on disk and watch them be recognized and inserted into the menus after a few seconds; and you may also choose Customize Bean (which really customizes the provided instance) on (say) a toolbar separator (under Toolbars) to change the separator size, and serialize the result to a new *.ser file which should then create a toolbar separator.

Folders of Instances

InstanceCookie.Of and lazy class loading

Now it is time to mention the purpose of InstanceCookie.Of. Suppose that there are two generic interfaces under consideration: e.g. javax.swing.Action and org.xml.sax.EntityResolver. For each interface, there is code to find registered instances, all under the Services/ folder. Furthermore, using either of these interfaces is relatively rare, and might not happen at all during a NetBeans session; and the implementations of the instances are complicated and involve a lot of code, so it is undesirable (for performance reasons) to load these implementations unless and until they are really needed. If you write the layers simply like this:
<filesystem>
    <folder name="Services">
        <folder name="Hidden">
            <file name="com-me-MyAction.instance"/>
            <file name="com-me-MyResolver.instance"/>
        </folder>
    </folder>
</filesystem>
everything will work, but this is inefficient. Consider some piece of code asking for all actions. The search through the services folder for actions would ask each of these files if it provides an instance cookie assignable to javax.swing.Action. For com-me-MyAction.instance, this will load the class com.me.MyAction, determine that it implements Action, and thus create a MyAction instance and return it; so far so good. But when com-me-MyResolver.instance is encountered, it will again load com.me.MyResolver, only to find that this does not implement Action and skip the instance. The behavior is correct, but now the MyResolver class has been loaded into the VM even though no one will ever use it (unless a resolver search is made). This will degrade startup time and memory usage (and thus performance).

So the better solution is to mark each file in advance, saying what interfaces it is intended to provide in its instance:

<filesystem>
    <folder name="Services">
        <folder name="Hidden">
            <file name="com-me-MyAction.instance">
                <attr name="instanceOf" stringvalue="javax.swing.Action"/>
            </file>
            <file name="com-me-MyResolver.instance">
                <attr name="instanceOf" stringvalue="org.xml.sax.EntityResolver"/>
            </file>
        </folder>
    </folder>
</filesystem>

Now the folder instance processor for Action will pass over com-me-MyResolver.instance without needing to load com.me.MyResolver, since it sees that its interfaces are declared, and Action is not among them. Of course, the interface classes - Action and EntityResolver - need to be loaded right away, but they were probably already loaded anyway, so this is acceptable.

Caution: if you do supply an instanceOf attribute, but it does not list all of the implemented interfaces and superclasses of the actual implementation class (including that implementation class itself, which is not implied), a lookup query on one of the missing superclasses may or may not succeed. So you should include in instanceOf any superclasses and interfaces that you think someone might use in a lookup query, possibly including the actual implementation class.

Lookup and Service Installation

The client side of the lookup system centers around one class, Lookup. In the simplest usage, all that is needed is to get some single instance of a given class (or subclass). For example, if some kind of service has been defined as an interface or abstract class, and you wish to find the implementation of it, you may simply use:
MyService impl = (MyService)Lookup.getDefault().lookup(MyService.class);
if (impl == null) /* nothing registered */ ...
impl.useIt();
Such implementation has to be registered by some module to the system. Either via layer as described above or as a JDK's service provider. If some module wants to register for example org.me.MyService it shall provide file name META-INF/services/org.me.MyService in its own JAR with single line containing name of the implementation class (for example org.you.MyServiceImpl). This is normally done more easily by using the @ServiceProvider annotation in MyService.java. The lookup infrastructure will then load the implementation class and call its default constructor to answer the query in the above example.

The Lookup supports two small extensions to the JDK's standard. It allows a module to remove class registered by another one. That is why it is possible to write a module that disables the org.you.MyServiceImpl implementation and provides its own. This the expected content of its META-INF/services/org.me.MyService file:
  # remove the other implementation (by prefixing the line with #-)
  #-org.you.MyServiceImpl

  # provide my own
  org.alien.MyServiceAlienImpl
    
The reason why the removal line starts with #- is to keep compatibility with JDK's implementation. The # means comment and thus JDK will not interpret the line and will not get confused by the - before class name.

Second extension allows ordering of items. The class implementing the interface can be followed by advisory position attribute. If multiple implementations are defined in one file then each can be followed by its own positioning attribute. When querying on an interface, items with a smaller position are guaranteed to be returned before items with a larger position. Items with no defined position are returned last. Example of content of META-INF/services/org.me.MyService file could be:

  org.you.MyServiceImpl
  #position=20
  org.you.MyMoreImportantServiceImpl
  #position=10
    
The MyMoreImportantServiceImpl will be returned in lookup before the MyServiceImpl. It is recommended to pick up larger numbers so that there is gap for other modules if they need to get in front of your item. And, again, to keep compatibility the position attribute must starts with comment delimiter.

Both extensions are supported by @ServiceProvider.

If more than one implementation has been registered, the "first" will be returned. For example, if the implementations were present in the Services folder as *.instance files, then folder order would control this.

As mentioned above, the NetBeans default lookup searches in the Services folder and its subfolders for instances whose class matches the requested class. Technically, it looks for data objects with InstanceCookie.Of claiming to match the requested superclass, or plain InstanceCookie whose instanceClass is assignable to it.

Note that you may use this method to find singleton instances of subclasses of SharedClassObject that have been registered in lookup (as is normally the case for system options). However for this purpose it is simpler to use the static finder method SharedClassObject.findObject(Class, true) which is guaranteed to find the singleton whether it was registered in lookup or not (if necessary it will first initialize the object according to saved state).

In many situations it is normal for there to be more than one registered implementation of a service. In such a case you use a more general method:

Lookup.Template templ = new Lookup.Template(MyService.class);
final Lookup.Result result = Lookup.getDefault().lookup(templ);
Collection impls = result.allInstances(); // Collection<MyService>
// use Java Collections API to get iterator, ...
// Pay attention to subsequent changes in the result.
result.addLookupListener(new LookupListener() {
    public void resultChanged(LookupEvent ev) {
        // Now it is different.
        Collection impls2 = result.allInstances();
        // use the new list of instances...
    }
});
Here you receive a collection of all instances matching your query, again in the order found if this matters. You can also listen to changes in the list (additions, deletions, and reorderings). It is fine to keep a Lookup.Result for a long period of time as it may implement its own caching scheme and only really compute the instances when allInstances is called; in fact it may be more efficient to keep a result, and listen for changes in it, than to repeatedly call lookup and create fresh result objects.

When a lookup query is finished - for example when Lookup.Result.allInstances() returns some Collection of instances - it is guaranteed that all objects registered in the same thread prior to the call to lookup() or prior to some change notification on the Lookup.Result, will be returned. Specifically, lookup instances registered via module layer will be available by the time ModuleInstall.restored() (or .installed()) is called. There are two situations in which lookup results may be incomplete: when you are currently inside the dynamic scope of some method providing a lookup instance itself; and when you are dynamically inside a DataLoader method involved in recognizing data objects.

Persisting Lookup Information

In some circumstances it is necessary to not only find registered objects, but to select some of them and make this selection persistent. For example, some setting may have as its value a choice among available services matching some interface; the value needs to be persisted, but it is the identity of the choice, rather than the full state of the instance itself, which must be stored.

In such cases it is possible to use code like this:

Lookup.Template templ = new Lookup.Template(MyService.class);
Lookup.Result result = Lookup.getDefault().lookup(templ);
Iterator it = result.allItems().iterator();
while (it.hasNext()) {
    Lookup.Item item = (Lookup.Item)it.next();
    String displayName = item.getDisplayName();
    if (/* user accepts displayName as the right one */) {
        MyService instance = (MyService)item.getInstance();
        // use instance for now, and ...
        String id = item.getId();
        someSettings.setChosenService(id);
        break;
    }
}
// later...
String storedID = someSettings.getChosenService();
Lookup.Template templ = new Lookup.Template(MyService.class, storedID, null);
Iterator it = Lookup.getDefault().lookup(templ).allInstances().iterator();
if (! it.hasNext()) /* failed to find it... */
MyService instance = (MyService)it.next();
// use instance again
The ID permits you to track which instance from all those available in the lookup result was last selected by the user, and find the "same" instance later, perhaps after a restart of NetBeans. The exact form of the ID is the private knowledge of the implementor of the lookup, but typically if the instance has been provided via layer the ID will mention the name of the file from which it was derived.

Creating Lookups

There are a number of reasons to create your own lookup implementation. For one thing, the lookup system which scans the Services/ folder will recognize instances of subclasses of Lookup specially by proxying to them. This can be very powerful because you may register just one layer file which points to your custom lookup, which in turn may provide an unlimited number of actual instances/items for queries (and compute them in a manner other than registration by files). Another reason is to associate a context with a data object using Environment.Provider; for example the data object might be an XML file and this provider might be registered with the file by means of the public ID of the doctype (informally, the DTD). Here the provider has an associated lookup which can serve requests for cookies and such things. See more information about associating lookups with XML files.

The simplest way to create a fresh lookup is to base it on other existing ones. ProxyLookup accepts a list of other lookup implementations (in the constructor and also changeable later). The results it provides are constructed by merging together the results of the delegate lookups.

If you want to use the common mechanism of finding instances in folders (or subfolders) and serving these as the results, Lookups.forPath(String) makes this possible: you need only provide a name of a folder to look in, and use Lookups.forPath(theFolderName) to retrieve a lookup implementation which will scan this folder and its subfolders for data objects with InstanceCookie matching the lookup template. Furthermore, any instance cookies whose instance class is assignable to Lookup will be treated specially: they will be proxied to, so these sub-lookups may provide additional instances if they match the lookup template. In order to get the full functionality associated with such a lookup it is wise to request presence of org.netbeans.modules.settings > 1.13 as that is the module that does most of the work behind Lookups.forPath. To register javax.xml.parsers.DocumentBuilderFactory into Lookups.forName("my/xml/app/data") add the above described dependency and put following code in your layer file:

<folder name="my">
  <folder name="xml">
    <folder name="app">
      <folder name="data">
        <file name="ThisIsMyRegistration.instance>
          <attr name="instanceCreate" newvalue="pkg.ClassNameOfYourImpl"/>
        </file>
      </folder>
    </folder>
  </folder>
</folder>

In fact the Lookups.forPath can be used in completely standalone mode. This is not very recommended in the NetBeans IDE, but can be found pretty useful when using this library in standalone applications: Lookups.forPath(path) scans all instances registered in the META-INF/services style just it uses META-INF/namedservices/path prefix instead. (@ServiceProvider supports this mode.) As a result to perform a successfull search for all javax.xml.parsers.DocumentBuilderFactory inside Lookups.forName("my/xml/app/data") one can register the implementation into META-INF/namedservices/my/xml/app/data/javax.xml.parsers.DocumentBuilderFactory.

The most powerful way to provide a lookup is to directly define what instances and items it should provide, by subclassing. For this, AbstractLookup is recommended as it is easiest to use.

The simplest way to use AbstractLookup is to use its public constructor (in which case you need not subclass it). Here you provide an AbstractLookup.Content object which you have created and hold on to privately, and which keeps track of instances and permits them to be registered and deregistered. Often InstanceContent is used as the content implementation. To add something to the lookup, simply use add(Object) (and remove(Object) for the reverse). These may be called at any time and will update the set of registered instances (firing result changes as needed).

In case it is expensive to actually compute the object in the lookup, but there is some cheap "key" which can easily generate it, you may instead register the key by passing in an InstanceContent.Convertor. This convertor translates the key to the real instance that the lookup client sees, if and when needed. For example, if you have a long list of class names and wish to register default instances of each class, you might actually register the class name as the key, and supply a convertor which really loads the class and instantiates it. This makes it easy to set up the lookup, but nothing is really loaded until someone asks for it.

Settings

Settings require special support in the lookup system: these are objects (perhaps singletons but not necessarily) which should be made available to lookup, yet whose content can be changed and stored to disk (typically as a result of user interaction with the GUI). *.instance files and similar constructions are fine for registering fixed objects from layer - "fixed" in the sense that while the user might copy, delete, move, or reorder them, the actual object they provide is statically determined and does not generally have a means of being modified. In contrast, settings have nontrivial content. A typical setting is a system options, simply a singleton bean with a set of properties and a structured GUI presentation driven by BeanInfo.

In order to save such settings, an XML file is normally used, and the APIs provide a convenient DTD for settings which can be represented as a single bean. In typical usage, the module layer declares an initial settings file which instructs lookup to create a default instance of the settings class. This might look like the following:

<?xml version="1.0"?>
<!DOCTYPE settings PUBLIC "-//NetBeans//DTD Session settings 1.0//EN" "http://www.netbeans.org/dtds/sessionsettings-1_0.dtd">
<settings version="1.0">
    <module name="com.foo/1" spec="1.0"/>
    <instanceof class="org.openide.options.SystemOption"/>
    <instanceof class="com.foo.MyOption"/>
    <instance class="com.foo.MyOption"/>
</settings>
Such a file might be placed in Services/com-foo-my-settings.xml (the exact name inside the Services folder is not important but ought to be globally unique to avoid conflicts with other modules). It provides an InstanceCookie with the settings object as instance.

The interesting parts of this file are:

There are actually three ways that the instance may be declared:

  1. Using <instance/> as above to generate a default instance. This is most common.

  2. You may pass an additional attribute method indicating a static method to call to produce the instance, rather than using a default constructor. The method may either be a simple name, in which case it is assumed to be a method in the class given by class, or you may give a full class name followed by a dot and method name to invoke a static method from some other class. The method may optionally take a FileObject argument which will be the settings file itself. This is analogous to the mechanism used for creating complex *.instance files. For example:

    <file name="some-difficult-to-make-instance.settings">
        <![CDATA[<?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE settings PUBLIC
              "-//NetBeans//DTD Session settings 1.0//EN"
              "http://www.netbeans.org/dtds/sessionsettings-1_0.dtd">
    <settings version="1.0">
        <module name="my.module/1" spec="1.0"/>
        <instanceof class="javax.swing.Action"/>
        <instanceof class="my.module.MyAction"/>
        <instance class="my.module.MyAction" method="createAction"/>
    </settings>
    ]]>
        <attr name="param" stringvalue="someval"/>
    </file>
    
    package my.module;
    public class MyAction extends javax.swing.AbstractAction {
        public MyAction(String name) {/* ... */}
        // ...
        public static MyAction createAction(FileObject fo) {
            return new MyAction((String)fo.getAttribute("param"));
        }
    }
    

    This will result in an instance of MyAction being created with name someval.

  3. You may use the <serialdata> element. Its textual contents are a hexadecimal dump (whitespace ignored) of the raw serialized bytes of an object to serve as the instance. Naturally this is the least preferred mechanism as it is not human-readable.

(You can configure your persistance style by using @ConvertAsProperties or @ConvertAsJavaBean instead).

A client can find the current setting in a couple of ways:

How does the customization of setting instances work? After finding a setting instance via this DTD, the system will automatically look for a beans-style event set of type PropertyChangeListener, and add its own listener. If the bean changes state (either programmatically or as a result of user manipulation), the property change will cause the new state to be written out to the original XML file, keeping the same name. (Normally this would mean the XML would be written to disk in the user directory.)

(Historically the state of an object is simply serialized into the XML file using <serialdata>, meaning the class must be Serializable, but you can choose different form of persistance by using @ConvertAsProperties or @ConvertAsJavaBean instead).

Conversely, changes to the setting file on disk should trigger a reload of the state and modification of the in-memory bean (or creation of a new instance cookie with a new bean).

UI for Services

There are several things you can do to not only have services and lookup function programmatically but also look good and behave nicely within the user's view of configuration options and settings.

Service Templates

For many kinds of services, especially ServiceTypes but also others, it is necessary to permit the user to create new instances of the service. Generally two criteria should be met for such services:

  1. The service is not a singleton, so it is meaningful to have more than one instance.
  2. The service has some user-configurable properties, so it is useful to have more than one instance.

Creation of new service instances may be supported simply by producing a template residing beneath Templates/Services/. If the service normally resides in a subfolder of services, for example Services/Executor/, then the template should correspondingly be placed in Templates/Services/Executor/.

The template should work like regular source code templates do: a file giving the initial structure of the service (typically a *.settings file), with the file attribute template set to true, and optionally a templateWizardDescription and templateWizardURL. For example:

<folder name="Templates">
    <folder name="Services">
        <folder name="Executor">
            <file name="my-module-executor.settings" url="executor.settings">
                <attr name="template" boolvalue="true"/>
                <!-- SystemFileSystem.localizedName and SystemFileSystem.icon as usual -->
            </file>
        </folder>
    </folder>
</folder>

If the user selects New From Template on the corresponding options folder, the template will be available.

Services display area and mirroring

In addition to providing services, it is desirable to display them to the user as well. This is done, as is customary in other aspects of NetBeans configuration, by displaying customized variants of the data nodes coming from the system filesystem. The root folder for displaying options is called UI/Services/. Its subfolders govern the display of the options available in the system.

As a rule, it is undesirable to place any actual settings in this folder (nor would they be recognized by the default lookup anyway). That is because the organization of this folder is driven by UI needs, without regards to API maintenance or compatibility of persisted user settings. So this folder solely mirrors configuration available elsewhere. You may freely reorganize the mirror according to current UI needs: existing modules plugging into services areas will continue to work unmodified, and existing user customizations stored to disk will continue to apply, since both of these act on the original files (which should not be moved frivolously).

While technically you could place anything you wish in the UI folder, in practice a few types of things are used:

No particular substructure of UI/Services/ is defined by the APIs. For optimal UI integration you may wish to examine the categories used by other modules and try to reuse an existing category appropriate to your needs.

In some cases it is necessary to hide a service file, or a whole folder of services. While you can place files into Services/ and simply not make any corresponding mirror in UI/Services/, you may wish to create services or subfolders inside existing displayable folders (for purposes of lookup, generally) yet not have them be visible in the UI. In this case you should mark the file or subfolder with the file attribute hidden (set to boolean true).

Property editor for services

If you wish to permit the user to select a service as part of the Property Sheet (from a node property, or as a PropertyPanel, providing general GUI embeddability), this is supported. You should use the property editor assigned to java.lang.Object (not your desired service interface). Various hints defined in the Explorer API permit you to control the result.

As an example, here is a node property permitting you to ask the user to select a value of type my.module.Thing, being some interface or abstract superclass, where some instances are registered to lookup, conventionally in the Services/Things/ folder which the module has provided:

public abstract class ThingProperty extends PropertySupport.ReadWrite {
    protected ThingProperty(String name, String displayName, String shortDescription) throws IOException {
        super(name, Object.class, displayName, shortDescription);
        setValue("superClass", Thing.class); // NOI18N
        setValue("nullValue", NbBundle.getMessage(ThingProperty.class, "LBL_no_thing")); // NOI18N
        DataFolder thingsFolder = DataFolder.create(
            DataFolder.findFolder(Repository.getDefault().getDefaultFileSystem().getRoot()),
            "Services/Things" // NOI18N
        );
        setValue("node", thingsFolder.getNodeDelegate()); // NOI18N
    }
    public final Object getValue() {
        return getThing();
    }
    public final void setValue(Object o) {
        if (o != null) {
            Lookup.Template templ = new Lookup.Template(Thing.class, o, null);
            Iterator it = Lookup.getDefault().lookup(templ).allItems().iterator();
            if (it.hasNext()) {
                setThingID(((Lookup.Item)it.next()).getId());
            } else {
                // Thing was registered but is not persistable.
                setThingID(null);
            }
        } else {
            setThingID(null);
        }
    }
    public final boolean supportsDefaultValue() {
        return true;
    }
    public final void restoreDefaultValue() {
        setValue(null);
    }
    // May be used by code wishing to get the actual Thing (or null):
    public final Thing getThing() {
        String id = getThingID();
        if (id != null) {
            Lookup.Template templ = new Lookup.Template(Thing.class, null, id);
            Iterator it = Lookup.getDefault().lookup(templ).allInstances().iterator();
            if (it.hasNext()) {
                return (Thing)it.next();
            } else {
                // Invalid ID.
                return null;
            }
        } else {
            return null;
        }
    }
    // Subclasses implement to actually read/write Thing persistent IDs (or null):
    protected abstract String getThingID();
    protected abstract void setThingID(String id);
}

A property extending this class would in the current UI display a pull-down list of all Thing implementations available in lookup; the custom property editor dialog would display the Things folder with anything contained inside it for the user to select from, provided it in fact had an instance assignable to Thing. The special null value is explicitly permitted here and would be displayed with the label given in the bundle.