To obtain a FileObject for an existing file on the local file system, use the helper class FileUtil:

FileObject obj = FileUtil.toFileObject(new File("C:/file.txt"));

To create a FileObject from a specific FileSystem object, call the findResource() method, using the full path:

FileSystem fs = Repository.getDefault().getDefaultFileSystem();
FileObject obj = fs.findResource("folder/file");

This is the manner in which you create a FileObject for data located in the System Filesystem, which is an XMLFileSystem.

The following allows you to create new files or folders using FileObjects:

File file   = new File("E:/newfolder/newfile.txt");
File folder = new File("E:/newfolder2");
FileObject fo1 = FileUtil.createData(file);
FileObject fo2 = FileUtil.createFolder(folder);

If you already have a FileObject folder, create a file or folder in the corresponding file system as follows:

FileObject folder  = ...
FileObject file = folder.createData("newfile.txt");
FileObject subfolder = folder.createFolder("newfolder");

To rename a folder or file, make sure someone else is not editing it at the same time, by using a FileLock object. This lock is released after renaming, using a finally block.

FileObject myfile = ...
FileLock lock = null;
try {
   lock = myfile.lock();
} catch (FileAlreadyLockedException e) {
   return;
}
try {
   myfile.rename(lock, "newfilename", myfile.getExt());
} finally {
   lock.releaseLock();
}

Deleting folders or files is straightforward. The delete() method takes care of reserving and releasing a FileLock. Consequently, deleting only requires the following line:

FileObject myfile = ...
myfile.delete();

A variant of the delete() method is available that enables users to pass their own file FileLock, analogous to the renaming of a FileObject.

A FileObject cannot be moved in the same way as a File, simply by renaming. Instead, this is achieved by using the method moveFile(), provided by the class FileUtil. It allows moving FileObjects and handles copying files or folders to the destination folder, deleting the source and automatically allocating and releasing the required FileLock objects.

FileObject fileToMove = ...
FileObject destFolder = ...
FileUtil.moveFile(fileToMove, destFolder, fileToMove.getName());

Reading and writing FileObjects is done, as usual in Java, by streams. The FileObject class provides the methods InputStream and OutputStream for this purpose. We wrap these for reading in a BufferedReader and for writing in a PrintWriter, as shown in Listing 7-1.

FileObject myFile = ...
BufferedReader input = new BufferedReader(
   new InputStreamReader(myFile.getInputStream()));
