Vogon

Vogon Developer Documentation

by Ashwin Verleker

Vogon is an Eclipse RCP (Rich Client Platform) application that is used for annotating texts. It allows the user to import text and xhtml documents that can be annotated based on pre-defined rules to create appellations and relations between words present in the texts and concepts and vocabularies that are imported from remote services. The user creates a workspace in the application and all the texts and annotations that the user creates are stored in that workspace. This helps in organizing the texts in a manner that is convenient and extensible. Vogon also provides Quadriga users to download their remote workspaces into the local machine and upload a local workspace to the Quadriga server.

Vogon has been developed as an open-source software and the project is publicly available via SourceForge here. It consists of multiple eclipse plugins that function together in the final product resulting in the overall application. These plugins are loosely coupled and that facilitates independent development of the various features provided.

System Requirements (developer machine)

• A 32/64 bit Operating System (Suggested: MacOSX, Windows, Linux)
• Eclipse for RCP Developers
• At least 2 GB of free disk space

Components

• com.novocode.naf
• edu.asu.gmf
• edu.asu.vogon.annotation.ui
• edu.asu.vogon.check
• edu.asu.vogon.digitalHPS.diagram
• edu.asu.vogon.digitalHPS.model
• edu.asu.vogon.digitalHPS.model.edit
• edu.asu.vogon.editor
• edu.asu.vogon.filebrowser
• edu.asu.vogon.files
• edu.asu.vogon.graphical
• edu.asu.vogon.jersey
• edu.asu.vogon.keywords.tagger
• edu.asu.vogon.mapping
• edu.asu.vogon.model
• edu.asu.vogon.model.edit
• edu.asu.vogon.ontology
• edu.asu.vogon.ontology.ui
• edu.asu.vogon.ontotator
• edu.asu.vogon.quadriga
• edu.asu.vogon.quadriga.workspace
• edu.asu.vogon.resource.manager
• edu.asu.vogon.rest
• edu.asu.vogon.ui
• edu.asu.vogon.util
• edu.asu.vogon.viewer
• edu.asu.vogon.vocabulary
• edu.asu.vogon.vocabulary.ui

Deployment and Execution

The product file is present in the edu.asu.vogon.graphical plugin and it lists the required plugins for the application to function properly. As of now the file has been named vogon_new.product. This plugin also contains the splash screen image and some of the icons that are used in the application.

Once all the required plugins have been downloaded in the eclipse workspace, the developer can run the application by opening the product file and running it as an eclipse application. Make sure that you have first clicked on the “Add Required Plugins” button in the Dependencies tab, which automatically adds the platform specific eclipse plugins that are required into the product. Note that the product file committed to the Sourceforge repository may have a different set of dependencies listed than the machine on which you have downloaded the source code. Therefore adding the required dependencies manually is an important step for the developer to run the code on his machine.

If all goes well, then a splash screen should show up and ask the user to select the local workspace directory for Vogon. This workspace directory will contain all the application data such as texts, concepts, vocabularies, etc. In addition to the user data, the workspace also keeps the execution logs in a hidden folder “.metadata”.

In the next section we briefly describe the function of each required plugin. Note that the java code is extensively commented with javadocs and inline comments and the developer can look at the same for specific details.

edu.asu.gmf

This plugin contains the GMF (Graphical Modelling Framework) model files that have been designed to model the graphical user interface on top of the EMF data model. These include the following:

• My.gmfgraph
  This file models the diagram canvas and the actual figures that would represent specific data.
• My.gmftool
  Contains the tools for the palette in the diagram editor. All the creation tools that need to be shown in the palette are listed here.
• Theirs.gmfmap
  This file contains the mapping between each diagram figure listed in the gmfgraph file to the actual data model object that it represents.
• Theirs.gmfgen
  This is an auto generated file built from the gmfmap file and contains the data required to generate the java code for the model.

edu.asu.vogon.annotation.ui

This is one of the most important and widely used plugin in Vogon especially where functionality is concerned. It provides the logic and interface for creating appellations and relations and also provides views for the same. Below are some of the features provided by this plugin. These same features are also used by the GMF generated user interface in order create, update, delete the Appellations and Relations.

