The Object Relational Persistency in Cincom® ObjectStudio®

Mapping Tool

This month we’ll have a look at the Object Relational Persistency in ObjectStudio. While we have a great object-oriented system, most of our data is still saved in relational databases.  This article is an overview of our current work on a tool we are developing to help you in this work.

Domain Model

The Mapping Tool uses classes that need persistency.  To explain the current features of the Mapping Tool, we’ll use a small example we call the Ebook Catalog.

We’ve created an abstract class BaseObject, which will be the superclass of our domain classes, and another abstract class named BasePersistentObject, which will be the superclass of our persistent domain classes. The BasePersistentObject contains the common attributes for our persistent objects like id, currentStatus, timestamp and username.

We have four persistent classes:

1. Author
2. Ebook
3. EbookVersion and
4. Language

There is also one embedded class we called Life.  This class has two dates and can test and make calculations with these dates. The class has no persistency of its own, but its values will be made persistent together with its parent object.

In our example, we have a hierarchy structure.  However, to create persistency for your objects, you don’t need this structure.

Adding Classes to the Atlas

Once we start the Mapping Tool, create a new atlas and make a database connection, we are ready to add classes to the atlas.

Any class of your Smalltalk image can be imported into the Mapping Tool. Abstract superclasses don’t need to be imported into the Mapping Tool since the subclass will show the defined instance variables of that class. We have four ways of making this easier for you.

1. Import from the Modeling Tool. All available classes currently in the Modeling Tool are available. Model information from these classes is converted to GLORP class models.
2. Import from Bundle/Package.  A drop-down box with all bundles and packages is available for selecting the required bundle or package.
3. Import from a Namespace. A drop-down box with all defined Namespaces is shown to make the selection.
4. Import from the Image. A search field is shown to help you limit the number of classes in the list.

Classes imported from the Modeling Tool have attribute domain information. This information is converted to a Glorp classmodel. For any other imported class, you need to enter this information.

For now, our work on the Object side is complete, and we are going to focus on the Relational side of our application. Here we have two options. We either use already-existing tables on our database, or we create new tables based on the model we just designed.

Using Existing Tables

Based on the database connection and chosen schema, we can add existing tables to our atlas.

Create New Tables Based on Our Classes

In this case, we’ll create new tables based on the classes we imported into our Mapping Tool. Simply select the class that you want to generate a table for, and choose the Create Table option from the pop-up menu.

The easiest way to do this is to start with embedded classes. For these classes, you’ll create “imaginary tables,” which means that they only exist in the Smalltalk image and are not generated to the database.  When these imaginary tables are created, the other classes will use this definition to embed the files into their own tables.

When this is done, we start by creating tables that have no relationships defined in their structure. This makes it easier to define the foreign key constraints for the database tables.

Once the desired database definitions are done, we can generate the tables to the database. Select the table and choose the Generate Table option from the pop-up menu.

In the next release, we’ll provide a global create and generate tables option, so we don’t need to do this table-by-table.

Now we have classes and tables, and we need to link them together.

Try Matching

If the naming conventions between classes/attributes and tables/columns are comparable, we can try to do some automatic mapping.  Press the  “try matching” button on the toolbar (or choose the option from the Mapping  menu), and the system will try to map as much as possible. Right now this option supports:

• Direct mappings
• Relationship mapping (one to one, one to many and many to many)
• Embedded mappings

The list will be extended with the next release.

Mappings that we couldn’t create automatically will have to be done manually.

Manual Mapping The current mapping tool allows the following manual mapping configurations:

• Constant mapping
• Direct mapping
• Relationship mapping (one to one, one to many and many to many)

The list will be extended with the next release.

After we open the view for the mapping details, we get the following screen.

We get a tree view with the available classes on the right. If you select a class, you’ll see the mappings of this class on the right.

Constant Mapping

A constant mapping assigns a fixed value to an instance variable. This can be a number, string or the database session.

Direct Mapping

When you select an attribute or instance variable, you get the current mapping or you can select the desired mapping for the attribute in the drop-down box.

Converters are normally assigned by the system, but you can define your own converters.

Converters

The mapping tool allows you to consult the available converters in the system but doesn’t allow you to edit or add new ones. We’ll have more information on converters in one of the future issues of the Cincom Smalltalk Digest.

Relationship Mappings

With one-to-one and one-to-many mapping, we can choose our source and target table and then add the compare conditions between the columns.  With many-to-many mapping, we need an additional look-up table as shown on the screen below.

Once you’ve created all of your mappings, we’ll discuss the items we see on the main mapping tool screen.

The top-left tree view shows the classes and their attributes. Selecting a class or instance variable will show its mapping detail in the left bottom list view.  On the top right, you see the classes that are referenced by the currently selected class or instance variable.

To the right of the class/instance variable tree view, you have a tree view with tables/columns. Selecting one of these will show on the left bottom view the mapping details. Then, on the right bottom, you’ll see the tables that are referenced by the tables/columns selection in the tree view.

With the   button on the toolbar or the Atlas – Write Descriptor System menu item. we’ll save our Mapping Tool work and the GLORP descriptor system. In next month’s Cincom Smalltalk Digest, we’ll discuss how to use this descriptor system in your code.