What are *.instance files?

Apache NetBeans Wiki Index

Note: These pages are being reviewed.

*.instance files represent an "instance", i.e. arbitrary Java object.

An instance file typically says what class it is an instance of via its class name - for example, com-foo-mymodule-MyObject.instance. A *.instance file may create its instance from any Java class with a default constructor, or by calling a static method on a class.

In NetBeans infrastructure, *.instance files result in `InstanceDataObject`s. `InstanceDataObject`s can supply `InstanceCookie`s, which in turn instantiate the object. So, code to actually get an instance of an object declared in the system filesystem (DevFaqSystemFilesystem) would look like this (plus error checking):

public static Object getTheObject(String pathInSystemFilesystem) throws Exception {
    return DataObject.find(FileUtil.getConfigFile(pathInSystemFilesystem)).
        getLookup().lookup(InstanceCookie.class).instanceCreate();
}

(FileUtil.getConfigObject is available for this purpose in NB 7.1+.)

A much easier way to get all instances of objects in a folder exists:

for (WhatISaidToPutHere instance :
        Lookups.forPath("MyFolder").lookupAll(WhatISaidToPutHere.class)) {
    // ...
}

Note that a default constructor is not required in an XML layer; you can also use a static method, using the following syntax:

<file name="ObjectTypes.instance">
  <attr name="instanceCreate" methodvalue="org.netbeans.core.ui.UINodes.createObjectTypes"/>
  <attr name="instanceOf" stringvalue="org.openide.nodes.Node"/>
</file>

(The instanceOf attribute is optional; it lets the system avoid instantiating your object just to see if it is assignable to Node. This is only useful in folders that contain objects of many different types mixed together, which is normally true only in the semi-deprecated Services folder: code looking for instances of one type only would rather not load everything.)

See also: DevFaqDotSettingsFiles

Applies to: NetBeans 6.7 and later