Monday, February 4, 2008

XPath evaluator module for Netbeans

Introduction

I do a lot XML and Xslt processing at my workplace. Altova XmlSpy has XPath tool for evaluating queries on edited XML file. I'm missing that (useful) feature in Netbeans so I decided to build something similar. Of course it's far away from Altova's version in features but it can be useful (and you can always extend it).

Creating module project

  1. New project: Choose File > New Project (Ctrl-Shift-N). Under Categories, select NetBeans Modules. Under projects, select Module and click Next.
  2. In the Name and Location panel, type XPathEvaluator in Project Name. Change the Project Location to any directory on your computer, such as /home/damir/Projects/netbeans. Leave the Standalone Module radio button selected.
  3. In the Basic Module Configuration panel, replace yourorghere in Code Name Base with netbeans.modules, so that the whole code name base is org.netbeans.modules.xpathevaluator. Leave the location of the localizing bundle and XML layer, so that they will be stored in a package with the name org/netbeans/modules/xpathevaluator.
  4. Click finish.

Add module dependencies

In project tree right click on Libraries Node > Add module dependency...

  1. Import Datasystems API by typing datasystems
    It contains XmlDataObject which we will listen for.

Create a TopComponent for evaluating queries and displaying results

  1. New file (Ctrl-N). Under Categories, select Module Development. Under file types, select Window Component and click Next.
  2. Window Position: output
  3. Leave Open on Application start unchecked
  4. Class Name Prefix: XPathEvaluator
  5. Package: org.netbeans.modules.xpathevaluator
  6. Click finish
Now lets build interface in design view. We have to add following controls:
  • 2x JLabel
  • 1x JTextField for XPath input
  • 1x JTextArea for XPath results
TopComponent should look like this:

Create action for displaying XPathEvaluatorTopComponent

  1. New file (Ctrl-N). Under Categories, select Module Development. Under file types, select Action and click Next.
  2. Check conditionally enabled and choose EditorCookie for cookie class
  3. GUI registration:
    • Category: XML
    • Uncheck Global Menu Item
    • Check Editor Context Menu and choose text/xml for content type, change position to Tools - HERE
    • Check Separator before and Separator after
  4. Name, Icon, and Location:
    • Class Name: ShowXPathEvaluatorAction
    • Display Name: XPath Evaluator
    • Package Name: org.netbeans.modules.xpathevaluator
  5. Click finish
When user choose XPathNavigator item from xml's context menu we will show him XPathEvaluatorTopComponent but before showing we will create org.w3c.dom.Document from editorCookie's input stream and pass it.
PerformAction method should look like this:

protected void performAction(Node[] activatedNodes)
{
    EditorCookie editorCookie = activatedNodes[0].getLookup().lookup(EditorCookie.class);

    try
    {
        DocumentBuilderFactory domFactory = DocumentBuilderFactory.newInstance();
        domFactory.setNamespaceAware(true);
        DocumentBuilder builder = domFactory.newDocumentBuilder();
        Document doc = builder.parse(((org.openide.text.CloneableEditorSupport) editorCookie).getInputStream());

        XPathEvaluatorTopComponent win = XPathEvaluatorTopComponent.findInstance();
        win.setDocument(doc);
        win.open();
        win.requestActive();
    }
    catch (SAXException ex)
    {
    //Exceptions.printStackTrace(ex);
    }
    catch (ParserConfigurationException ex)
    {
    //Exceptions.printStackTrace(ex);
    }
    catch (IOException ex)
    {
    //Exceptions.printStackTrace(ex);
    }
}
      
Press Ctrl+I to fix imports. Make sure you select org.w3c.dom.Document from combo box.

Extending XPathEvaluatorTopComponent

We have to:

  • create private member which will hold org.w3c.dom.Document from selected editor and on which we will execute XPath.
  • create setDocument(org.w3c.dom.Document doc) method for setting current xml document.
  • create evaluate() method for executing and displaying XPath query.
  • add DocumentListener to jTextField1 for executing XPath query as we type.
  • listen for changes in TopComponent selection (when user opens/activates/closes other xml or non xml panel).
I will focus on last three points and let you struggle with other two :)

evaluate() method

This method is simple. It evaluates text from jTextField1 control and fills jTextArea1 control with results after clearing the same. If there were errors it shows them at bottom of window (jLabel2). xmlDoc is current xml document.

