HowTo write a connector
From SONIVIS:Wiki
Contents |
How to write a connector
When you are using SONIVIS you will notice that you can currently work with some specific forms of data. You can see what data we support "out of the box" by looking at the descriptions of mapped data. To further this list and get new data into SONIVIS from other sources you will have to write what we call a connector.
What exactly is a connector?
First and foremost a connector is a plugin for SONIVIS. In its simplest form this plugin provides SONIVIS with the means to extract you specific data. If you checkout our source code you will see some packages named "de.sonivis.tool.XXXconnector" with XXX being one of the corresponding mappings you'll find here - and there is an example connector (de.sonivis.tool.exampleconnector) to simplify connector development for you! Those packages are the connectors:
If you take a look at the connector plugins you will see that they all contain very different subpackages and classes. A connector plugin should bundle every specific aspect of your data. Everything specific you'll need for working with your data in SONIVIS needs to be implemented in your connector plugin. This concerns at least the following elements:
- your extractors (the most important part) - Learn how to write one
- your transformers - Learn how to write one
- your datamodel extensions - Learn how to da that
You can (and should) add everything you can think of that concerns you specific data (network definitions, metrics etc.) into your connector plugin.
How to begin?
First off, if you haven't already, you should refresh your knowledge of the Eclipse Plugin Architecture as the whole of SONIVIS is build as a plugin based application within the Eclipse framework.
Afterwards it's time to create your new plugin. Eclipse already provide you with whats needed to get you started. First choose the corresponding project template in the Eclipse dialog:
The most important thing to do here is naming you new plugin. Please follow the naming conventions we employ throughout SONIVIS and choose a name that lets your fellow developers see what kind of data your connector connects to. If, for example, you want to analyze a dump of email data you could name your connector "emaildumpconnector" which would lead to the name "de.sonivis.tool.emaildumpconnector" for your package. Either way, please use the correct namespace and a sensible name.
Everything else in the project dialog is pretty much up to you. If you're not sure what to choose just leave everything as suggested by Eclipse (otherwise known as the "when in doubt, leave unchanged" pattern). After you clicked the "finished" button Eclipse will create a plugin project for you in the currently selected workspace and you can start configuring your connector plugin.
What is needed?
If you take the simplest example of a connector that contains only one extractor there would be three essential steps if you want to fully implement your connector:
- Implement the extractor within your new connector plugin.
- Use the extension point in de.sonivis.tool.core.extractor to let SONIVIS know about your new extractor.
- Implement wizard pages to give SONIVIS users a convenient way to work with your extractor.
Let's see how you accomplish those steps.
How do I tell SONIVIS:Tool about my connector plugin?
There are essentially two steps to register your connector with SONIVIS. For the first bit you have to understand that the core class of every connector is something we call an extractor. The extractor basically is a class that extracts the data from your source (hence the name) and writes it into the SONIVIS database. A connector might consist only of this one class but for greater flexibility you can encapsulate much more functionality in your connector plugin.
Nonetheless as the extractor is the most important part of your connector you have to register it at the corresponding extension point provided by SONIVIS. If you don't know what an extension point ist, now might be good time to read up on extension points in Eclipse. Obviously to register an extractor class in your connector you first need a class that represents an extractor. For more on that please see "HowTo write an extractor".
You can register the extractor class within your connector plugin by going to the plugin.xml configuration file in your plugin project. Eclipse will give you a nice graphical user interface to edit this file. You will see a tabbed navigation on the bottom on the editor. The page you are looking for is called "extensions" where you can specify all the extensions your plugin provides for several available extension points. Make sure you end up with at least something that looks like this:
What you are seeing here is the result of clicking "Add..." and providing the necessary details for the class that represents the extractor in your connector plugin. Please note that your connector may very well provide several extractors depending on the data you want to extract. You have to provide one extension to the extension point "de.sonivis.tool.extractor" for each extractor your connector implements.
After that the hard part in terms of configuration is already over. All there's left to do is registering your new plugin in SONIVIS globally. For that purpose please have a look into the "de.sonivis.too.installer" package that you checked out with the rest of the source code. You'll find a "SONIVIS_tool.product" file in there which is the configuration file for the whole application. In the tab "Dependencies" you will see a rather long list of plugins that SONIVIS depends on. There you can register your newly created plugin so SONIVIS knows your new connector is part of the tool. Just click on "Add..." and choose your connector plugin from the list.
You're done configuring. Lets get to implementing.
What should be implemented in my connector plugin?
As noted before your connector plugin will be home to at least one extractor but you should implement everything needed to handle your data wihtin your connector. Maybe you need to implement a rather sophisticated API extractor that needs a lot of logic which should all be encapsulated in your connector. You can do that of course by using a sensible package structure within your connector plugin. The only thing SONIVIS needs from your connector is at least one extractor class that extends the abstract extractor from "de.sonivis.tool.core.datamodel.extractwizard".
For details on how to write this extractor class and what exactly an extractor is please see HowTo write an extractor.
Basically you'll need to implement extractFromSource(), getDescription and getWizardPages() from that abstract class with the first being the starting point of your extractor, the second providing a description for the user about your extractor and the third providing a set of wizard pages for the user to work with your extractor. Again, if you need more than one extractor in your connector you'll need to implement one class that extends the abstract class for each extractor needed. Of course every one of those classes needs to implement the aforementioned methods extractFromSource(), getDescription and getWizardPages().
How can SONIVIS users work with my connector?
As mentioned above, all your extractor classes need to implement the methods getDescription and getWizardPages(). They stem from the abstract extractor you need to extend and are both important for the users of SONIVIS to work with your extractors. Both are used in the extract wizard SONIVIS uses to guide its users through the extraction process.
To see the user's manual for that wizard please see the manual for the extractor wizard.
What you as a developer need to do is provide the wizard pages that can be included in the wizard so your users can provide all the necessary details for your extractors to work and a description for each of your extractors so your users will know what to expect.
Again, for details on all these methods please see the manual for the extractor wizard.
getDescription
This method simply returns a string containing a brief description that will be shown to the user when he chooses what extractor he wants to run.
getWizardPages
This method needs to return a set of wizard pages. It should handle all preference storing and basically handles your users' inputs.
