Architecture for Functional Specs

Functional specifications are useful to explain to users what the system is meant to do.

Functional Spec Architecture Diagram for Project35

Functional Spec Scenario

1. The trigger for this feature is a "Generate functional specification" menu button that appears in the Configuration Tool.
2. The functional spec uses information in the Configuration Reader to describe general properties of the generated application. It also asks the Record Model Factory for all of its templates of records (native data structures).
3. It goes through each of these templates and does a look up on each field for additional properties that may be registered or defined in the Configuration Reader. Through this process, the Functional Specification System describes the functionality of record forms that are supported in the various applications.
4. The file is serialised as an HTML file.
   
   

Key Reference Sections

Model Reader System  |   Native Data Structures  |   Record Model Factory  |   Functional Specification System

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

Reference Sections for Functional Spec

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 from 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 case of 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

Native Data Structures

Purpose	The native data structures are an in-memory representation of an XML data set.
Description	The basic native data structure in Project35 is the RecordModel class, which comprises a number of DataFieldModel objects. The image below shows the different kinds of data fields that can be created: Inheritance Hierarchy for Data Field Classes Supported in Project35 All fields will have properties such as: A field name; A help link for a URL; Whether the field is required or optional; The kind of field view type (eg: "RADIO_FIELD", "DATE_FIELD" etc); Whether the field is an attribute or not (this probably belongs in EditFieldModel class); Text to appear when an end-user hovers over the field label. The two kinds of fields are EditFieldModel which manage a single value and ListFieldModel which contain one or more RecordModel objects. EditFieldModels will have: A value represented as a string; A default value that should appear when forms are rendered with a new record model object; Whether the field value should be included as part of the display name that represents the containing record. ListFieldModel objects will know what kinds of record models they can contain and will have a collection of children RecordModel objects. There are four kinds of EditFieldModel subclasses, although they have few extra properties. A GroupFieldModel is a kind of EditFieldModel where end-users select a value from a list. Its subclass BooleanFieldModel constrains this list of choices for "true" and "false". TextFieldModel is a marker class for identifying fields that can be associated with ontology services or id generation services. An IDFieldModel is a kind of TextFieldModel which also has an IDGeneratorService. This service creates an identifier value that can be inserted into the form field. An IDFieldModel is the data container object that corresponds to an attribute field in XML Schema. A RecordModel is a collection of DataFieldModel objects. The image below shows how the RecordModelFactory, RecordModel, EditFieldModel and ListFieldModel classes relate: Aggregation Relationships for Project35 Native Data Structures A RecordModel will contain a collection of EditFieldModel objects and a collection of ListFieldModel objects. Each ListFieldModel can contain multiple RecordModels. When the SchemaReader is operating, it adds RecordModel instances to the RecordModelFactory. The instances act as templates that can be cloned whenever a new record model is needed for a data set. The most popular utility class in the project35.mda.model package is RecordModelUtility. It has a number of methods to help group fields in different ways. There is a strong relationship between properties of the XML schema and properties of the native data structures. The following tables list the attributes of native data structures that should be set with values derived from a schema: RecordModel Properties DataFieldModel Properties EditFieldModel Properties IDFieldModel Properties GroupFieldModel Properties BooleanFieldModel Properties ListFieldModel Properties RecordModel Properties Property record_class_name Description The name of the record. Provider <xs:element name="[record_class_name]"> <xs:complexType> <xs:sequence>... </xs:sequence> </xs:element> Property helpLink Description The URL for a web page that describes the form concept. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property ontology_identifier Description A unique identifier that can be associated with a schema concept. This is useful if ontology services want to use a schema concept's ontology identifier to help limit what values are presented to the end-users. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property form_comments Description Comments that appear on the form and describe the schema concept. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property tool_tip Description Text that appears when end-users let their mouse cursor hover over a field label. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property record validation services Description Collection of descriptions of record-level validation services. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Back to properties list DataFieldModel Properties Property name Description Name of the field. Provider XML Schema Reader: <xs:element name="[name]" .../> for edit fields; XML Schema Reader: <xs:element ref="[name]" .../> or <xs:group ref="[name]".../> for list fields.Note that for list fields, the name is the record class name of another record structure or the name of a group of record class names. Property isRequired Description Determines whether a field is optional or required. Provider <...minOccurs="0".../> means the field is optional. <...minOccurs="1".../> means the field is required. Property helpLink Description The URL for a web page that describes the form concept. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property fieldViewType Description Gives an indicator of how the field should be rendered. Provider type="xs:string" indicates the field type is TEXT_FIELD. type="xs:date" indicates the field type is DATE_FIELD. The field label will be followed by the date format pattern enclosed in parentheses. If a field has at most three restriction values, the field type will be a RADIO_FIELD. The field will be rendered with radio buttons. If there are more than three restriction values, the field type will be COMBINATION_FIELD. The field will be rendered with a dropdown list of choices. type="xs:anyURI" indicates the field type is URI_FIELD. The field will be rendered with a browse button that allows end-users to search for a file. <xs:attribute.../> indicates the field type will be an ID_FIELD. In the main Project35 form, attribute fields are shown first, followed by all the other fields. An ID_FIELD will also have a "Generate Key" button that users can press to generate an identifier value; <xs:element ref=".."...maxOccurs="1"../> indicates a field will be ONE_TYPE_ONE_VALUE_LIST. This form field will have a desensitised text field and have a "New" and "Edit" buttons; <xs:element ref=".." ... maxOccurs="unbounded"../> indicates a field will be ONE_TYPE_N_VALUE_LIST. This form field will have a scrollable list showing display names of sub-records. It will also have "New", "Edit" and "Delete" buttons; <xs:group ref=".."...maxOccurs="1"../> indicates a field will be a N_TYPE_ONE_VALUE_LIST. The form field will have a desensitised text field and a combination box that lets the user choose which type of record to create; <xs:group ref=".." ...maxOccurs="unbounded"../> indicates a N_TYPE_N_VALUE_LIST field view type. The form field will have a scrollable list showing display names of sub-records. It will also have a combination box that lets the user choose which type of record to create. When users select a type of record, the list filters to show records of that type. Property ontology_identifier Description A unique identifier that can be associated with a schema concept. This is useful if ontology services want to use a schema concept's ontology identifier to help limit what values are presented to the end-users. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property form_comments Description Comments that appear on the form and describe the schema concept. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property tool_tip Description Text that appears when end-users let their mouse cursor hover over a field label. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Back to properties list EditFieldModel Properties Property defaultValue Description The default value that should be displayed whenever a new record containing this field is displayed. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property allowFreeText Description Determines whether a text field entry can accept free-text entries; this is not applicable for fields that have drop-down lists or radio buttons. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property scrollingTextField Description Determines whether a text field is displayed with one line of text or a scrolling text area. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property editFieldValidationServices Description Validation services that can be applied to the value held by the edit field model. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property isDisplayNameComponent Description Determines whether the field is used to derive the name of the containing record. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property units Description The units associated with a field; typically only of use for numeric fields. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property fieldValidationServiceConfiguration Description A collection of descriptions of field validation services. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property ontologyServiceConfigurations Description A collection of descriptions of ontology service descriptions; this is only applicable to text fields. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property editingComponentClassName Description The class name of an editing component; this should desensitise the part of the form field that holds a value. Instead, users click on "Edit" to invoke a separate editing component. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Back to properties list IDFieldModel Properties Property idGeneratorService Description Generates an identifier value that Project35 inserts into the text field whenever the "Generate Key" button is pressed. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Back to properties list GroupFieldModel Property choices Description The choices provided in a drop down list. Provider XML Schema Reader: <xs:restriction base="xs:string"> <xs:enumerationvalue="value2"/> </xs:restriction> Back to properties list BooleanFieldModel Property choices Description The choices provided in a drop down list. Provider XML Schema Reader: type="xs:boolean" BooleanFieldModel, a subclass of GroupFieldModel, forces the choices to be "true" and "false". Back to properties list ListFieldModel Properties Property fieldValidationServiceConfigurations Description A collection of list field validation services. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Property listFieldEditingComponentConfigurations Description A collection of descriptions of components that can create or edit different kinds of records in a list field. Provider Described in Project35 Configuration Tool; See project35.mda.config.SchemaConceptConfiguration. Back to properties list
Design Considerations	During the early development of the code base, there was a great temptation to make the application hold all its data in DOM objects. This was because the main I/O routines were written using the DOM parser and the result of the activity was a complete in-memory tree of DOM objects. There could have been some benefit in having Project35 rely on a generic data structure that was used in other projects. However, the DOM object model had shortcomings. The generic data objects had generic means of accessing and changing data. The task of finding specific fields within a record was cumbersome and required a great deal of looping constructs. The cumbersome nature of the DOM API led me to develop a collection of native data structures that could hold better cater for operations supported by the application. This proved to be a good decision because the application later failed to perform satisfactorily when it loaded large data files. Performance improved dramatically when the file reading routines switched from using the DOM to SAX parser. The SAX parser did not produce DOM objects, so it would have not made sense for the rest of the code base to depend on the generic data structures. Initially the native data structures held information about both the model and view aspects of records and fields. This later caused severe performance problems because Swing-based field views were created for each field whether they were being viewed or not. The structures were later reworked in a way that rigidly separated model and view aspects. View components were only ever generated for fields in the currently displayed record. The next problem with the native data structures related to serialisation. The copy and paste feature in the application required that all objects and the objects they referenced are serialisable. This worked well until serialisation encountered things like ValidationService and OntologyService objects. These were interfaces that could be implemented as Java classes that themselves were not serialisable. Eventually, native data structures were stripped of most of references to services so that serialisation had fewer dependencies. The only remaining service that exists as an artefact is the way EditFieldModel references validation services. This legacy feature will be eliminated when the schema reader is improved. In the revised approach, the form generation facility would receive a form field, look up properties in the configuration reader, and instantiate services when the fields were actually displayed on the screen. Still, many of the native data structures had too much code. Many of them such as RecordModel had a number of utility methods which did things like identify different groups of fields. This functionality was migrated to a new class called RecordModelUtility. The result is that the data structures now hold mostly data and not information about views and services. The exception is how DataFieldModel knows about a FieldViewType. This type is something that is determined by the schema reader, and is used to encode rendering hints into the model object. For example, the schema reader can tell whether a list field can support one or multiple types of sub-records. It marks the model object with field view types such as "ONE_TYPE_ONE_VALUE_LIST", and "N_TYPE_ONE_VALUE_LIST". Project35's project35.desktopDeployment.FieldViewFactory uses this field type value to determine what kind of form field to create for visualising the field data.
Scope of Effect	Project35's native data structures are used ubiquitously in all tools in the Project35 suite.
Relevant Code Packages	All of the model classes are defined in the project35.mda.model package.

