The main differences between them are as follows:

FileSystems are used in two basic but very distinct ways in NetBeans. The first is representing the user’s files on disk. To get a FileObject for some path in NetBeans, just call, e.g.

The second usage is to represent configuration data - this is the "System Filesystem", which is where modules can install their files. Folders in the System Filesystem act as "extension points" - there are some which have predefined meanings (for example, NetBeans' main menu is a tree of folders you will place special "files" into to add menu items); modules are free to create their own folders and do as they wish with the contents.

How does all this work? Well, once you have the concept of a virtualized FileSystem full of FileObjects, it’s relatively easy to imagine a FileSystem which took several other FileSystems as arguments, and presented a merged view of the sub-filesystems as if all the data lived in one tree.

Add into this the notion that the "files" in a FileSystem don’t actually have to be physical files on disk at all - anything that can be made to walk and talk like a file will do. So you could have an XML "filesystem" where the contents of files lived in an XML document, not a bunch of files on disk.

That is what the NetBeans Platform does: Each module can define an XML "layer" file, which contains some virtual "files" and folders that are merged into the System Filesystem. In this way modules add their configuration data to the system. And because the System Filesystem is composed from discrete XML fragments from modules, when a module is disabled or unloaded, its XML layer is simply removed. FileObjects for the various folders that had files removed from them fire changes indicating some files were deleted, so the UI can get rid of any objects that represented the now-unloaded module’s files. This is why you can uninstall and reload modules at runtime.

In its jar manifest, a module will contain a line such as:

This is a pointer to an XML file inside the module jar (meaning that you simply create this file somewhere in your sources so it will be compiled into the jar when your module is built). In its simplest form, that could contain something like:

The url attribute is important: It says where the contents of myFile.txt lives in the module’s jar file. This path is relative to the location of the layer file. So, if the layer file is org/netbeans/modules/mymodule/layer.xml, then in the module jar there should also be a text file org/netbeans/modules/mymodule/resources/aTextFile.txt. When some code requests an InputStream for myFolder/myFile.txt, that text file in the module jar is what will actually be read.

Of course, this particular fragment doesn’t do much of anything, but it is useful to illustrate what can be done here. Since myFolder has no predefined purpose to NetBeans, it is up to the module defining that folder to do something with its contents. But one could imagine a module that provided myFolder, let other modules add more files to that folder, and provided one menu item for each file, letting the user view them.

Accessing this file programmatically is quite simple:

DataObjects don’t do a lot in and of themselves - that is, it is almost always a mistake to be casting a DataObject as a particular subclass. The way to do most interesting interaction with DataObjects is via the method getLookup(). The pattern, which we will see in more detail in the section on Lookup is:

The above code will actually open a file in the editor. The key here is that, rather than providing programmatic access to a file’s content as a bunch of instance methods on itself (which would quickly lead to a tangled mess of inheritance issues), you ask a DataObject for an instance of some known interface that does what you need. This is accomplished by passing a Class object to lookup(), which will return that object if possible, or null if not.

As another example, determining if an opened file has unsaved changes is as simple as:

Modules can provide their own public interfaces, and make instances of those objects available via lookup. So, for example, a DataObject for an XML file might make a DOM tree or some other structural representation of the file available via lookup for other modules to use to manipulate the file’s contents. Some common interfaces modules will typically use via lookup can be found in the package org.openide.cookies.

Note that the term "cookie" in this context has nothing to do with the web browser concept of cookies.

To illustrate the power of loaders and DataObjects, recall that loaders are registered against a file type. And recall that modules can install actual Java objects via .instance files. What’s going on here?

What is actually happening is that the very same infrastructure (DataLoaders) that lets NetBeans recognize a user’s .java file on disk and create an appropriate DataObject is what recognizes .instance files - after all, the System Filesystem is a filesystem too. There is simply a DataLoader registered in the system that claims all files with the .instance extension.

Under the hood, what’s really happening is that the DataObject for a .instance file provides an InstanceCookie. So to get the actual object in question manually, you would do something like this:

or more simply:

Nodes use the same pattern as DataObject - they have a getLookup() method that can be used as described above. Nodes that represent DataObjects will typically delegate to their DataObject’s getLookup() method.

Note that all Nodes do not represent DataObjects - the Nodes API is useful in and of itself for creating tree like hierarchies.

There are a number of UI components that can represent a tree of nodes as trees, combo boxes, lists, etc. - so typically when one needs to display a UI with a list or tree in it, the natural choice is to use the Nodes API, and simply create the appropriate component and set the root node appropriately.

A key thing to remember is that Nodes are intended as a presentation layer for an underlying data model (which might be files on disk, or whatever you want). If you find you’re putting a lot of logic into your Node subclass, consider that your model is what needs enhancing - Nodes should be lightweight and simple, and the model should do the heavy lifting.

The default lookup is an instance of Lookup returned by calling Lookup.getDefault(). The NetBeans APIs define a number of abstract service classes which allow you to get an instance of some object that is of general use - for example, org.openide.DialogDisplayer, which displays dialogs to the user. These are typically things that there only needs to be one of in the system, so they are effectively singleton objects. To get an instance of DialogDisplayer, you could do as follows:

In practice this code is a little clunky to ask people to write all the time, so most such abstract classes will have their own method getDefault() implemented as:

Modules can register their own objects into the default lookup using the @ServiceProvider annotation.

While we won’t go into this in detail here, it is also possible to register multiple instances of an interface into the default lookup, retrieve all of them and even listen for changes on the result of that query.

A very thorough discussion of Lookup can be found here.

The salient points to remember are:

Nodes provide a hierarchy of objects; the Explorer API provides Swing UI components that display a Node and its children. There are a large variety of Explorer view classes which can variously represent a hierarchy of Nodes as a JList, a JMenu, a JComboBox, a JTree, a JTable and more. Typically when you want to display some hierarchical data structure in NetBeans, you locate or implement the appropriate Node, create an appropriate Explorer component for it, and set the Explorer view’s root node to be the node you want to display.

In older versions of NetBeans, the place where the Files and Projects tabs live was a separate window with the title "Explorer" - you will see the phrase "open in the Explorer" in older documentation.

The API of the Window System is found in org.openide.windows. A basic overview is that in NetBeans, you don’t deal with JFrames or JDialogs - rather, you supply components which are displayed, and NetBeans window management system decides where and how they appear in terms of top-level frames. The main thing to know is that all components in NetBeans are subclasses or usages of org.openide.windows.TopComponent. TopComponent has relatively self-explanatory methods such as open() and requestActive(). TopComponents live in docking modes (the somewhat confusingly named org.openide.windows.Mode). A Mode is a container for multiple TopComponents - a thing that has Tabs. Mode itself is not a GUI component, it is an abstract class that acts as a controller.

TopComponents can be instantiated and opened on the fly, but typically a module installs its UI components via several XML files inside its JAR file and pointers to those files in the module’s XML layer file.