Defining a Foreign Key in a Model

Defining a Foreign Key in a Model

The ORM supports currently supports the modeling of three types of foreign key relationships: the belongs to relationship, the has one relationship, and the has many relationship.

Creating a "Belongs To" Relationship

The belongs to relationship is used when a Child model belongs to a Parent model. A Child model refers to the class that has the foreign key which associates with the Parent model's primary key. This relationship is a one-to-one association.

Let's take the Person class (i.e. the Child model). In the Person.h file, add the following prototype for getting the person's address:

- (Address *) address;

For this example, we will assume that the Address class (i.e. the Parent model) uses a composite primary key made up of a first name and a last name; therefore, there is only one address for each unique name pairing. The next step is to add the respective logic in the Person.m file (i.e. the Child model):

- (Address *) address {
     return [self belongsTo: [Address class] foreignKey: [NSArray arrayWithObjects: @"firstName", @"lastName", nil]];
}

Note that the field names (i.e. firstName and lastName) populating the foreign key array in this example are referring to the instance variables in the Person class, not in Address class. This foreign key array will be mapped to the primary key array of the Address class in the same order the primary key was defined in the model.

Upon calling this "address" method, it will return an instance of the Address class populated with the address information for that Person. This instance is set to autorelease.

Creating a "Has One" Relationship

A similar mapping is the has one relationship. As its name implies, it is also a one-to-one association. However, it differs from the belongs to relationship in that the relationship is defined in the Parent model rather than in the Child model. The has one relationship maps the primary key in the Parent class to the foreign key in the Child model.

To create a has one relationship, let's add the following prototype to Person class (which is now considered the Parent model because its primary key will be used to make the association):

- (Email *) email;

Now in the Person.m file, add the following logic:

- (Email *) email {
     return [self hasOne: [Email class] foreignKey: [NSArray arrayWithObject: @"personPK"]];
}

Unlike the belongs to relationship, the field name in the foreign key array is the name of an instance variable in the Email class (i.e. the Child model). Therefore, the "pk" field in Person class will be associated with the "personPK" field in Email class.

The model instance returned by this method is set to autorelease.

Creating a "Has Many" Relationship

The has many relationship is used to create a one-to-many association. It is set up almost identical to the has one relationship, except it will return a result set (i.e. an array of models) rather than a single model.

To create a has many relationship, add the following prototype to the Person.h file:

- (NSArray *) phoneNumbers;

The next step will be to add the appropriate logic to the Person.m file:

- (NSArray *) phoneNumbers {
     return [self hasMany: [PhoneNumber class] foreignKey: [NSArray arrayWithObjects: @"personPK", nil]];
}

Like the has one relationship, the field name "personPK" is a member of the PhoneNumber class (i.e. the Child model) and will relate to the primary key "pk" in the Person class (i.e. Parent model).

The result set is an array of PhoneNumber models. Instances contained in this array are set to autorelease.

A result set can also be manipulated via the various supported options: LIMIT and OFFSET. Here is an example of how this can be done:

- (NSArray *) phoneNumbers {
     return [self hasMany: [PhoneNumber class] foreignKey: [NSArray arrayWithObjects: @"personPK", nil] options: [NSDictionary dictionaryWithObjectsAndKeys: [NSNumber numberWithInteger: 5], ZIMOrmOptionLimit, [NSNumber numberWithInteger: 2], ZIMOrmOptionOffset, nil]];
}