General

Download

Overview
Project History
People

Use Cases Scenarios
Use Case Requirements
Bugs and Known Limitations
LHA

User Manuals Getting Started
General Tour
Configuration Options
Logging Tool Tour
Administration Tool Tour

Developers Architecture
Analysis of Design
Creating Plugins
Future Enhancements

Architecture Walkthroughs

Launching the logging tool

  1. The user double clicks on the file "run_logging_tool.bat" in the release directory. The main() routine of LoggingToolApplication will run.
  2. StartupOptions will read a configuration file that is specified by the end-user. StartupOptions initialises an instance of SessionProperties, which holds references to a number of application components that are needed by various parts of the code.
  3. StartupOptions uses an instance of ConfigurationManager to read the configuration file specified by the end-user.
  4. The ConfigurationManager will create the instance of TrialSubjectModelFactory which is used to create new instances of subject and activity records.
  5. At the end of LoggingToolApplication.main(), LoggingToolApplication calls its run() method. The run method creates an instance of ProductionLoggingService , which manages a MySQL database.
  6. An instance of LoggingToolDialog is created and launched; this is the class which manages the main dialog for the Logging Tool.

Launching the demonstration suite

The demonstration suite is used to create instances of the Administration Tool and Logging Tool which interact with a shared in-memory database. The database simulates aspects of persistence storage, but only lasts for as long as the demonstration suite is running. This section describes in greater detail how the demonstration versions of tools are created.
  1. Users double click on the "run_demo.bat" file which appears in the release directory. The batch file invokes the main() method of DemonstrationToolSuite.
  2. StartupOptions reads the properties file, creates a record factory for making new records ( TrialSubjectModelFactory) and initialises application objects in a SessionProperties object.
  3. DemonstrationToolSuite.main() invokes its run() method.
  4. The run() method sets the flag SessionProperties.DEMO_MODE to true. This flag lets the tools know whether they should indicate to the users that they are using demonstration versions of the services. In demonstration mode, the dialogs are specially coloured and the title of the tools starts with [DEMO].
  5. Next, the run() method sets the flag SessionProperties.IS_COMPONENT_MODE to true. This will later help instances of the Administration Tool and Logging Tool know they are being deployed as components from the demonstration suite tool, and not from command-line. For example, when users click the "Exit" button of the Database menu in the Logging Tool, the exit will just hide the Logging Tool dialog rather than call System.exit(0).
  6. An instance of DemonstrationLoggingService and DemonstrationAdminService are created. These two demonstration services will share the same instance of DemonstrationDB.
  7. The run() method of DemonstrationToolSuite creates and launches an instance of DemonstrationLauncherEditor, which lets users launch instances of the Administration Tool and Logging Tool.

Importing trial subject data

  1. The administrator user presses the "Import Subject Attribute Data..." button in the Administration Tool.
  2. AdministrationToolDialog. listens for the button press, then uses an ImportTrialSubjectDataUsingWizards object to guide the end-user through the process of importing subject records.
  3. Most of the process is described by steps in the importCoreData method of the wizard class.
  4. DataSelectionEditor lets the user choose an import file.
  5. FindFirstLineDialog lets the user identify the first line of input in the tab-delimited text file.
  6. PreviewSpreadsheetImportEditor lets the user associate columns from the text-file with the identifier and attributes that appear in a TrialSubjectModel.
  7. Thus far, the import file has only been analysed. The previous steps identified the first row of input and mappings between columns in the text files and properties in TrialSubjectModel objects. ImportTrialSubjectDataUsingWizards uses an instance of TrialSubjectDataSpreadsheetParsingEngine to validate and then import subject records into the data repository.
  8. TrialSubjectDataSpreadsheetParsingEngine uses a two-pass approach for importing data. First it reads the entire file and attempts to validate the records. If no errors are generated, the parsing engine reads the file again to import all the records.
  9. During the validation step, the engine makes use of two classes: TrialSubjectDataHeaderParser and TrialSubjectDataSpreadsheetBodyParser. TrialSubjectDataHeaderParser checks for duplicate header values or columns which don't map to a subject attribute. It also checks to make sure that some column has been mapped to the primary key field.
  10. TrialSubjectDataSpreadsheetBodyParser checks for duplicate subject identifiers.
  11. If no errors are detected, then TrialSubjectDataSpreadsheetBodyParser calls the importTrialSubjectModels(...) method of the LoggingServiceAPI.
  12. If any error is detected, ImportTrialSubjectDataUsingWizards produces an error report.

