This is the second in a series of articles that explore some of the new features in Apache Pivot 1.1. Pivot is a Java-based RIA toolkit that is currently undergoing incubation at the Apache Software Foundation. The previous article provided an overview of the new drag and drop features in Pivot 1.1; this article introduces Pivot's support for browsing the local file system.

As noted in the previous article, a well-known pain point in web application development is file upload. A related issue is the web browser's inability to access the local file system. While unrestricted access to a user's hard drive is obviously a major security issue, this limitation imposes some serious technical and usability restrictions: applications that need to operate on locally stored content simply cannot be built using standard web technologies.

Enter Pivot 1.1's support for file browsing. Pivot applications are packaged and delivered via Java Archive (JAR) files and run in the Java Plugin, which allows JARs to be "digitally signed" by their authors. Signed applications may in turn be "trusted" by their users and granted access to the local file system. A complete discussion of digital security is well beyond the scope of this article - however, many books and articles have been written on the subject, and an overview can be found here.

While many web applications could benefit from the addition of local file system access, one of the most obvious is undoubtedly a file upload tool similar to the one discussed in the previous article. The developers of such a tool might want to allow the user to browse the local file system within the application UI itself, rather than requiring the user to open a native file browser window. Pivot provides classes that enable creation of this type of user interface right out of the box.

The following is a screen shot of a simple file browser application written in Pivot. It uses Pivot's TreeView component to provide a view of the user's local home directory:

A runnable example is available in the Demos section of the Pivot Wiki; the rest of this article discusses the program's implementation.

WTKX Source

The WTKX source code for the application is quite short:

 
<Border styles="{color:10, padding:0}"
    xmlns:wtkx="http://incubator.apache.org/pivot/wtkx/1.1"
    xmlns:content="pivot.wtk.content"
    xmlns="pivot.wtk">
	<content>
	    <ScrollPane preferredWidth="240" horizontalScrollBarPolicy="fillToCapacity">
	        <view>
	           <TreeView wtkx:id="folderTreeView">
	               <nodeRenderer>
	                   <content:TreeViewFileRenderer useNativeIcons="false"/>
	               </nodeRenderer>
	           </TreeView>
	        </view>
	    </ScrollPane>
	</content>
</Border>

The root element is a border component, which contains a tree view embedded in a scroll pane. The only thing of real interest in this example is the tree view's use of a TreeViewFileRenderer as a node renderer. This class is defined in the pivot.wtk.content package and allows the tree view to present instances of java.io.File (as well as pivot.io.Folder, discussed below) as tree nodes.

The Folder Class

Pivot 1.1 introduces a new class called pivot.io.Folder. This class extends java.io.File and implements pivot.collections.List<File>. In addition to being a generally useful means for programmatically navigating the local file system, since it extends List, the Folder class can also serve as the data model for a TreeView component.

After loading the WTKX file, the first thing the sample application does is set the tree view's data to a folder representing the user's home directory:

 
String pathname = System.getProperty("user.home");
folderTreeView.setTreeData(new Folder(pathname));

That's all there is to it. The user can now browse the local file system using the application's UI.

Although it isn't demonstrated here, this example could easily be combined with the example described in the previous article to serve as the foundation of an extremely usable file upload tool. Many other potential applications are also possible.

Event Handlers

While this example is clearly useful, it doesn't really do much. To make it a little more interesting, the application also installs a couple of event handlers on the tree view that showcase another handy Pivot feature: the ApplicationContext.open() method. This method allows a caller to open a given file using the native application associated with that file type. It associates both a mouse button listener and keyboard listener with the tree view that allow the user to double-click or press ENTER to open the currently selected file:

Mouse button listener:

 
folderTreeView.getComponentMouseButtonListeners().add(new ComponentMouseButtonListener() {
     public boolean mouseDown(Component component, Mouse.Button button, int x, int y) {
          return false;
      }
 
     public boolean mouseUp(Component component, Mouse.Button button, int x, int y) {
          return false;
      }
 
     public boolean mouseClick(Component component, Mouse.Button button, int x, int y, int count) {
          if (count == 2) {
               openSelectedFile();
           }
  
          return false;
      }
});

Keyboard listener:

 
folderTreeView.getComponentKeyListeners().add(new ComponentKeyListener() {
     public boolean keyTyped(Component component, char character) {
          return false;
      }
 
     public boolean keyPressed(Component component, int keyCode, Keyboard.KeyLocation keyLocation) {
          if (keyCode == Keyboard.KeyCode.ENTER) {
               openSelectedFile();
           }
  
          return false;
      }
 
     public boolean keyReleased(Component component, int keyCode, Keyboard.KeyLocation keyLocation) {
          return false;
      }
});

Both methods call the private openSelectedFile() method to launch the associated application:

 
private void openSelectedFile() {
     File file = (File)folderTreeView.getSelectedNode();
     try {
          ApplicationContext.open(file.toURI().toURL());
      } catch(MalformedURLException exception) {
          // No-op
      }
}

Conclusion

The inability to access the local file system from a web browser imposes both feature and usability limitations on web-based applications. Pivot 1.1's new support for file browsing alleviates this restriction and enables web applications to scale beyond their current server-based bounds.

For more information, visit http://incubator.apache.org/pivot.

Read more from Greg Brown.