Home Page   We Generate Your Software.
Products Services Company Technology Demo Contact Site Map Search
The Somusar/SoProTech[tm] Booklet Series
Volume II

"somusar/SoProTech: A Sample Project"

Printer friendly


Contents
1. Introduction
2. Sample Project Entities
3. Sample Project Mold Kit
4. Project Conventions
5. Exercise 1: Adding Field currency to Entity country
5.1 Request For Change
5.2 Change Impact Analysis
5.3 Change Implementation
5.4 Actual Change Impact
6. Exercise 2: Adding Entity "company.ef"
7. Exercise 3: Changing all SQL Scripts and all HTML Forms
8. Further Reading
Appendix A - Project Entity Files
Appendix B - Library Entities

Chapter 5 - Exercise 1: Adding Field currency to Entity country

This chapter describes the first simulation exercise of system modification on the sample SoProTech project. The exercise simulates a simplified change management process, consisting of the following steps:

  • Request for change;

  • Change impact analysis;

  • Change implementation;

  • Change impact verification.

In this exercise an apparently small change is applied to one single entity, showing how SoProTech[tm] can help software development teams apply local changes that automatically have cascading effects on several parts of the software system.

5.1 - Request For Change        top

The sample project entity country has been initially designed as a single-field entity containing the country name, as shown in the following code example.

Code Example 1 - Single-field "country.ef"
Entity country consists of just one enum (lines 4 and 7-14). Adjusting parameter DB.table.create on line 25 is set to "false", hence no database table is created for country. Collection DB.table (lines 16-17) defines the set of country fields to be embedded in the database table of other entities that embed country as one of their own DB.table members.
Source code - File "country.ef"
    1      country "Country"
    2      | A national country
    3      
    4      enum                    country         "Country"
    5      
    6      ----------------------- DEFS
    7      country:
    8         usa                  "USA"
    9         canada               "Canada"
   10         japan                "Japan"
   11         france               "France"
   12         uk                   "UK"
   13         espana               "Espaņa"
   14         india                "India"
   15      ----------------------- DB
   16      table:
   17         country
   18      ----------------------- LOGIC
   19      class:
   20         country
   21      ----------------------- UI
   22      full_view:
   23      country
   24      ----------------------- ADJUST
   25      DB.table.create = "false"
	       

The project team is requested to adapt the software system, so that it handles national or federated currencies.

5.2 - Change Impact Analysis        top

The project team decides to insert a new enum field currency into entity country.

Entity country is logically located at the bottom of the entity relationships graph: it consists of a single, basic type field, and it is embedded in entities person_info (as field nationality) and address (as field country), which are in turn embedded in higher-level entities.

Thus, as small as this change may appear, it actually impacts several aspects of all layers of the system, for example:

  1. A database table for country is required, to store the current currency of a country, as the currency may change in the future;

  2. Java[tm] and C++ classes derived from country should handle the new member;

  3. The DB table for entity customer embeds collection country.DB.table via its field address, but it should not embed the new field currency;

  4. The UI full view of an employee embeds the nationality of the employee via its field info, but it should not be concerned by new field currency.

5.3 - Change Implementation        top

Changes 1 and 2 in the previous list can be accomplished directly in "country.ef", as shown in the following code example.

Code Example 2 - The updated "country.ef"
The extended entity country contains a new enum currency (lines 5 and 17-25), which is added as a new member to collections DB.table, LOGIC.class and UI.full_view.

Adjusting parameter DB.table.create is set to true, and a new collection DB.pkey is defined, according to project conventions.

Finally, member country is renamed country_name, to better specify its contents.

Source code - File "location/country.ef"
    1      country "Country"
    2      | A national country
    3      
    4      enum                    country_name    "Country"
    5      enum                    currency        "Currency"
    6      
    7      ----------------------- DEFS
    8      country_name:
    9         usa                  "USA"
   10         canada               "Canada"
   11         japan                "Japan"
   12         france               "France"
   13         uk                   "UK"
   14         espana               "Espaņa"
   15         india                "India"
   16      
   17      currency:
   18         us_dollar            "US dollar"
   19         cnd_dollar           "Canadian dollar"
   20         yen                  "Yen"
   21         french_franc         "French franc"
   22         uk_pound             "UK pound"
   23         peseta               "Peseta"
   24         rupia                "Rupia"
   25         euro                 "Euro"
   26      
   27      ----------------------- DB
   28      table:
   29         country_name, currency
   30      
   31      pkey:
   32         country_name
   33      ----------------------- LOGIC
   34      class:
   35         country_name, currency
   36      ----------------------- UI
   37      full_view:
   38      country_name
   39      currency
   40      ----------------------- ADJUST
   41      DB.table.create = "true"
	       

