Learning FORM

A Detailed Description of a
Framework for Object-Relational Mapping

R1.2.1m

This document provides a detailed description of the concepts, design, and implementation of FORM, a framework for object-relational mapping. Learning FORM is meant for two audiences: the first audience is people working with FORM and who must understand the framework in enough detail to satisfy their application needs. The second is people interested in a detailed description of the issues with and approaches to building object-relational mapping frameworks. When you have finished with this document you will have a comprehensive understanding of FORM’s concepts, how to use the FORM API to accomplish specific tasks, and an overall approach for structuring programs that use any type of object-relational mapping tool.

Other Formats

• PDF Format: The PDF format is somewhat cleaner and truer to the original than this HTML format. The contents are identical.

Table of Contents

1 Overview  

1.1 Requirements  

1.2 Supplemental Reading  

ChiMu Resources  

Other resources  

1.3 Notation  

2 Introduction  

2.1 Application Architecture  

2.2 Just the Domain  

Domain Model-1  

Example: PersonRetrieval_1a  

2.3 Bringing in the Database and FORM  

Database Schema-1  

Example: PersonRetrieval_1b  

Implementation Changes  

Summary adding FORM  

2.4 Further Decoupling of the Domain and FORM  

2.5 Exposing FORM directly  

Example: PersonRetrieval_1c  

2.6 Conclusions  

3 Configuring and Running FORM  

3.1 Configuring FORM  

DatabaseConnection  

Orm  

ObjectMappers  

FormInfos  

Completing the Orm setup  

3.2 Running with FORM  

ObjectRetrievers  

Retrieving Objects  

Example: PersonRetrieval_2  

Object Typing  

3.3 Summary  

4 Creating an Object-Relational Mapping  

4.1 ObjectMappers and FormInfos  

4.2 Creating an ObjectMapper  

Tables  

FormInfo createMappers  

4.3 Configuring an ObjectMapper  

Slots  

Constructors  

FormInfo configureMappers  

FORM Preprocessor  

4.4 Linking ObjectMappers  

4.5 The Completed Person ObjectMapper  

4.6 New Examples: Using Slots in Retrievals  

Example: PersonRetrieval_3  

Example: PersonRetrieval_4  

4.7 General Domain Interfaces and Abstract Classes  

FORM Provided Abstract Classes  

Domain Interface for PersonRetrieval  

4.8 Putting it all Together  

PersonRetrieval_4  

ExampleAbsC  

PersonC_FormInfo  

DomainObjectAbsC_FormInfo  

DomainObject_1_AbsC_FormInfo  

4.9 Summary  

5 Introduction to Queries  

5.1 Queries  

5.2 ObjectRetriever Queries  

5.3 QueryDescriptions and QueryVars  

QueryDescriptions  

QueryVars  

Example: Query_1  

5.4 SlotVars and Results  

SlotVars  

Query Results  

Example: Query_2  

Duplicates  

5.5 Query Conditions  

Query Condition  

Example: Query_3  

Compounding conditions  

Example: Query_4  

5.6 Query Factoring  

5.7 Summary  

6 OQL: FORM’s Object Query Language  

6.1 Example: OqlQuery_1  

6.2 OqlQuery  

6.3 OQL to QueryDescription Equivalencies  

SlotVars  

Literal Constants  

Conditions and Expressions  

6.4 Example: OqlQuery_2  

6.5 Bound Values  

Example: OqlQuery_3  

Complex Object Values  

6.6 Combining with QueryDescriptions  

6.7 Summary  

7 Domain Object Services to FORM  

7.1 FORM to Domain Object Communication  

Constructing DomainObjects  

Determining whether an Object is a MappedObject  

Getting the ObjectMapper for a MappedObject  

Getting the IdentityKey of a MappedObject  

Giving a MappedObject a Database Identity  

Initializing the State of a MappedObject  

Extracting the State of a MappedObject  

7.2 FORM Preprocessor  

7.3 PersonC Implementation  

7.4 Summary  

8 Inserts, Updates, and Deletes  

8.1 Domain Model-1b  

Database Schema-1b  

8.2 Example: Update_1  

8.3 DomainObject Interface and DomainObject__AbsC  

DomainObject Interface  

DomainObject__AbsC  

8.4 ObjectMappers as ObjectSavers  

8.5 Example: Delete_1  

8.6 Example: Insert_1  

8.7 Types of Identity Generation  

8.8 Example Identity Generation  

8.9 Example: Write_1  

8.10 Summary  

9 Putting FORM underneath the Domain  

10 Associations  

10.1 Domain Model-2  

Database Model  

10.2 Associations  

10.3 Association Slots  

Properties of Association Slots  

Association Slot Types  

10.4 Example: EmployeeRetrieval_1  

10.5 Forward Associations in a Mapping  

10.6 Reverse Associations in a Mapping  

Cardinality  

10.7 Example: CompanyRetrieval_1  

Asymmetry between Forward and Reverse Associations  

10.8 Domain Model-3  

Database Model  

10.9 External Associations  

Association Connectors  

Example Configuration  

10.10 Summary  

11 Queries-2  

11.1 Association Slots  

Multiple Traversals  

Multiple Partners  

11.2 Connected and Unconnected Query Variables  

Explicitly Named OQL Query Variables  

Reusing Query Variables in the Query API  

12 Inserts, Updates, and Deletes – 2  

12.1 Transactions  

TransactionCoordinator  

Controlling Transaction Isolation  

TransactionCoordinator stages  

TransactionException  