Exporting trial subject data

  1. The administrator user clicks on the "Export Subject Attribute Data" button in the Administration Tool.
  2. AdministrationToolDialog listens for the button click and then calls TransferTrialSubjectData to carry out the export operation. TransferTrialSubjectData is a legacy class which used to manage both import and export duties. However, I eventually encountered some performance problems with the import routines. Most of the classes which appear in cst.adminTool.io are a result of reworking the subject data import feature. I reduced the responsibility of TransferTrialSubjectData and in future I will probably rename it as cst.adminTool.io.ExportTrialSubjectData
  3. TransferTrialSubjectData calls the getSubjectAttributeData(...) method of AdminServiceAPI. This method returns a collection of TrialSubjectModel records which have been stripped of TrialActivityModel objects. Each TrialSubjectModel only contains a primary key field and subject attribute fields, all of which are instances of TextFieldModel.
  4. TransferTrialSubjectData calls a number of routines which serialise the records in a tab-delimited file.

Recording change history

This walkthrough assumes that the Logging Tool is using a ProductionLoggingService, which manages a MySQL database.
  1. Users adjust some date field value for an activity. A date field is managed by three JSpinner objects which separately manage day, month and year components. Each spinner has the DateFieldView as a change listener. When users adjust a spinner, DateFieldView calls its stateChanged(...) method.
  2. The DateFieldView registers itself as a changed field with SaveChangesMonitor.
  3. When users try to change focus to some other record or try to quit the application, the SaveChangesMonitor is asked if there are any changes that need to be saved by the user.
  4. If the user elects to save changes, SaveChangesMonitor asks each registered field to provide a TrialActivityChange. These are held while the monitor prompts the TrialActivityView to commit the contents of the form to the data repository. If the operation succeeds, the monitor calls the updateChangeHistory(...) method of the LoggingServiceAPI.
    5. TrialActivityChange objects are serialised in a change history table which has fields for the date, type, author and description of the change made.

Viewing change history

This walkthrough assumes that the Logging Tool is using a production logging service that manages a MySQL database.
  1. User presses the "History of changes for current case study..." button in the Options menu of the Logging Tool. Note that 'case study' could be something else such as 'mouse', 'volunteer' or whatever singular subject name is specified in the configuration file.
  2. OptionsMenu detects the event and asks the NavigationManager object for a reference to the currently displayed TrialActivityModel.
  3. OptionMenu uses the primary identifier key for the current TrialActivityModel record to obtain a list of relevant TrialActivityChanges from the LoggingServiceAPI object.
  4. The LoggingServiceAPI is implemented by an instance of ProductionLoggingService. The getTrialActivityChangesForSubject(...) method makes a delegation call to a method of ProductionLoggingToolQueries with the same name. ProductionLoggingToolQueries is the class which applies SQL queries to the database and retrieves results for logging tool operations.
  5. The results returned for the SQL query are packaged into instances of TrialActivityChange. The ProductionLoggingService returns the results to OptionsMenu.
  6. OptionsMenu passes the collection of TrialActivityChange to a ShowActivityChangeHistoryDialog object.
  7. The method generateChangesForSubjectReport(...) of ShowActivityChangeHistoryDialog uses a ChangeHistoryReport object to generate an HTML report. The report then appears in the dialog display.

Author: Kevin Garwood

(c)2010 Medical Research Council. Licensed under Apache 2.0.