1. Appellations
   1. View
      The appellation view is provided by the class edu.asu.annotation.ui.view.AppellationView.java. This view shows the created appellations in the form of a list. It also provides various view actions that include creation, editing and deletion of appellations in the workspace.
   2. Creation
      The “Add New Appellation” action opens the AppellationWizard, that prompts the user to select the word from the text and assign it a normalization and interpretation. Each term part can also have its own normalization. The UI for this wizard is present in AppellationPage.java which is a combination of different SWT widgets. Once all the data in the wizard has been filled and is deemed to be correct, the AppellationWizard performs the finish operation and executes the required commands to create an AppellationEvent in the workspace for that particular text. The details of these operations can be found in AppellationWizard.java.
   3. Editing
      The “Edit Appellation” action opens the same wizard as “Add New Appellation” with the difference that now the wizard fields are already populated with the data of the selected appellation. The remaining process is similar to creation of a new appellation.
2. Relations
   1. View
      The relations view is provided by RelationsView.java class and it displays a list of already created relations for the particular text. It also provides the view actions for creating, editing and deleting the relation events which have been created.
   2. Creation
      The “Add New Relations” action opens a wizard that provides the user with dropdown menus to select the subject, predicate and object for the relation to be created. The predicte list consists of all the appellation events that have been created, while the subject and object lists consists of the appellation as well as relation events that have been created. After choosing the fields and pressing the “Finish” button, the required commands are generated and executed to store the new relation in the model.
   3. Editing
      The “Edit Relation” action opens the wizard with the fields pre-populated from the selected relation. It allows the user to change the subject, predicate, object fields and clicking on “Finish” will update the relation.
   4. Change Description
      This is an aesthetic feature that allows the user to toggle between a short and long description of the relation events in the list provided by the view. Sometimes the relation events can consist of multiple other relation events, and that can make the long (detailed) description unreadable. Clicking on this button will provide a shortened description that shows minimum detail and is easier to read.
   5. Delete
      The “Remove Relation” action deletes the selected relation event from the relation view list from the model.

edu.asu.vogon.digitalHPS.diagram

This plugin is automatically generated from the gmfgen file in the edu.asu.gmf plugin. It contains the java code required for the GMF user interface. These include:

• Model diagram editor
• Edit parts corresponding to model elements
• Commands for CRUD operations on the edit parts
• Elements and actions for the palette.

All the code used for creating and managing diagrams is present here. The auto generated classes have been edited to include project specific code in addition to that which is already generated by GMF. Some new elements have also been created to replace the default ones provided by GMF. The most important amongst them is the graphical viewer object for the diagram editor. A new graphical viewer has been created by the class VogonDiagramGraphicalViewer.java. The creation of a new viewer was necessary since we wanted our other components such as Appellation and Relation view to respond to selection events occurring in the diagram editor. Since we want full control over how each event is triggered and who responds to what event, we created the new viewer which has been tailored to work with the requirements of Vogon. The code for editing the diagram objects has also been modified. For example, if the subject link of a relation event is changed, the commands for editing the corresponding model object have to be generated and executed instead of using the setter methods. Similar techniques have been used for creation and deletion.

edu.asu.vogon.digitalHPS.model

This plugin contains the EMF model for the application and all the generated interfaces and classes that are to be used by other plugins for storing model data. It also contains the ecore and genmodel files which are used by EMF to generate the model classes for Vogon.

edu.asu.vogon.digitalHPS.model.edit

This plugin contains all the provider classes for the model objects defined in the edu.asu.vogon.digitalHPS.model plugin. These provider classes are used to define which properties of an object are to be displayed in the properties view, and what text should represent the model object. If you need to change the way the text is displayed in the Appellation or Relation or Properties views, then these provider classes corresponding to the model classes are the ones to be edited.

edu.asu.vogon.editor

This plugin consists of the base classes for the editor. It is mainly used by the Text editor component. It defines some classes that handle the data to be transferred during selection events. For example, if a word or phrase is selected in the text editor, then it is wrapped by WordStructuredSelection.java class that contains additional data about the position, length and other attributes of the selection. This wrapped object is then sent as notification to the listener classes.

edu.asu.vogon.filebrowser

This plugin contains the UI components and actions to be used by the File Browser view. This view is placed in the left side panel of Vogon by default. It displays the list of texts that have been imported into Vogon and double clicking on the file opens the diagram and text editors for it. The plugin provides a view named FileBrowserView and the actions for Opening a file and Deleting a file.

edu.asu.vogon.files

This plugin provides the factory classes for generating objects that represent the files for the text editor. Currently text and xhtml files are supported. It also defines classes that are used as wrappers for input to the corresponding text or xhtml editors in an identifiable format.

edu.asu.vogon.graphical

This is the plugin that puts all the plugins together into the final Vogon product. It contains the main product file named vogon_new.product that lists all the required plugins for the software. It also defines a few classes that contain the algorithms to be executed on product start up. These include selection of workspace, checking operations on selected workspace, design of the perspectives and application startup.