try {
   String line = null;
   while((line = input.readLine()) != null) {
      // process the line
} finally {
   input.close();
}
PrintWriter output = new PrintWriter(
   myFile.getOutputStream());
try {
   output.println("the new content of myfile");
} finally {
   output.close();
}

You optionally pass your own FileLock to the method getOutputStream().

To monitor changes, register a FileChangeListener for the FileObject that responds to data changes inside the file system (see Listing 7-2).

File file = new File("E:/NetBeans/file.txt");
FileObject fo = FileUtil.toFileObject(file);
fo.addFileChangeListener(new FileChangeListener(){
   public void fileFolderCreated(FileEvent fe) {
   }
   public void fileDataCreated(FileEvent fe) {
   }
   public void fileChanged(FileEvent fe) {
   }

public void fileDeleted(FileEvent fe) {
   }
   public void fileRenamed(FileRenameEvent fre) {
   }
   public void fileAttributeChanged(FileAttributeEvent fae) {
   }
});

The methods fileFolderCreated() and fileDataCreated(), called when a file or folder is created, only make sense when the monitored FileObject is a folder.

While changing files, the event is always processed for the file itself, as well as its parent directory. This means that you will be informed of changes of files, even when only monitoring the parent directory. If you are not interested in all the events of the FileChangeListener interface, use the adapter class FileChangeAdapter instead.

The classes FileSystem, FileObject, and FileUtil provide several additional and helpful methods. It is worth having a closer look at the documentation of the File Systems API.

First, specify the functionality of the Mp3DataObject by an interface. Call it PlayCookie and specify the method play(), used to play the corresponding Mp3DataObject:

public interface PlayCookie {
   public void play();
}

Also required is an implementation of functionality specified by our cookie—possibly the direct implementation of the interface by the class Mp3DataObject. Better is to use a separate class, a so-called support class. This permits flexibly adding and removing functionality to and from the Mp3DataObject. Semantic grouping of multiple cookies is possible as well, and the Mp3DataObject class remains lean.

public class PlaySupport implements PlayCookie {
   private Mp3DataObject mp3 = null;
   public PlaySupport(Mp3DataObject mp3) {
      this.mp3 = mp3;
   }
   public void play() {
      //Mp3Player.getDefault().play(mp3);
      System.out.println("play file");
   }
}

Now, adding an instance of this support class to the CookieSet of the Mp3DataObject class is required. This is accomplished using the method getCookieSet() and adding an instance of the class PlaySupport via assign(). Here, we also set the type to PlayCookie, although you can use the PlaySupport class. But this method allows us independence from the implementation.

public class Mp3DataObject extends MultiDataObject {
   public Mp3DataObject(FileObject pf, MultiFileLoader loader)
      throws DataObjectExistsException, IOException {
      super(pf, loader);
      getCookieSet().assign(PlayCookie.class, new PlaySupport(this));
   }
}

We have now added functionality to the Mp3DataObject such that it can be used outside the local Lookup available via getLookup().

A question remains concerning access to the functionalities of a DataObject. This is answered by a CookieAction class. Use the class MyCookieAction created in Chapter 4 or create a new class via the wizard with File

The method cookieClasses() is implemented as follows:

protected Class[] cookieClasses() {
   return new Class[] { Mp3DataObject.class };
}

As shown in Chapter 4, the performAction() method of the CookieAction receives selected nodes. As you have seen in the Mp3DataObject 's createNodeDelegate() method, the node representing the Mp3DataObject receives the local Lookup from the Mp3DataObject. This Lookup allows us querying the functionalities of the Mp3DataObject. In other words, the DataNode is a proxy for the Mp3DataObject. It is precisely that Lookup that we obtain from the selected node via the performAction() method. As usual, we now use the Lookup, via the getLookup() method, to obtain an instance of PlayCookie, after which we execute its play() method.

protected void performAction(Node[] nodes) {
   PlayCookie pc = nodes[0].getLookup().lookup(PlayCookie.class);
   pc.play();
}

Test the code using the Favorites module. Make sure the Favorites module is active in the application by going to Properties

By means of the example in Listing 7-4, the provided functionalities of an Mp3DataObject can be changed at runtime, which also implicitly control the actions available to the user. Previously, we created a cookie and a support class that plays an MP3 file. Now we create another to stop an MP3 file. Set the current play status of the Mp3DataObject using the method playing().

public interface PlayCookie {
   public void play();
}
public class PlaySupport implements PlayCookie {
   private Mp3DataObject mp3 = null;
   public PlaySupport(Mp3DataObject mp3) {
      this.mp3 = mp3;
   }
    public void play() {
       System.out.println("play");
       mp3.playing(true);
    }
}
public interface StopCookie {
   public void stop();
}
public class StopSupport implements StopCookie {
   private Mp3DataObject mp3 = null;
   public StopSupport(Mp3DataObject mp3) {
      this.mp3 = mp3;
   }
   public void stop() {
      System.out.println("stop");
      mp3.playing(false);
  }
}

We use the constructor to create both support classes. We can assume that the MP3 file is not being played, and we assign the PlaySupport class to the CookieSet. Using the playing() method, called by the support classes, we change the cookies available in the CookieSet. If the file is currently being played, all instances of PlayCookie are removed by passing the type without any instances to the assign() method, and adding an instance of StopCookie (see Listing 7-5). If the file is stopped, everything happens in reverse order.

public class Mp3DataObject extends MultiDataObject {
   private PlaySupport playSupport = null;
   private StopSupport stopSupport = null;

   public Mp3DataObject(FileObject pf, MultiFileLoader loader)
      throws DataObjectExistsException, IOException {

super(pf, loader);
      playSupport = new PlaySupport(this);
      stopSupport = new StopSupport(this);
      getCookieSet().assign(PlayCookie.class, playSupport);
   }

   public synchronized void playing(boolean value) {
      if(value) {
         getCookieSet().assign(PlayCookie.class);
         getCookieSet().assign(StopCookie.class, stopSupport);
      } else {
         getCookieSet().assign(StopCookie.class);
         getCookieSet().assign(PlayCookie.class, playSupport);
      }
   }
}

Making the example complete requires two additional action classes used to start and stop the MP3 file. These are two CookieAction classes, using PlayCookie and StopCookie as cookie classes (see Listing 7-6 for the PlayAction class). The menu (or toolbar) entries are activated or deactivated automatically, depending on which cookie or support class is currently provided by the selected MP3 file.

public final class PlayAction extends CookieAction {
   protected void performAction(Node[] n) {
      PlayCookie pc = n[0].getLookup().lookup(PlayCookie.class);
      pc.play();
   }
   protected Class[] cookieClasses() {
      return new Class[] { PlayCookie.class };
   }
}
public final class StopAction extends CookieAction {
   protected void performAction(Node[] n) {
      StopCookie sc = n[0].getLookup().lookup(StopCookie.class);
      sc.stop();
   }
   protected Class[] cookieClasses() {
      return new Class[] { StopCookie.class };
   }
}

Normally, a DataObject need not be created explicitly, but is created by the DataLoader pool on demand. Optionally, you can create a DataObject for a given FileObject using the static find() method of the DataObject class:

FileObject myFile = ...
try {
   DataObject obj = DataObject.find(myFile);
} catch(DataObjectNotFoundException ex) {
   // no loader available for this file type
}

If no DataLoader or DataObject.Factory is registered for the given file, a DataObjectNotFoundException is thrown.

A DataLoader is a factory for a DataObject and is responsible for exactly one data type. The DataLoader recognizes the type of the file, either by file extension or XML root element. DataLoaders are implemented by modules and registered via the layer file. This registration can be used to find the corresponding DataLoader for an appropriate file type. Basically, there exist two types of DataObjects: a DataObject representing only one file, the primary file; and a DataObject that contains additional files, the so-called secondary files. Depending on which data type used, you need different types of DataLoaders.

Using a DataObject with only one primary file, as in our MP3 example, select a DataLoader of the type UniFileLoader. Whenever DataLoaders need to load additional secondary files, choose a MultiFileLoader. The UniFileLoader is only a special variant of the MultiFileLoader, and its created objects are of the type MultiDataObject. You can directly derive from DataLoader and DataObject, but it is considerably easier to use the MultiFileLoader or UniFileLoader class.

The DataLoader Mp3DataLoader responsible for the creation of DataObjects of the type Mp3DataObject was created by the NetBeans wizard. It inherits the abstract superclass UniFileLoader, since our Mp3DataObject solely represents an MP3 file or FileObject. Observe the assembly and functionality of a DataLoader by means of the Mp3DataLoader (see Listing 7-8).

A DataLoader is responsible for a specific MIME type. First, define this type by a private data element. Use the type audio/mpeg. Pass the complete name and DataObject class for which the DataLoader is responsible to the base class constructor. This representation class is labeled for our example as com.galileo.netbeans.module.Mp3DataObject.

Setting a displayable name for the DataLoader is done by overriding the method defaultDisplayName(), in which we read the name from a resource bundle. The initialize() method is used to call the method of the base class and afterward to add the MIME type to the ExtensionList, accessed via the getExtensions() method. The DataLoader infers the file extension from the MIME type, using the file Mp3Resolver.xml, created by the wizard and registered in the layer file in the Services/MIMEResolver folder. If you don't register the MIME type to the ExtensionList using addMimeType(), you can pass the file name directly via addExtension(), making the file Mp3Resolver.xml and its entry in the layer file obsolete.

Registration of file name extensions or MIME types in an ExtensionList allows the DataLoader to recognize its responsibility for a specific file type. Checking if a DataLoader comes into consideration for a specific file type is done by findPrimaryFile(). The UniFileLoader, possessing the ExtensionList, already implements this method and checks if a MIME type or the extension of the parent file matches the type of DataLoader.

If you want to use a MultiDataLoader, you need to implement the method yourself, and should first check if the passed FileObject is the primary file. In this case, directly return it; otherwise (if it is a secondary file), you have to find the appropriate primary file.

For that purpose, the method FileUtil.findBrother() is useful. Otherwise, the findPrimaryFile() method will return null, indicating the DataLoader is not responsible for the file type. The method createMultiObject() is the DataLoader 's factory method, responsible for creating an Mp3DataObject instance. This method is called with the primary file as a parameter (in this case an MP3 file), which we pass to the Mp3DataObject constructor. For the creation of MultiDataObject.Entry instances, which manage the FileObjects inside the DataObject, the responsible methods are createPrimaryEntry() and createSecondaryEntry(). For a UniFileLoader, only the createPrimaryEntry() method, which is already implemented, is needed. If you use a MultiFileLoader, you must implement both methods inside the subclass.

Last, a DataLoader defines a folder in the System Filesystem—the layer file in which actions are registered for the particular data type—using the method actionsContext().

These registered actions are shown in the node's context menu—that is, in the context menu of the node responsible for the presentation of the DataObject.

public class Mp3DataLoader extends UniFileLoader {
   public static final String REQUIRED_MIME = "audio/mpeg";
   public Mp3DataLoader() {
      super("com.galileo.netbeans.module.Mp3DataObject");
   }
   protected String defaultDisplayName() {
      return NbBundle.getMessage(Mp3DataLoader.class, "LBL_Mp3_loader_name");
   }
   protected void initialize() {
      super.initialize();
      getExtensions().addMimeType(REQUIRED_MIME);
   }
   protected MultiDataObject createMultiObject(FileObject pf)
      throws DataObjectExistsException, IOException {
      return new Mp3DataObject(primaryFile, this);
   }
   protected String actionsContext() {
      return "Loaders/" + REQUIRED_MIME + "/Actions";
   }
}

As already mentioned, with the introduction of the DataObject.Factory interface, the DataLoader superclass also implements this interface. This enables you to register your own DataLoader implementation in the layer file instead of the manifest file. The order of the loaders can be determined by the generic position attribute (see also Chapter 3).

The preceding Mp3DataLoader can be registered as Listing 7-9 shows.

<folder name="Loaders">
   <folder name="audio">
      <folder name="mpeg">
         <folder name="Factories">
            <file name="com-galileo-netbeans-module-Mp3DataLoader.instance">
               <attr name="position" stringvalue="100"/>
            </file>
         </folder>
      </folder>
   </folder>
</folder>

With this entry, you have registered your own DataLoader or DataObject.Factory implementation, which creates Mp3DataObjects.

A node makes a context menu available to the user, allowing context-sensitive actions. A DataNode obtains its context menu's actions from the DataLoader of the DataObject it represents. For this purpose, a DataLoader defines a MIME-specific folder in the layer file via the method actionsContext(), where actions are registered. These are read and added automatically to the context menu.

For nodes that do not represent DataObjects, the getActions() method in the Node is used to define the actions in the context menu. Override this method in your class to add more actions to the set provided by default by the NetBeans Platform. Add actions programmatically or use Lookup to retrieve them from the layer file (see the "Context Menu" section in Chapter 5). When overriding the getActions() method, make sure to add a call to super.getActions(), in addition to the actions you add to the set.

You can also override the getPreferredAction() method, which provides the action invoked when the user double-clicks the node. If you return null from this method, the first action from the getActions() array is invoked.

To react to Node events, use a PropertyChangeListener, as well as a NodeListener. Use the PropertyChangeListener to be informed of changes to Node properties provided via the getPropertySet() method. Via the NodeListener, you can listen to internal node changes, such as changes to the name, the parent node, and the child nodes. To that end, the Node class makes a range of property keys available, such as PROP_NAME and PROP_LEAF. The methods listed in Table 7-2 are offered by the NodeListener.

If you don't want to be informed of the events, or you don't want to implement them, use the NodeAdapter class instead of the NodeListener interface.