private void evaluate()
{
    if (xmlDoc != null)
    {
        try
        {
            XPathFactory factory = XPathFactory.newInstance();
            XPath xpath = factory.newXPath();
            XPathExpression expr = xpath.compile(jTextField1.getText());

            NodeList nodes = (NodeList) expr.evaluate(xmlDoc, XPathConstants.NODESET);
            jTextArea1.setText("");
            for (int i = 0; i < nodes.getLength(); i++)
            {
                jTextArea1.setText(jTextArea1.getText() + nodes.item(i).getNodeValue() + "\n");
            }
        }
        catch (XPathExpressionException ex)
        {
            jLabel2.setText(ex.getMessage());
        }
    }
}
      

DocumentListener for XPath input

Append following code at the end of XmlPathEvaluatorTopComponent's constructor:

jTextField1.getDocument().addDocumentListener(new DocumentListener()
{
    public void insertUpdate(DocumentEvent e)
    {
        evaluate();
    }

    public void removeUpdate(DocumentEvent e)
    {
        evaluate();
    }

    public void changedUpdate(DocumentEvent e)
    {
    }
});
      

Listen for changes in Lookup

Following code is based on Netbeans Selection Managment Tutorial I. We have to listen for global selection changes of "Object". In our case it is XmlDataObject. We have to extend our TopComponent to implement LookupListener.

final class XPathEvaluatorTopComponent extends TopComponent implements LookupListener
      
LookupListener provides a method for handling changes (resultChanged(LookupEvent ev)). We have to check if there are any instances of XmlDataObject selected and change xmlDoc value according to that.
  • If there are any XmlDataObject instances (in this case only one) then we have set xmlDoc member's value to selected XmlDataObject's XmlDocument and we have to enable input in window.
  • If there are not any instances then we have to set it to null and to disable input on window.
If we put only these two checks then we won't get waiting result. Supose that user selects xml file. If he change focus to XPathEvaluator window, Lookup event will be fired and there won't be any XmlDataObject selected and our module will be unusable.
To avoid this we have to check if our window (XPathEvaluator) is selected.
public void resultChanged(LookupEvent arg0)
{
    // if this window selected then do nothing
    if (TopComponent.getRegistry().getActivated().equals(this))
    {
    // do nothing
    }
    else
    {
        Lookup.Result r = (Lookup.Result) arg0.getSource();

        Collection c = r.allInstances();
        // if there are instances
        if (!c.isEmpty())
        {
            try
            {
                XMLDataObject o = (XMLDataObject) c.iterator().next();
                setDocument(o.getDocument());
                evaluate();
                jLabel2.setText(o.getName());
                jTextArea1.setEnabled(true);
                jTextField1.setEnabled(true);
            }
            catch (IOException ex)
            {
                jLabel2.setText(ex.getMessage());
            }
            catch (SAXException ex)
            {
                jLabel2.setText(ex.getMessage());
            }
        }
        else
        {
            xmlDoc = null;
            jTextArea1.setEnabled(false);
            jTextField1.setEnabled(false);
            jLabel2.setText("no selection");
        }
    }
}
      
Now we have to register LookupListener. We will do that when window is opened:
@Override
public void componentOpened()
{
    Lookup.Template tpl = new Lookup.Template(org.openide.loaders.XMLDataObject.class);
    result = Utilities.actionsGlobalContext().lookup(tpl);
    result.addLookupListener(this);
}
      
When we close window we have to unregister the listener:
@Override
public void componentClosed()
{
    result.removeLookupListener(this);
    result = null;
}
      
We have to create a member for holding the result where lookup listener is registered. You can find explanation for this in Netbeans Selection Managment Tutorial I.

Result

8 comments:

marvi said...

Thanks! You make really nice tutorials.

damir said...

Thank you for reading and I'm glad you like them :)

Varun said...

Hi,

My name is Varun Nischal and I'm the NetBeans Community Docs Contribution Coordinator. Your blog entry would make a fantastic tutorial for our Community Docs wiki (http://wiki.netbeans.org/CommunityDocs).

Would you be willing to contribute it? If you need any help or have any questions, please contact me at nvarun@netbeans.org

I look forward to hearing from you.

Thanks,
Varun Nischal
http://nb-community-docs.blogspot.com/
--
"You must do the things you think you cannot do."

Al said...

You should make this plugin available for download. It would be very helpful.

damir said...

Hi Al,

you can find downloadable source code in this post.

All the best,
Damir

Mark Ellul said...

Any chance of releasing this as a plugin? If not do you know if code works with latest version of netbeans 6.7 M2

damir said...

Well, I didn't planned releasing it as plugin because it's not production ready (in my opinion). You can download source code and see if it works in Netbeans 6.7 M2.

Pasi said...

This really looks like something that should be part of NB plugins. Exactly what I need right now but unfortunately don't have time to install it from source.
Looks great. I hope to see this released soon!