Overview Sections:  Overview of Architecture*  |   Service Anatomy  |   Service Families  |   Accessing Application Variables

Detailed Architectures:  Core*  |   Validation  |   ID Generation  |   Ontologies  |   Meta Data  |   Functional Specs  |   Alerts  |   Plugins
* If you are looking at this documentation for the first time, we recommend you start here for each section.

Architecture for Ontologies

Ontologies can be used to help supplement information on forms or provide lists of options for completing forms.

Ontologies Architecture Diagram for Project35

Ontologies Scenario

  1. The trigger for this occurs when the user selects a record in the tree and the record view is made to visulaise that object. The record view interrogates each of the fields in the current record it is trying to visualise. Some of these fields are associated with a text field.
  2. For these cases the record view asks the Configuration Reader if there are any descritions of ontology services associated with these fields.
  3. Any descriptions that are returned by the Configuration Reader are instanciated as services via the factory.
  4. Those services are made available when an end user right clicks over the lable of the indicated form field.

Key Reference Sections

Form Generation System  |   Model Reader System  |   Configuration Reader  |   Ontology Services Factory

Each section is structured to address purpose, description, design considerations, scope of effect, and relevant code packages.

Ontologies as a Specialised Service

An ontology service allows end-users to mark up a form field with terms that come from a controlled list of terms. Although its scope of effect is a single form text field, it may use other information about the current form, the user or document to help constrain the choices of terms it provides to the viewer.

Reference Sections for Ontologies

Form Generation System

Purpose To generate UIs for Project35 which suite displays on desktop and Tablet PCs.


Project35's architecture maintains a rigid separation between the structures that hold data and structures that present them to an end-user. The model aspects are represented by the Native Data Structures, information for which can be found in the Core Architecture section. The view aspects are represented by the following packages: project35.desktopDeployment and project35.tabletDeployment.

General Classes for Generating Desktop Project35 Forms

When end-users invoke the "run_project35" script, it spawns an instance of Project35 Application. The object prompts end-users to load a model and it produces template record definitions that can be used to populate a document.

  • Project35Application creates an instance of an empty Project35Dialog, which is the main window for the data entry tool;
  • Project35Dialog has three major UI components: Project35MenuBar, NavigationTree, and RecordView;
  • Project35MenuBar containing a variety of menus subclassed from Project35Menu;
  • Project35Menu contains general-purpose code for handling plugins;
  • NavigationTree is the tree display that appears on the left part of the window. This manages a tree of NavigationTreeNode objects that mirror the tree of RecordModel objects, which comprise the document;
  • RecordView comprises a RecordViewTitle, which appears flushed left at the top of the panel, and a collection of DataFieldView objects, which render form fields;
  • DataFieldView objects all use a corresponding DataFieldModel object that is part of the currently selected RecordModel object.

General Class Relationship Diagram for Generating Desktop Project35 Forms

Classes for Generating Edit Fields in Desktop Project35 Forms

The image below describes a more detailed view of UI classes that are used to render text fields, identifier fields, combination box fields and radio fields. EditFieldView contains code which can render properties of a corresponding EditFieldModel object. It is responsible for rendering a "Plugins" button for any form field that has been associated with a collection of plugins. The other field view classes use properties defined in corresponding edit field model objects. RadioFieldView uses the choices provided by GroupFieldModel to render a group of radio buttons. If GroupFieldModel provides more than three choices, Project35 uses a CombinationFieldView to render the items as a drop-down list. URIFieldViews use TextFieldModel objects whose XML Schema definitions used "xs:anyType" for the type attribute (See EditFieldModel Properties). IDFieldView uses an instance of IDFieldModel to render a text field that is accompanied by a "Generate Key" button. The identifier service used to provide an identifier is a property of the IDFieldModel.

Class Relationship Diagram for Rendering Edit Fields in Desktop Project35

Classes for Generating List Fields in Desktop Project35 Forms

  • ListFieldView comprises a ListTypeManager, a ListValueManager and it uses an instance of ListFieldModel.
  • ListTypeManager manages the type of child record that will be created or edited when end-users press "New" or "Edit" buttons. There are implementations of ListTypeManager that accommodate lists that support one or multiple types.
  • MultiListTypeManager renders a combination box populated with the kinds of records that can appear in the list field.
  • ListValueManager is an abstract class that manages the display of list items.
  • SingleListValueManager represents a one item list as a single non-editable text field that shows the display name of the child record.
  • MultiListValueManager shows the child records in a scrollable list of record names.
  • project35.desktopDeployment.RecordViewFactory creates list fields. It determines the type of list field to produce by inspecting the fieldViewType attribute of the ListModel object.