Changes 3 and 4 are logically more subtle: the point is that an address and a set of person_info should not directly embed the data fields of a country. Instead, they should relate to one country.

Therefore, changes 3 and 4 merely require to add the Sisendel type specifier link in the definition of fields address.country and person_info.nationality, which are both of the Sisendel type country.

Such simple changes can be applied within minutes using a standard text editor. No changes on the molds are required: it is thus sufficient to run the Somusar/Software Production Machine[tm] in order to re-generate within a few seconds all software files (including DOCumentation pages) for all entities: on a 1700 MHz Intel®-based Linux® PC with 256 MB RAM the complete automatic production process required less than 7 seconds.

5.4 - Actual Change Impact        top

The comparison between the files generated before and after modifying the entity files show an impressive amount of comparatively small consistent changes scattered across several generated files. The table below lists the impacted files and describes these changes.

Table 8 - Changes in the generated files due to new country.currency field

Generated file Description of change
business/DB/customer.sql Column country renamed to countryname
company/DB/employee.sql Column infonationalitycountry renamed to infonationalitycountryname
location/DB/country.sql New SQL script to create table country
location/LOGIC/Address.h
persons/LOGIC/PersonInfo.h
Member of type Country replaced by an int representing the relationship to class Country; related get/set methods accordingly changed
location/LOGIC/Country.h Member country and related get/set methods changed to countryName; new type enumCurrency and new member currency, with related get/set methods
location/LOGIC/Address.java
persons/LOGIC/PersonInfo.java
Member of type Country replaced by an int representing the relationship to class Country; related get/set methods accordingly changed
location/LOGIC/Country.java Member country and related get/set methods changed to countryName; new mapping for Sisendel enum Currency and new int member currency, with related get/set methods
business/UI/customer.fview
company/UI/employee.fview
location/UI/address.fview
location/UI/country.fview
persons/UI/person_info.fview
Same changes as in corresponding UI/<entity>.html files below
business/UI/customer.html
company/UI/employee.html
location/UI/address.html
persons/UI/person_info.html
Embedded country replaced by a reference to it
location/UI/country.html select name="country" replaced by select name="country_name"; new select/option list for currency
location/DOC/address.html
location/DOC/country.html
persons/DOC/person_info.html
Updated entity documentation pages

The following code examples and illustrations describe in more detail some of the changes listed above.

Code Example 3 - New SQL script "country.sql"
The new database table is required to keep track of national country currencies.
Source code - File "location/DB/country.sql"
    1      --
    2      -- This SQL script created by somusar/SoProMach[tm]
    3      --
    4      
    5      create table country (
    6          countryname               varchar(40)    not null,
    7          currency                  varchar(40)    not null,
    8          constraint pk_country     primary key    (countryname)
    9      )
   10      ;
   11      
	       

Code Example 4 - Changes in "Country.java" due to new country.currency field
The changes caused by adding field currency can be seen on lines 25-33, 36, 46-48, 58-60.
Source code - File "location/LOGIC/Country.java"
    1      /*
    2       * This Java class generated by somusar/SoProMach[tm].
    3       */
    4      
    5      package com.somusar.entdemo.location;
    6      
    7      /**
    8       *   Class Country:
    9       *
   10       *   A national country.
   11       */
   12      
   13      
   14      public class Country {
   15      
   16          // Map enum 'Country' onto an int with a set of values
   17          public final int USA                = 0; // USA
   18          public final int CANADA             = 1; // Canada
   19          public final int JAPAN              = 2; // Japan
   20          public final int FRANCE             = 3; // France
   21          public final int UK                 = 4; // UK
   22          public final int ESPANA             = 5; // Espaņa
   23          public final int INDIA              = 6; // India
   24      
   25          // Map enum 'Currency' onto an int with a set of values
   26          public final int US_DOLLAR          = 0; // US dollar
   27          public final int CND_DOLLAR         = 1; // Canadian dollar
   28          public final int YEN                = 2; // Yen
   29          public final int FRENCH_FRANC       = 3; // French franc
   30          public final int UK_POUND           = 4; // UK pound
   31          public final int PESETA             = 5; // Peseta
   32          public final int RUPIA              = 6; // Rupia
   33          public final int EURO               = 7; // Euro
   34      
   35          private int          countryName;        // enum 'Country'
   36          private int          currency;           // enum 'Currency'
   37          
   38          /*
   39           *   Get methods
   40           */
   41      
   42          public int getCountryName() {
   43              return countryName;
   44          }
   45      
   46          public int getCurrency() {
   47              return currency;
   48          }
   49      
   50          /*
   51           *   Set methods
   52           */
   53      
   54          public void setCountryName( int countryName ) {
   55              this.countryName = countryName;
   56          }
   57      
   58          public void setCurrency( int currency ) {
   59              this.currency = currency;
   60          }
   61      
   62      }
	       