edu.asu.vogon.jersey

This plugin provides the jersey library for the REST client in Vogon. The jersey classes will be used by Vogon in other plugins to make REST web service calls to remote services to access concepts, vocabularies and also to upload and download workspaces with Quadriga.

edu.asu.vogon.model

This plugin contains some model files from the older version of Vogon that are still being used by some parts of the application.

edu.asu.vogon.model.edit

This plugin contains the item providers for the model files defined in the edu.asu.vogon.model plugin.

edu.asu.vogon.ontology

This plugin provides the factory and provider classes for Ontologies. They contain the logic for all the operations related to ontologies such as adding, deleting, updating etc. One of the most important interfaces is OntologyProvider.java with implementation OntologyProviderImpl.java and it provides a handle for other plugins to operate on ontologies.

edu.asu.vogon.ontology.ui

This plugin provides all the UI components required for Ontologies. These include the view, actions and wizards that enable the user to perform various operations on Ontologies. The view provides a tree viewer that lists the ontologies that have been created by the user for the workspace. Expanding each ontology would display the concepts that have been downloaded from that remote ontology into the workspace. It also provides the view actions to add new ontologies and menu actions to filter the concept list and to display all the concepts (in case the concept list has been filtered).

edu.asu.vogon.ontotator

This plugin provides the action for importing texts into Vogon workspace. The AnalyseTextActionDelegate opens the dialog that allows the user to import the texts and analyse them.

edu.asu.vogon.quadriga

This plugin provides the operations for Vogon to interact with Quadriga servers. These operations include using the jersey classes provided by the jersey plugin to implement the RESTful client and the interface to submit the annotations to Quadriga once they are completed.

edu.asu.vogon.quadriga.workspace

This plugin provides the code for uploading and downloading workspaces to Quadriga. It provides the UI components such as menu actions, wizards, etc as well as the business logic for doing the same. It creates its own REST client that interacts with the RESTful service provided by Quadriga for downloading and uploading workspace to and from Vogon. It involves converting the model objects into a format that is recognized by Quadriga and from the format to model objects. The format and parsers are borrowed from the QStore4S repository project.

edu.asu.vogon.resource.manager

Contains files that help to manage the resources being used in Vogon. Currently contains a handler for the files that have been loaded into Vogon called LoadedFilesHandler.java that can be used to perform some commonly used functions on the files. These functions include adding a text to the emf resource, adding ontology files, getting the lists of texts and/or ontologies, etc.

edu.asu.vogon.rest

This plugin basically provides the REST clients for the ontology and vocabulary services to connect to the remote ConceptPower and WordPower services respectively. These clients provide the interface to connect as well as download concepts and vocabularies from these servers into Vogon. The plugin also provides the XML parsers to convert the XML document received from the remote web services into a form recognizable by Vogon.

edu.asu.vogon.ui

This plugin provides some UI components to be used by other plugins. Firstly it provides the wizard dialog that is used when completed texts and annotations are to be uploaded to Quadriga. Secondly it provides an interface to be used in the text editor for getting the current text i.e. the text that is being displayed in the editor.

edu.asu.vogon.util

This is basically a utility plugin. It contains several helper classes that provide commonly used functions and methods for other plugins to use. These include files that define constants, helper classes for resources, exception handling services etc. Basically any class that is designed to be used by other plugins without any plugin-specific functionality needs to be a part of the util plugin.

edu.asu.vogon.viewer

This is one of the most important plugins from the user’s perspective. It contains the classes for the editors that would be used to annotate the text files. It contains the code for the editors (TextAnnotationEditor.java and XHTMLAnnotationEditor.java) as well as the other specialized classes that help in making the annotations. Any code or enhancement with respect to the editors has to be added into this plugin.

edu.asu.vogon.vocabulary

This plugin provides some classes, specific to the use of vocabularies in Vogon. It provides the provider class for the vocabulary objects and provides methods for common operations on vocabularies like addition, removal, update and listing of vocabularies in Vogon workspace. The plugin also contains some factories that help in establishing new vocabulary objects in the workspace.

edu.asu.vogon.vocabulary.ui

This plugin provides all the UI classes required for vocabularies in Vogon. These include the view (VocabularyView.java), the wizard for adding new vocabulary (ConnectVocabularyWizard.java), wizards and actions for adding words to a vocabulary, filtering the list of words, etc. Any code related to the user interface for vocabularies in Vogon needs to be placed inside this plugin.