Part 1 - XML Multiview + Visual Library

Sunday Feb 25, 2007

Introduction

In Netbeans, to represent a file visually, you can use Multiview API to have multiple sectioned views. XML multiview builds top of this API and adds support for XML based data model. You can see the XML multiview in action while editing the web.xml in any Web application created inside Netbeans. Here is the screenshot:

Still not a standard API

XML multiview API is not a standard API now, but in future it may be included as a standard API.
Please note that both these APIs are still under development and they are subjected to change until they are published as stable APIs.

If we want to use these APIs now, then we need to depend on the current implementation version. (You might know that every Netbeans module API specifies two kinds of version information: specification version and the implementation version.) If we depend upon the implementation version rather than the published specification version, there is quite a good chance that we will face some issues during deployment and providing updates.

Book example

With that let's get started. For this we will use the Geertjan's book example and extend it to integrate the Visual library to display Book and its chapters in a graph. First, download the Book sample project from his update center, or download it here. Unzip and open the project in Netbeans 5.5 IDE. When you run the project and open the abc.story file (from file menu), you can see the multiview in action.

This book example, is part of the Netbeans source and it is a test project in automated unit tests for XML multiview module. This example was used by Geertjan to illustrate how the multiview looks.  If you have the 5.5 sources, you can find this project under <sources_root>/xml/multiview/test/unit. So this project contains the necessory support files and some additional code for the unit tests.

Digging deep into the example 

The following picture shows the BookMVEditorSample project view with relevant files highlighted.
In this sample,  the file abc.story is the XML file for which the XML multiview editor is written.  A new filetype support is added to this file to make Netbeans understand this file as some XML file. The advantage is getting XML editing support and DataObject support. There is a tutorial which explains how to add filetype support for an arbitrary file such as jar manifest file. BookDataLoader.java, BookDataNode.java, BookDataObject.java, BookResolver.java and layer.xml files are created when the new filetype support is added. The dataloader is a loader which creates dataobject from the FileObject. The datanode provides the view for the file. For example, you can set an icon for the file to show in the treeview, when this file is displayed in the explorer view such as Project view. The resolver file adds a MIME type support. the layer.xml file is the metafile for the whole module and it has the registration for the new filetype as below:

Book.java and Chapter.java are model classes. These hold the marshalled XML data. In the original example, these classes are generated using schema2beans library. Because of the loose coupling between XML multiview and the model used, we can use JAXB stubs too in place of these.

Setting dependency for the project 

As I mentioned earlier, the XML multiview extends the basic Multiview API. And as XML multiview API is not a standard API, the Book sample depends on the implementation version of it. You can do that for your project by adding a dependency and choosing the implementation version in the 'Edit dependency' dialog as below: 

XML multiview provides two types of built-in views : Toolbar view and TreePanelView. And there are base classes to implement these views. BookToolBarMVElement implements the toolbar view, while BookTreePanelMVElement implements a treepanel view. (refer the above projectview figure). The web.xml view is a toolbar view. The book example has code for both toolbar view and treepanelview (as you can see both files,BookToolBarMVElement and  BookTreePanelMVElement are present). We will use toolbar view, which will enable us to implement a visual graph in one of the multiview.

MultiView code

The BookDataObject is the starting point. The new filetype wizard will generate this file. For adding multiview support, this file extended to have multiview specific code. Specifically, the dataobject is changed to extend the XMLMultiViewDataObject, instead of UniDataObject as shown below.

Customizing the DataObject

Extend the constructor

Parse Document 

Model synchronizer is the one which takes care of two way synchronization between the view and the XML file. We add CheckXMLCookie and ValidateXMLCookie to the existing list of cookies to make use of the XML support provided by the Netbeans platform. The parseDocument() method is of current interest.

Construct MultiView Description 

As this example uses schema2beans library for generating the model, you see it used here in this method shown above. The Book is the  root tag. The call to Book.createGraph(), will result in parsing the whole XML file and constructing  a XML graph objects with the data filled in. If we plan to use some other library to generate the model, then here is the first place to edit. 

Next, the DesignView is the multiview descriptor class which constructs a multiview. We can see that this class constructs a toolbar view by returning BookToolBarMVElement at line 110. Note how the dataobject (model, in our case) is passed to the actual MVElement.

Now, return this DesignView in the overridden method 'getMultiViewDesc()' as above. Note that if we want, the TreePanelView instead of the toolbar view, here is the place to change.

Attach multiview section to a XML element 

By default, the XML Multiview API provides the XML file view. We need to tell the API to open up a particular multiview section for particular XML tag. The showElement() does this.

Model Synchronization

The model synchronization is handled by extending the ModelSynchronizer class as follows:

You need to return true from mayUpdateData() to tell the API that you need synchronization and this model synchronization should be called to do that. The updateDataFromModel() method does the actual sync. It takes the model object and calls the write() method of BaseBean, which is part of schema2beans. Again, this is the place to change if we want to use other derived model classes such as from JAXB.  In the original book example, there are two errors: first, the call to the datacache is commented out at line 173, which turns off the sync altogether and second, the updateDataFromModel() is overridden wrongly. The filelock object is of the type: org.openide.filesystems.FileLock and not java.nio.channels.FileLock. If you have downloaded this example from my blog link, you have these errors fixed already.

Connect model synchronizer to the rest

The above code calls the model synchronizer when needed. This call usually originates from the view.

This is the end of Part 1 of this series. In this, we explored what is XML multiview and how to start implementing one for a custom XML file. The next part shows how we can actually provide the UI in the multiview elements.

Disclaimer: The modules described here are purely experimental so no guaranties. Use at your own risk.

Like this post? | | | |

Posted at 06:02PM Feb 25, 2007 by Vadiraj D in Netbeans
Tags: book example graph library multiview visual xml