Back to top

Record Model Factory

Purpose	To create instances of template records that have been defined by the Model Reader System.
Description	The Record Model Factory is used to instantiate instances of template records which have been defined by the Model Reader System. The instances are used for two purposes. First, the instances can be used to hold form data created by an end-user. Second, different parts of the application, such as the Form Generation System, can interrogate them to determine application properties associated with concepts defined in the XML schema.
Design Considerations	Early in the development of the software, there was a need to centralise the creation of container objects used to hold form data.
Scope of Effect	The Record Model Factory is used throughout the code base, both to create new records and to inspect the properties of template data structures that have been synthesised by the Model Reader System.
Relevant Code Packages	The Record Model Factory is a single class project35.mda.model.RecordModelFactory.

Back to top

Functional Specification System

Purpose	To generate human-readable functional specifications based on information contained in the XML Schema and the Configuration File for a data entry tool.
Description	This system generates a functional specification based on the current state of the XML schema and configuration file options associated with a given data entry tool. Application designers may generate functional specifications during any time they edit a configuration file for their model. The feature is intended to help Project35 support a rapid prototyping activity which can let non-technical project leaders better understand the features that are supposed to be supported by a data entry tool. The specifications can be used to inform the specifications of the final data entry tool product, whether that tool is generated by Project35 or developed from scratch. The package uses two main sources of information to produce the specification: Template record definitions that are managed by project35.mda.model.RecordModelFactory; Configuration options that are managed by project35.mda.config.Project35ConfigurationReader. Project35 interrogates the RecordModel templates that are managed by RecordModelFactory. The templates hold most of the properties of forms that are described in the XML Schema. For example, a template can be used to determine whether the "post_code" field of a form "address" is a String and whether it is optional or required. However, there are some properties of records and fields which are not described by the templates. Over the years, the software evolved so that definitions of services associated with forms (eg: ontology services, validation services, etc) were managed through a look-up mechanism in Project35ConfigurationReader. Extending the previous example, form "address" and field "post_code" could be used to determine whether a controlled vocabulary service was associated with the field "post_code". The description of such a service could be included in the generated functional specification. Project35ConfigurationReader also holds information about other application properties including: Descriptions of menu plugins; Descriptions of document-wide validation services; The colours used to paint parts of generated forms; The dialog title used to label each data entry window; The style sheet that is associated with XML data sets whose structure is defined by the XML schema; A list of schemas that are compatible with the XML Schema. The last property determines which data sets the generated data entry tool can import. Each data set that is produced by Project35 is stamped with a schema. If the schema stamp matches the schema being used to generate the data entry forms, the tool will be able to load that data set. Otherwise, the tool will indicate to the user that the schema used to create the data set doesn't match the schema being used by the data entry tool. In many modelling efforts, a schema may contain definitions of records which themselves are imported from a smaller schema. For example, consider a data entry tool that is generated from a large complex schema describing a patient record. One of the record forms defined for the model may describe laboratory results. The definition of record fields for a laboratory result may be managed by some standards committee that specifically focus on laboratory results. If the patient record model subsumes the smaller laboratory result model, then the data entry tool should be able to import data sets that are made with the schema that just defines laboratory results. The functional specification will include the list of compatible schemas which describe the kinds of data sets the generated data entry tool can import.
Design Considerations	The XML Schema and Configuration File developed for a project describe the features which will be supported by a generated data entry tool. This system was developed to present the information as a functional specification that could be evaluated by non-technical stake holders of a project. Most of the code was developed to present configuration options in HTML files that could be printed out and marked-up by people who were reviewing a demonstration of the generated application.
Scope of Effect	The scope of effect of the system is limited to the "Generate Functional Specifications" feature of the Project35 Configuration Tool. Changing aspects of this system should not impact any other part of the code base.
Relevant Code Packages	The main package for the functional specification system is project35.specifications.

Back to top