Class Relationship Diagram for Rendering List Fields in Desktop Project35

Classes for Generating Forms in Tablet Project35

Tablet Project35 was designed to support the same data models as those used to run Desktop Project35. However, we envisioned that different forms of deployment would be used at different stages of editing the same document. End-users will tend to use Tablet Project35 to do simple data entry tasks which require them to be at a work site such as a laboratory or a remote field location. They will tend to use Desktop Project35 to support complex data entry tasks and to fill in the rest of the document.

Tablet Project35 was designed with the following principles in mind:

  • Minimise the feature set of the application to support essential tasks;
  • Minimise the use of pop-up dialogs;
  • Economise on screen real estate;
  • Change features which rely on right-menu clicks.

The classes used to generate forms in Tablet Project35 are in the project35.tabletDeployment package. Many of them share the same name as other classes that cater to supporting Desktop Project35. There are a few notable differences.

First, some of the menu items have been removed. For example, the File Menu does not contain an "Export to Final Submission Format" button. This feature was deemed non-essential because it was likely this would be done with the Desktop version.

To reduce the number of pop-up dialogs, some features were altered so they used a stack of screens instead of separate windows. For example, consider the "Window" feature in Desktop Project35. When end-users switch from one file to another, a new window grabs focus. In Tablet Project35, only one file is shown at a time. When end-users change the current file, it changes the file loaded in the current window.

As another example, the DefaultOntologyViewer was altered so it relied on JPanel objects instead of JDialog objects. This was done so the ontology viewer was more easily embedded in a stack of windows.

To economise on screen real estate, the NavigationTree was removed. It is accessible via the "Where Am I" button, which pushes a view of the NavigationTree onto the stack of windows. Tablet Project35 supports navigation via a RecordStack object. RecordStack is a drop down list that shows the currently edited branch of the tree.

Finally, the right click mechanism for activating ontology services is replaced by pressing a "Mark-up" button which appears at the end of a text field.

Design Considerations

Initially, Project35 tightly coupled data objects with the objects that viewed them. This led to severe performance problems because Java would potentially be managing thousands of UI components, each using a collection of Swing objects. This led to stripping the native data structures of references to UI components. Eventually the production of form field views was centralised in the class project35.desktopDeployment.RecordViewFactory.

The most significant change in the form generation classes came when Tablet Project35 was developed. Initially we wanted to run the software on a PDA. However, these devices often require a specialised form of the JVM which does not support Swing components. Although the native data structures were stripped of references to UI components, they still had one crucial reference to the swing libraries: the ChangeListener class. We realised it would not be easy to port the code base to a PDA platform so instead we decided on a Tablet PC platform.

It became clear that we had to make some changes to the forms. The NavigationTree was taking up too much room in the display and it was difficult to tap a pen on some of the nodes. Too many windows popped up and they cluttered the screen area. We also observed that it was difficult to activate ontology services. In the Tablet display, a right-click action is done by tapping and holding the pen on a form label. This seemed too awkward to do, so a "Mark up" button was developed instead.

The development of TabletProject35 took 3 consultation meetings with mass spectrometer scientist Jennifer Lynch and ten business days of coding. The result proved that Project35's design isolated its model aspects enough to develop new ways of visualising them.

Scope of Effect The UI classes are probably not used by anything other than classes in Desktop and Tablet deployment packages.

Relevant Code Packages The classes used to generate user interfaces in Project35 are in the project35.desktopDeployment and project35.tabletDeployment packages.

Back to top

Model Reader System

Purpose To coordinate the reading of the XML Schema and the Configuration File.

Description This system is a construct for classification of coding areas that are found within the project35.mda package.

Design Considerations We wanted a system that was capable of supporting a replacement of the Schema Reader. This can be accomplished by having the rest of the system interact with an abstract interface rather than a specific implementation something that interprets schemas. We needed a system that could extract information about data structures form the schema and another thing to extract information about form properties that were related to that schema. This system's role as a whole is to obtain enough information/properties to drive form generation.