Code Example 5 - Changes in "PersonInfo.h" due to new country.currency field
Entity person_info, that formerly embedded country, has now a link to it. The related changes can be seen on lines 37, 54-57, 74-77.
Source code - File "persons/LOGIC/PersonInfo.h"
    1      #ifndef __PersonInfo__
    2      #define __PersonInfo__
    3      
    4      /*
    5       *   -----------------------------------------------------------------
    6       *   Class PersonInfo
    7       *
    8       *   Private information, to be kept distinct from employee 
    9       *   info.
   10       *   -----------------------------------------------------------------
   11       * 
   12       *   [This header generated by somusar/SoProMach[tm].]
   13       */
   14      
   15      
   16      
   17      #ifndef __dummy_classes__
   18      #   define __dummy_classes__
   19      
   20      /* Dummy declarations, just for compiling.  */
   21      class Collection { char s[100]; };
   22      class Object     { char s[100]; };
   23      
   24      #endif
   25      
   26      #include <String.h>
   27      
   28      #include "location/Country.h"
   29      #include "Image.h"
   30      
   31      class PersonInfo {
   32      
   33      private:
   34      
   35          int          age;                // 18-120; would fit in a uint8
   36          String       ssn;                
   37          int          nationalityCountryName;        // relationship to Country
   38          Image        photo;              
   39      
   40      public:
   41      
   42          /*
   43           *   Get methods
   44           */
   45      
   46          int getAge() {
   47              return age;
   48          }
   49      
   50          String getSsn() {
   51              return ssn;
   52          }
   53      
   54          int getNationalityCountryName() {
   55              return nationalityCountryName;
   56          }
   57      
   58          Image getPhoto() {
   59              return photo;
   60          }
   61      
   62          /*
   63           *   Set methods
   64           */
   65      
   66          void setAge( int age ) {
   67              this->age = age;
   68          }
   69      
   70          void setSsn( String ssn ) {
   71              this->ssn = ssn;
   72          }
   73      
   74          void setNationalityCountryName( int nationalityCountryName ) {
   75              this->nationalityCountryName = nationalityCountryName;
   76          }
   77      
   78          void setPhoto( Image photo ) {
   79              this->photo = photo;
   80          }
   81      
   82      };
   83      
   84      #endif /* __PersonInfo__ */
	       

The next illustrations show the user interface form for entity customer before and after adding field country.currency.

Figure 2 - "UI/customer.html" without country.currency
Figure 2 - <tt>"UI/customer.html"</tt> without <tt>country.currency</tt>
Enlarge

Figure 3 - Changes in "UI/customer.html" due to country.currency
Figure 3 - Changes in <tt>"UI/customer.html"</tt> due to <tt>country.currency</tt>
Enlarge

The following illustrations show the documentation page for entity country before and after adding field currency.

Figure 4 - "DOC/country.html" without currency
Figure 4 - <tt>"DOC/country.html"</tt> without <tt>currency</tt>
Enlarge

Figure 5 - Changes in "DOC/country.html" due to currency
Figure 5 - Changes in <tt>"DOC/country.html"</tt> due to <tt>currency</tt>
Enlarge

[Previous chapter]    [Next chapter]    [Back to top]

http:// www.somusar.com  / doc  / booklets  / sample_proj  - Powered by SoProMach
Copyright © 2003-2012 Somusar - Trademarks - Legal - Privacy - Webmaster