.instance files

Almost all the time

Create a file whose name is the fully qualified name of the class you want to register, with the . characters replaced with - characters and the extension .instance - e.g. <file name="com-foo-mymodule-MyStatusBarElementProvider.instance"/>. You can also give the file a different name and instead declare the type using a FileObject attribute, e.g. <blockquote>`<file name="x.instance">   <attr name="instanceClass" stringvalue="com.foo.mymodule.MyStatusBarElementProvider"/> </file> </blockquote> [source,xml] ----

If you want to use a factory method and set up some configuration of the object using your own FileObject attributes, you can instead <ul><li>Create a public static method on some class, which takes a `FileObject as an argument, e.g.<blockquote>`<file name="x.instance">  <attr name="instanceClass" stringvalue="com.foo.mymodule.MyStatusBarElementProvider"/>  <attr name="instanceCreate" methodvalue="com.foo.mymodule.MyStatusBarElementProvider.factoryMethod"/>  attr name="yourCustomAttribute" stringvalue="someValueYouCareAbout"/></file>`</blockquote> ----

.settings files

In specialized situations when the object may be saved back to disk with changed state at runtime and you cannot simply use NbPreferences

Create an XML file in your module for your settings file, populated as described in the .settings file FAQ. Register that file in some folder by specifying the XML file as the URL of the <file> entry in your layer, e.g. <file name="MyObject.settings" url="theActualFile.xml"/> (in this case, the layer.xml file and the settings file are in the same Java package in your sources).

.shadow files

If you want your object to be a pseudo-singleton, but it will be registered in multiple folders, or the user may delete the shadow file and you need to provide a way for the user to recover it (i.e. a way to create a new .shadow file)

.shadow files are like unix symbolic links - they point to another file somewhere else in the system filesystem or on disk, and behave as if they were really that file. Use one of the other registration mechanisms described here to register your object in some folder. Then create a shadow file as described here which points to it. An example of this is Menu and Toolbar actions — all actions are registered in subfolders of the Actions/ folder in the system filesystem. The user might manually delete or rearrange them; the UI that allows this can also show all available actions, so that the user can replace accidentally deleted actions.

.ser (serialized object) files

Basically never

Write a serialized object out to disk in a file with the extension .ser, either on the fly at runtime into some folder under FileUtil.getConfigFile(), or serialize an object ahead of time somehow, copy it into your module sources, and register something like <file name="foo.ser" url="relative/path/in/module/sources/from/layer/dot/xml/to/foo.ser"/>. Remember that if you use serialization, any change to the class you serialized is likely to break loading of existing .ser files - this is almost never a good idea.

Your own file type

Basically never

Any DataObject type which contains an InstanceCookie (and ideally also an InstanceCookie.Of) can be registered in some folder. If this is done ` Lookups.forPath(&quot;path/to/parent/folder&quot;) ` can be used to find it and any other objects registered in that folder (whatever their file type). So you could create your own file type which provides these objects. Unless you are doing something very, very unusual, one of the existing registration mechanisms will almost always be sufficient. This mechanism may be useful if you have existing code which reads and writes files in some format, and you cannot change that code.