Domain Model-3b  

Commits and Identity Generation within Transactions  

Future Enhancements to FORM Transactions  

Dome: Units of Work  

Other Alternatives: Semantic Transactions and Workflow  

12.2 Associated Objects in Inserts, Updates, and Deletes  

12.3 Automatic Refreshing  

12.4 Optimistic Locking  

12.5 Identity Cache Management  

Weak Cache Management  

Explicit Cache Management  

12.6 Other Control Functionality  

13 Conversions and Transformation Slots  

13.1 Simple Data Type Conversions  

13.2 Transformation Slots  

DomainModel-4  

13.3 Transforming Basic Data Types  

Mapping between Numerical Data Types  

Example: NumericTransform_1  

13.4 Database dependent Transformations  

Example: BooleanTransform_1  

DomainModel-4  

Example: ProjectInsert_1  

14 Embedded Objects  

14.1 Simple Embedded Object: US Dollars  

DomainModel-4b  

Money  

US Dollars  

14.2 Complex Embedded Object: Money  

DomainModel-4c  

Mapping Money  

14.3 Mapping a look up object  

DomainModel-4d  

Mapping a City  

15 Advanced Mappers and Retrievers  

15.1 Distinguishing Object Mappers  

Example: CommissionedRetrieval_1  

15.2 CollectiveObjectRetrievers  

Example: EmployeeRetrieval_2  

Example: EmployeeInsert_2  

16 Descriptions  

16.1 Database Descriptions  

DomainModel 5b  

16.2 Summary  

17 References  

17.1 ChiMu References  

17.2 General References  

18 Appendix-A OQL Syntax  

18.1 Non-Terminals  

18.2 Terminals  

WHITE SPACE  

COMMENTS  

OPERATORS  

SEPARATORS  

SPECIAL  

RESERVED WORDS AND LITERALS  

IDENTIFIERS  

LITERALS  

 

Example Listing

Example                                                                                                                                              Section     Page

PersonRetrieval_1a  

PersonRetrieval_1b  

PersonRetrieval_1c  

PersonRetreival_2  

PersonRetreival_3  

PersonRetreival_4  

Query_1  

Query_2  

Query_3  

Query_4  

OqlQuery_1  

OqlQuery_2  

OqlQuery_3  

Update_1  

Delete_1  

Insert_1  

Write_1  

EmployeeRetrieval_1  

CompanyRetrieval_1  

EmployeeInsert_1  

EmployeeInsert_2  

NumericTransform_1  

BooleanTransform_1  

ProjectInsert_1  

EmployeeRetrieval_2  

EmployeeInsert_2  

 

Figures Listing

Figures                                                                                                                                                                         Page

Figure 1: Classifier Stereotypes. 2

Figure 2: Attribute-specific Associations. 2

Figure 3: System Layering. 3

Figure 4: Domain Testing. 3

Figure 5: Example-1 Domain Model5

Figure 6: Architecture with FORM and Database. 6

Figure 7: Person Table. 7

Figure 8: Example-1 Domain Objects. 7

Figure 9: Category to Storage Relationships. 8

Figure 10: DomainObjects to Storage Relationships. 10

Figure 11: Client to Server IdentityKeys. 11

Figure 12: Domain Object to FORM Communication. 11

Figure 13: Local Container Architecture. 13

Figure 14: FORM-Based Container Architecture. 13

Figure 15: Domain-Internal Tester14

Figure 16: FORM... 15

Figure 17: DatabaseConnection Objects. 15

Figure 18: Orm & Database. 16

Figure 19: ObjectMapper Relationships. 16

Figure 20: FormInfos. 17

Figure 21: ObjectRetriever18

Figure 22: FORM Representation of Database. 22

Figure 23: Slots. 23

Figure 24: Person ObjectMapper26

Figure 25: Abstract Classes. 27

Figure 26: FORM Query Capabilities. 31

Figure 27: Query Extent Variables. 32

Figure 28: Slot Variable. 33

Figure 29: QueryVars with Person Objects. 34

Figure 30: OQL. 39

Figure 31: OqlQuery Transformation. 40

Figure 32: Domain-FORM... 45

Figure 33: Creation Functor45

Figure 34: Client-Server Object States. 49

Figure 35: Object Mappers. 51

Figure 36: Generator Counters. 53

Figure 37: Domain Model-1. 55

Figure 38: Domain to Storage Relationships. 55

Figure 39: Domain Model-2. 57

Figure 40: Database Model-2. 57

Figure 41: Type Association. 58

Figure 42: Object Linking. 58

Figure 43: ObjectMapper Associations. 58

Figure 44: Forward Association. 60

Figure 45: Reverse Association. 61

Figure 46: Paired Forward and Reverse Associations. 62

Figure 47: Domain Model-3. 62

Figure 48: Database Model-3. 63

Figure 49: External Associations. 63

Figure 50: Query through multiple slots: “employee.employer.revenues”. 68

Figure 51: Query with Multiple Partner Values. 68

Figure 52: Query through “employer.employees.height”. 69

Figure 53: Project Budget Mapping. 78

Figure 54: Company Revenues (Embedded US Dollars)81

Figure 55: Money Representation. 82

Figure 56: Money Subtypes. 82

Figure 57: Company Revenues (Embedded Money)83

Figure 58: Domain Model-4d. 83

Figure 59: Employee Class Hierarchy. 85

Figure 60: Data Model-5. 86

Figure 61: Collective Object Retriever88

Figure 62: Mapping Descriptions Architecture. 91