Introduction
Top-Braid Composer (TBC), a product of TopQuadrant, Inc., is a graphical development environment for modeling data, connecting data sources, and designing queries, rules and semantic data processing chains.
The AllegroGraph TopBraid Composer Plugin lets the TBC user connect to an AllegroGraph server, load data into an AllegroGraph triple store, and execute SPARQL queries against the triple store. If the user has the proper AllegroGraph privileges, it is also possible to issue Prolog queries and to use the RDFS++ inference.
Installing TopBraid Composer
Download TopBraid Composer from the TopQuadrant web site:
http://www.topquadrant.com/downloads/topbraid-composer-install/ The TopBraid Composer installation instructions are on that page.
You may use either the Standard Edition or the Maestro Edition.
Installing the AllegroGraph Plugin
Run TopBraid Composer.exe. You should find it in the top-level directory of the files you unzipped.
In the TopBraid interface, open the Help menu and select Install new software... This opens the Available Software dialog.
Click the Add... button in the upper right corner. This opens the Add Site dialog box.
Type "AllegroGraph Plugin" into the Name field, and paste the AllegroGraph Plugin URL into the Location field.
For TBC 5.0.1 release and 5.0.x releases for x equal 1 or larger (tested on 5.0.1)
http://www.franz.com/ftp/pub/agraph/eclipse/tbc/5.0.1 For TBC 5.0 release (unsupported because of software issues, see TBC 5.0.1)
For TBC 4.6.x releases (tested on 4.6), the appropriate URL is:
http://www.franz.com/ftp/pub/agraph/eclipse/tbc/4.6 For TBC 4.5.x releases (tested on 4.5), the appropriate URL is:
http://www.franz.com/ftp/pub/agraph/eclipse/tbc/4.5
For TBC 4.4.x releases (tested on 4.4 and 4.4.1), the appropriate URL is:
http://www.franz.com/ftp/pub/agraph/eclipse/tbc/4.4 For TBC 4.3.x releases (tested on 4.3.0), the appropriate URL is:
http://franz.com/ftp/pub/agraph/eclipse/tbc/4.3 For TBC 4.2.x releases (tested on 4.2.0 and 4.2.1), the appropriate URL is:
http://franz.com/ftp/pub/agraph/eclipse/tbc/4.2 For TBC 4.1.x releases (tested on 4.1.0), the appropriate URL is:
http://franz.com/ftp/pub/agraph/eclipse/tbc/4.1 For TBC 4.0.x releases (tested on 4.0.0), the appropriate URL is:
http://franz.com/ftp/pub/agraph/eclipse/tbc/4.0 For TBC 3.6.0 and 3.6.1 releases, the appropriate URL is:
http://franz.com/ftp/pub/agraph/eclipse/tbc/3.6 Note: the TBC 3.6.2 release was discontinued by Top Quadrant, and the AG plugins are not available for that release (please use the TBC 4 or 3.6.1 release instead).
For TBC 3.5.x releases, the appropriate URL is:
http://franz.com/ftp/pub/agraph/eclipse/tbc/3.5 and for TBC 3.4.x or TBC 3.3.x releases, the URL is:
http://franz.com/ftp/pub/agraph/eclipse/tbc/plugins Versions prior to TBC 3.3 are not supported.
Click the OK button to close the Add Site dialog. This returns focus to the Available Software dialog.
On the Available Software dialog, uncheck the Group items by category checkbox. Then check the box next to com.franz.agraph.feature. Click the Next button.
Confirm that you want to install the AllegroGraph plugin. Accept the license agreement. Ignore the warning about unsigned plugins. The Available Software dialog will close.
Close and restart TopBraid Composer to activate the AllegroGraph plugin.
Testing the Installation
To test the AllegroGraph plugin installation, you will need access to an AllegroGraph server (version 4.0.6 or later). You will need the URL and port number of the server, plus the name and password of an AllegroGraph user who is authorized to create and manipulate a triple store.
The test consists of taking a .owl ontology in the TopBraid environment, converting it into AllegroGraph format, pushing it to a triple store on the AllegroGraph server, and then running a SPARQL query that returns results from AllegroGraph back to TopBraid Composer.
Connect TBC to AllegroGraph
Create a new folder in the Navigator Pane to contain your AllegroGraph ontologies. Right-click the TopBraid node and follow the context menu to New > Folder. Name the folder AG4.
In the Navigator Pane, open the TopBraid/Examples node and double-click on geotravel.owl. This will open the ontology in various panes of the TopBraid interface.
The next step is to export geotravel.owl as an AllegroGraph database. In the Navigator Pane, right-click the TopBraid/AG4 node, and select Export from the context menu. In the Export dialog box, open the TopBraid Composer node and select Export/Merge/Convert RDF Graphs. Click Next.
On the next panel, select the AllegroGraph 4 Database Storage (*.ag4) format, and give the target file a name, such as geotravel. No suffix is needed on the file name. We only want to export one graph: geotravel.owl. Click Next.
On the next panel, enter your AllegroGraph URL, port number, and credentials. Enter the name of an existing AllegroGraph catalog, or leave that field blank to use the default RootCatalog. Then enter the name of the repository you want to use within that catalog, such as tbcgeo. If you use a new repository name, AllegroGraph will create a repository for you.
(Note that Catalogs cannot be created from TopBraid Composer. New catalogs are created by editing the AllegroGraph server's configuration file.)
Click Finish. TopBraid Composer will upload the data to the AllegroGraph server. This might take a while, depending on the size of your ontology file. For the geotravel example, it takes a few seconds.
When the data finishes loading, you should see a geotravel.ag4 file in your TopBraid/AG4 folder.
Close the geotravel.owl overview panel. (If you omit this step, TopBraid will complain about having two copies of the same model open at the same time when you export to AllegroGraph.)
In the Navigator Pane, double-click the geotravel.ag4 file. You'll see an AG4 Repository Connection dialog box that displays your AllegroGraph connection information and credentials. There is no need to change these settings. Click Finish.
SPARQL and Prolog Queries
Open TopBraid's SPARQL editor pane (look for the SPARQL tab). It contains a default SPARQL query that searches for rdfs:subClassOf triples. The SPARQL window has three buttons that let you run a query with or without locally-configured inferencing. Click the green "Run" button to run this query. After a few seconds you will see a table of ?subject and ?object values returned from the triple store.
The TopBraid SPARQL editor lets you use TopBraid's local inference features. To use AllegroGraph's server-side inference (and to pose Prolog queries in addition to SPARQL queries), you'll need to open the Agraph View. Select Window menu > Show view > Other... to open the Show View dialog box. In the TopBraid folder select the Agraph view. Click the OK button.
This opens a new query-editing pane in the TopBraid window. This Agraph view accepts both SPARQL and Prolog queries. It has three buttons that perform the following functions:
- Execute the query.
- Toggle on/off AllegroGraph's reasoning.
- Toggle SPARQL/Prolog query language.
To try a Prolog query, copy this text into the edit pane:
(select (?s ?o)
(q ?s !rdfs:subClassOf ?o)) Click the button that selects the Prolog query language. Then click the Run button.
Query results from the Prolog query prove that the AllegroGraph plugin is installed and working correctly.
Connecting TBC to the Virtual Server on Windows or Mac
AllegroGraph runs on 64-bit (x86-64) Linux. Windows and Mac users can simulate a 64-bit Linux environment using the AllegroGraph Virtual Machine, which can be downloaded from the AllegroGraph Download page. The virtual machine has AllegroGraph pre-installed on port 10035. TopBraid Composer can be connected to the virtual machine for experiments where performance is not critical.
Both the virtual server and TopBraid can be installed on the same laptop, if desired, or TopBraid can connect to the virtual machine from another computer across a network.
TBC and VM on the Same Computer
To connect TopBraid Composer to a virtual AllegroGraph server, with both running on the same physical computer, all you need is the IP address of the virtual machine. This IP address is usually assigned when the virtual machine comes on line, and may change from session to session. To discover the current IP address, open a terminal window in the virtual machine and type the ifconfig command. (Note: ifconfig, not ipconfig.) The server's IP address is in the second line of the response.
Use this IP address and the AllegroGraph port number (10035) when you connect TopBraid Composer to the virtual AllegroGraph server.
Connect TBC to the VM on a Local Network
The AllegroGraph Virtual Machine's network adaptor is set of Network Address Translation (NAT) by default. This setting makes it easy to connect TBC to the VM when both are on the same host computer. If you have TBC and the VM running on separate computers, you might encounter difficulty making the connection.
To connect to a virtual AllegroGraph server on a network computer, you will have to reconfigure the virtual machine's network adaptor. Open the VM menu > Settings... > Network Adaptor dialog box. The object is to turn off NAT and enable "bridging" instead.
Windows
Select "Bridged: Connect directly to the physical network." Check the option that says "Replicate the physical network connectivity state."
Mac
Select "Connect directly to the physical network (Bridged)." Select "Autodetect."
Close the dialog box and reboot the virtual machine. Use "ifconfig" to get the new IP address. This address (using port 10035) will connect across the network.
If there are further issues, see the VMware documentation.
Checking for Updates
The AllegroGraph TopBraid Composer plugin will be updated as needed. To check for an update, open the Help menu and select Check for Updates.
Removing the AllegroGraph Plugin
To remove the AllegroGraph plugin from TopBraid Composer, open the Help menu and select Install New Software.... On the resulting dialog box, click the link labeled "What is already installed?"
This opens a list of installed plugins. Click on com.franz.agraph.feature and then on the Uninstall... button.