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 ID Generation

ID Generation can provide identifiers for fields in forms.


ID Generation Architecture Diagram for Project35


ID Generation Scenario

  1. Users select a record in the record tree. That record is then represented in the record view.
  2. As the record view begins to interrogate the record object and goes through all its fields, it will ask each field if it's an attribute field.
  3. If the answer is yes, then it associates that model field with a view component that can support the insertion of generated ids. This view component contains a button that will be visible to users on the form.
  4. When you press this button, a machine readable identifier value (not necessarily readable for humans) is created and inserted into the form field.
  5. The record view tries to determine whether a description for that service exists by asking the Configuration Reader if it has a descrption of that service.
  6. If the Configuration Reader has a description, then the ID Generation Service Factory uses that to create an instance of that service for use by the Form Generation System.
  7. If the Configuration Reader does not have a description then the factory creates a default service for the form generation system.


Key Reference Sections

Form Generation System  |   Model Reader System  |   Configuration Reader  |   ID Generator Services Factory

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


ID Generation as a Specialised Service

This service generates a unique key value for a form text field. Whereas ontology services help provide values that carry semantic significance, ID generator services simply provide keys to uniquely identify a record with respect to other records in the same document or perhaps even records within other documents.

For example, they could be used to uniquely tag samples in an experiment. Implementations of the ID Generator Service interface could provide a key that did not already appear in a database or records.


Reference Sections for ID Generation

Form Generation System

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


Description

Project35's architecture maintains a rigid separation between the structures that hold data and the 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 which 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 supporitg a replacement of the Schema Reader and it tends to communicate with the Schema Reader via an interface. This system doesn't depend upon a specific implementation of the Schema Reader. 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.


Description

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


ID Generator Services Factory

Purpose To provide an identifier that can be used to populate an identifier field.


Description

The ID Generator Service interface extends ServiceClass in the same way that OntologySource, OntologyViewer, DocumentValidationService, RecordValidationService and other service classes do.

ID Generator Service Interface

IDGeneratorService has two main methods. The generateKey(...) method is used to generate a String value that Project35 inserts into the attribute form field. excludeKey(...) is used when a data file is read. ID values found in existing records are excluded so that the generateKey(...) doesnít produce a key which already exists in the data set.



Design Considerations Many of the use cases in bioinformatics use identifiers to uniquely label experiment records. For example, if a data set describes a number of samples, they would each get a unique identifier so they could be processed better by analysis programs. Unlike ontology services, identifiers donít have a semantic value. However, identifiers may have naming conventions which use domain-specific phrasing. For example, a unique identifier for a sample might include the name of the laboratory where the work was done. Project35 needed some kind of service which could generate unique keys. This was the incentive for developing the IDGeneratorService interface.


Scope of Effect ID Generator services are only ever used for attribute fields.


Relevant Code Packages IDGeneratorService is defined in the package project35.soa.id. It will appear in project35.desktopDeployment.IDFieldView. The class name for an IDGeneratorService will be stored in project35.mda.config.AttributeFieldConfiguration.

Back to top