Scope of Effect Nothing else uses this as it's an abstract concept but parts of it will be used in other places as in the Configuration Reader. The components of the Model Reader System are used to synthesise Native Data Structures that are then used by the rest of the program. Most of the rest of the programme will only use the Configuration Reader.

Relevant Code Packages project35.mda.schema, project35.mda.config, project35.mda.model (for more information on the last, see sections on Native Data Structures and Record Model Factory.

Back to top

Configuration Reader

Purpose To manage options for configuring a data entry application that are not expressed in the XML schema.


Project35 interprets the XML Schema to determine properties of the data entry application. However, many of the configuration options can’t be expressed in the XML Schema language, so they are managed in a ./[model]/config/ConfigurationFile.xml. This file maintains a collection of mappings that link schema concepts to different kinds of properties.

Data modellers use the Project35 Configuration Tool to produce the file "ConfigurationFile.xml", which describes all the application properties that are associated with XML Schema concepts. When the Project35 application starts, it reads the configuration file and holds the information in instances of data container classes. These classes have properties which are analagous to classes defined in the XML Schema for the Project35 Configuration Tool (See the XML schema for the Configuration Tool in .\models\project35_form_configuration\project35_form_configuration.xsd of the distribution).

Various parts of Project35 use the Project35 Configuration Reader to obtain configuration data that are used to render the application. For example, project35.desktopDeployment.TextFieldView uses the Project35 Configuration Reader to determine whether it should link an edit field defined in the domain schema to ontology services. In another case, Project35’s menu classes use the Project35 Configuration Reader to determine which standard menu items should be included for display.

Other Configuration Files

Project35 maintains two other configuration files in the config directory of a model folder: SessionAspects.xml and FileExtensionsToLaunch.xml

The SessionAspects.xml file contains information about the most recently accessed files, and is managed by the class project35.mda.config.SessionManager. Project35 uses a list of recently accessed files to create the "Favourites" sub-menu located in the File Menu. It also uses session information to set the default starting directory for when users open files.

The FileExtensionsToLaunch.xml file associates file extensions with shell commands used to launch other software applications. The mappings are used when users press the "View" button on a URL Field View. If the file specified in the text field ends with an recognised extension, Project35 will try to launch an application by making a system call.

It remains the only configuration file that end-users still have to configure. Currently, the SessionManager uses the class FileLauncher to parse the file of mappings. In future, this file will be eliminated in favour of having the same information represented as properties in the Project35 Configuration Tool.

Design Considerations

In early incarnations of the software, data modellers had to craft the ConfigurationFile.xml file by hand. The file was awkward and time-consuming to maintain, especially when large XML schemas were being used. This led to the idea of using Project35 to edit its own configuration files. The Project35 Configuration Tool was developed using a schema of configuration properties and a collection of plugins which helped data modellers fill in the forms.

The advent of the Project35 Configuration Tool meant that a configuration file could be designed far more rapidly than it could in previous releases. Enshrining configuration options in an XML Schema also meant it was easy to add new properties.

The configuration options for Project35 expanded to include the selective inclusion of menu items and services which could be associated with a field, record or document scope of effect. With new features came data container classes that held the property values in memory.

Scope of Effect

The Configuration Reader is referenced in the file menu classes to determine what features should be included. Many of the classes which generate form fields interact with the Project35ConfigurationReader via the SchemaConceptManager interface.

Relevant Code Packages Code for Project35ConfigurationReader and the data container classes can be found in the package project35.mda.config.

Back to top

Ontology Services Factory

Purpose Provide a system which allows end-users to mark-up form fields using terms from multiple ontology services.

Description The Project35 Ontology Service Framework manages ontology services which collect and render ontology terms for end-users in some kind of display. The Ontology Services Factory produces an instance of what what the Ontology Services Framework describes below.

Ontology Term

The basic unit of information handled by the services is the OntologyTerm, which comprises a label, a unique identifier, and a collection of related terms. All ontology terms can be represented by the OntologyTerm class and those which can be ordered as a tree of concepts can be represented by TreeOntologyTerm as well.

Ontology Term Data Structure

The label represents the word phrase that would be presented to an end-user in a display. The unique identifier represents the concept referred to by the term. For example, "cat" and "le chat" are word phrases for the same concept "cat". The concept could have an identifier such as "www.dictionary.org/cat_01". Humans will relate to the label whereas software agents that manage the ontology will relate to the unique identifier.

The collection of related terms does not refer to a specific type of relationship such as "has a", or "is a". The way to determine the kind of relationship of related terms is covered later in this section.

TreeOntologyTerm is a subclass of OntologyTerm which also has a notion of a parent term. It is used to support ontologies that are structured as a tree of concepts.

Ontology Provenance

Project35 uses OntologyTerm as a lightweight data container for holding information about ontology terms. However, when users select and use terms, Project35 attempts to find out more information about them. In the sections covering OntologySource and OntologyViewer, there are interface methods for getOntologyTermProvenance. These methods cause a source or viewer agent to return data that describes more details about a given ontology term. OntologyTermProvenance contains information described in the SKOS standard. Most of these details are probably only meant to be processed by software agents.

Project35 saves the meta data about selected ontology term in its *.META data layer. More information can be found in the sections on the I/O System and the Meta Data System. The provenance information is important in cases where an ontology term has been reclassified in the same ontology, or if a term has been deprecated.

Ontology Services

The Project35 Ontology Service Framework can associate one or more ontology services with a form field. An OntologyService will have at most one OntologySource and one OntologyViewer. It can have one, the other or both of these kinds of objects.

An Ontology Service Comprises at Most One Ontology source and One Ontology Viewer

An OntologySource is an agent that provides ontology terms to the system. It is an interface which is intended to hide implementation details of how terms are read from a storage medium. For example, the terms could be a list of words in a simple text file; a bunch of rows in a relational database table; or tag values in some XML-based file. The terms could also be managed locally or remotely. The interface is designed to shield the rest of the application from these data management details.

An OntologyViewer visualises ontology terms for end-users and is designed to accept OntologyTerm objects provided by an OntologySource. A viewer can present data in a number of ways such as a simple list, a table, a graph, an image map or a collection of images. Project35’s use of this interface allows it to be insulated from details of how terms are rendered for the end-users. The main purpose of the viewer is to provide the system with a collection of selected terms that can be inserted into a form field.

If a service has both a source and a viewer specified, then terms provided by the source are given to the viewer to render in some kind of display. If only a source is provided, then Project35 associates it with its own default ontology viewer. If only the viewer is provided, then Project35 assumes the agent will combine responsibilities of reading and presenting ontology terms.

The flexibility of mixing and matching source and viewer components is meant to make it easy to integrate legacy components. With this scheme, a developer can wrap the part of an application that parses terms; the part that views terms or both. The same application can be wrapped as a source and a viewer, allowing the same component to be marketable for use in other ontology services.

There are a couple of reasons why developers may want to wrap just a viewer. Sometimes the legacy application may not have a rigid separation between its model and view aspects. In this case, the source may somehow be tied to graphical objects even though its job does not include rendering activities. The viewer could require specialised parser routines that contain information which is non-compatible with the OntologyTerm objects provided by some other source.

Another reason is to allow the ontology viewer to take advantage of implementation details in the ontology source. A source hides most of its implementation details from an OntologyViewer. The viewer accesses information about the ontology via the methods in the interface used by the source. In some cases, developers may want to expose rather than hide certain formalisms. For example, an OWL-based ontology can support various logical arguments and can support a variety of complex relationships. It may be desirable for expert end-users to have more features in the viewer which take advantage of ontology terms as they are expressed in OWL rather than from the term objects provided by a source.

Ontology Source

The image below describes the OntologySource in detail, as well as showing some of the default ontology sources that come bundled with the application. Most of the methods in OntologySource take an argument Project35FormContext which is an instance of the class by the same name. Project35FormContext is a Hash Map that allows developers to reference parts of the Project35 application from within the service. It is described in more detail in the Contexts section of the Architectute Overview. The table below describes the major methods of the OntologySource interface:

Method Description
isWorking A diagnostic method used by Project35 to determine whether a source is fit to use or not. The most likely causes of a failure in the source is that it can’t find some resource file it’s looking for or it can’t connect to the Internet. The result of this method can determine whether an ontology service is listed for the end-user to use.

getOntologyTermProvenance The way the source provides provenance data for a given ontology term. This method is called when users decide to select a term in the viewer. The viewer attempts to capture all the information about the term so it can be included in Project35’s meta data file.

containsTerm Designed to let the OntologySource be used in other contexts such as search and retrieval services. The idea is that the same source can be used to tag a field with a term and to perform a lookup operation to check that the term is part of its ontology.

getTerms Returns a collection of ontology terms. This is used by viewers to render an ontology as a list. getSubOntologySource this is used to return an ontology which represents part of a larger one. For example, consider an ontology which is a very large taxonomy file of animal species. The same taxonomy could be used in a number of data forms but only a branch of the taxonomy is needed for any given form field. The parameters of the method could include anchor terms which help intialise the starting point of an ontology for a given field.

getSupportedRelationships An ontology could support multiple ways of relating terms to one another. This method returns the list of relationship types used by the ontology. getRelatedTerms given an ontology term and the name of a supported relationship type, this method returns a collection of related terms.

getOntologyServiceMetaData This is basic meta data information about the service that includes:
  • Name;
  • Author;
  • Description;
  • Version;
  • What formalisms are supported;
  • A contact email;
  • A unique code that identifies the software agent.

This method is principally called by OntologyService. By default the service calls the same method in its viewer. If the viewer isn't present or if the viewer defers answering the request to its source, then this method is called.

TreeOntologySource extends the OntologySource interface with a simple method for getting the root of a tree of ontology terms. Most of Project35’s default ontology sources rely on ontologies that can be represented as trees.

Default Ontology Sources Supported in Project35

Ontology Viewer

OntologyViewer replicates many methods of OntologySource because the viewer may elect to delegate to its source for certain method calls. There are two distinguishing methods of the viewer interface as shown in the image below. getSelectedOntologyTerms returns the collection of terms the end-user has selected in the viewer display. setOntologyTermSelectionListener notifies a component when the users have indicated in the viewer they want to use selected terms for marking up a form field.

The Ontology Viewer Interface

Default Viewer’s Use of Introspection on Ontology Sources

In most cases, data modellers will create ontology services that use the tool’s default ontology viewer. Although the OntologySource API provides access to terms, the source provides little information about how to render terms. Its getTerms(...) method allows all ontologies to be rendered as lists. However, to find out more rendering hints, the DefaultOntologyViewer applies Java reflection to the class which implements OntologySource. The viewer tries to determine what other ontology interfaces the class might implement. The image below shows the viewer interrogating MyOntologySource, a class that implements the OntologySource interface. Project35’s Default Ontology Viewer introspects ontology sources to determine what other interfaces the ontology source classes support.

Marker Interfaces Used by Ontology Sources to Provide Rendering Tips

MyOntologySource also implements TreeOntologySource, which means the viewer can present the ontology as either a list or as a tree. DictionaryDescriptionSupport is an interface which indicates that most ontology terms will have both a label and a text definition. This assumption allows the viewer to produce a "Dictionary View", a table with fields for term and definition. URLDescriptionSupport indicates that most ontology terms will be associated with a web page. This assumption causes the viewer to render an HTML pane to show the web page. The ImageDescriptionSupport carries an assumption that most terms will be associated with an image. This allows the viewer to produce a view of thumbnail images. OntologyCaching indicates the ontology source can be updated. The interface has two methods: one to determine whether the source is outdated and another method which causes the source to update itself. The default viewer responds to the presence of the OntologyCaching interface by rendering an "Update" button if the ontology is out of date.

The OntologyContext

Ontology services can ask Project35 questions about what else is on the current form. The OntologyContext object retains knowledge about the currently selected field, the field which invoked an ontology service, the parent record of the current form record and the field values that appear on the form.

An ontology source or ontology viewer can access this object through the following call:

OntologyContext ontologyContext
= (OntologyContext) project35FormContext.getProperty(Project35FormContext.ONTOLOGY_CONTEXT);

Developers can use the OntologyContext object to help reduce the amount of terms that are presented to the user.

A Walkthrough for Selecting an Ontology Term

The process of marking up a form field with a term begins with the end-user right clicking over a starred form field label. In the desktop application, the label will belong to project35.desktopDeployment.TextFieldView. That label will be associated with the TextFieldView’s instance of OntologyServiceManager. This class manages the task of presenting a right click menu and inserting terms into the text component of the form field.

The OntologyServiceManager listens to the right click action on the form label and generates a popup menu. It will add a menu item for each ontology service registered for the field. If the form field does not allow free-text entry, then a "Clear" menu button is added to the popup menu.

In createMenuItemForService(...), Project35 works out what to do in cases where a service has only an OntologySource, only an OntologyViewer or both. When an ontology has less than 20 menu items, the OntologyServiceManager tries to render terms as menu items. When there there are between 21 and 40 terms, the manager object tries to render submenus. For larger ontologies, it simply makes a menu button that can cause the ontology viewer to pop up.

When the user chooses a service from the menu, the OntologyServiceManager creates a DefaultOntologyTermSelectionListener to listen for when the end-user uses terms selected in the ontology viewer.

The OntologyViewer allows the end-user to select terms in some kind of display. The viewer will have some button which will indicate that the user wants to insert selected terms into the form field. This is when the OntologyViewer notifies the DefaultOntologyTermSelectionListener. The DefaultOntologyTermSelectionListener asks the OntologyViewer to supply it with the selected terms. It then asks OntologyViewer to provide an OntologyTermProvenance object for each selected OntologyTerm. The OntologyTermProvenance objects are added to the OntologyContext object which keeps track of what terms have been used in the current form. The OntologyContext in turn submits the OntologyTermProvenance objects to the OntologyTermProvenanceManager, which retains knowledge about all ontology terms used to tag the data set. The DefaultOntologyTermSelectionListener also inserts the label for each selected term into the form text field.

When the end-user saves the data set to a native format *.PDZ file, the OntologyTermProvenance objects held in the OntologyTermProvenanceManager are written to the *.META file. This is how Project35 stores information about the ontology terms used to mark-up form fields.

Design Considerations

A number of requirements for ontology services were identified early in the development of the software:

  1. The data entry XML schema and the mark-up services will evolve autonomously at different rates. Therefore, these things should be decoupled and supported through separate mechanisms. As a consequence, we should not expect the XML schema to contain declarations of field values as well as the names of form fields;
  2. The framework should be able to associate multiple ontology services with the same field and multiple fields with the same ontology;
  3. The framework should be able to support simple "stub ontologies" which are used during rapid prototyping activities. The ontologies should be simple lists of terms that can be presented to prospective end-users for feedback and evaluation;
  4. Support multiple technologies for managing ontology terms. Do not tie the architecture to one specific language for expressing ontology terms (eg: OWL). This is because different projects may use different ways of maintaining terms based on factors such as: legacy system features, in-house technology biases, the sophistication of the ontology and the skill level of the people who create the ontologies;
  5. Let each ontology service comprise one or both an OntologySource and an OntologyViewer. Each of these objects is described by an interface. An OntologySource provides terms and is designed on behalf of those who maintain ontologies. An OntologyViewer renders terms provided by the OntologySource, and is designed on behalf of those who use ontologies. The ontology service may be configured to mix and match an OntologySource with an OntologyViewer;
  6. Make the design of an OntologySource consider whether terms are maintained locally or remotely.
  7. The framework should provide some way of determining whether an OntologySource needs to be updated. End-users should be able to decide whether the ontology service updates itself.
  8. Require ontology services to provide meta data information about the ontologies. This information should include the name, author, version, description and kind of formalism supported by an ontology.

Scope of Effect

The Project35 Ontology Services Framework (POSF) is used in all of the Project35 tools created thus far including the desktop Project35 application, the Tablet Project35 application, the Project35 Configuration Tool, and the Project35 Meta Data Editor.

Within the Project35 code base, POSF features are referenced in project35.desktopDeployment.TextFieldView and Project35.tabletDeployment.TextFieldView.

Relevant Code Packages

The packages relevant to POSF include:

  • project35.soa.ontology.sources
  • project35.soa.ontology.views
  • project35.soa.ontology.provenance

The schema for ontology services is defined in the ./models/project35_form_configuration/model/project35_form_configuration.xsd file. The meta data retained for each ontology term is defined in ./models/Project35_meta_data/model/Project35MetaData.xsd file.

Back to top