Generic OR mapper

1. Introduction

Designing object oriented applications, you typically claim, that the complete design can be created on OO style - without break of media. In order to achieve this goal, each developer was yet faced with the problem of data storage in relation databases. If there is no tool, a DataMapper has to be implemented newly for each application. This does not only result in higher costs and lack of time, but is also not compatible with the DRY (don't repeat yourself) paradigma. You still are forced to produce redundant code.

The APF module genericormapper now provides an abstraction layer, that is intended to do most of the work a data mapper has to do. The functionality thereby can

• manage objects,
• manage relations between objects (compositions and assoziations) and
• features CRUD functionality for objects and object structures (aka. trees).

For this tasks, the API features a couple of methods, that support loading, manipulation and deletion of objects within the database. The generic domain object (GenericDomainObject) returned by the API functions can on the one hand be used directly within your applications or your application features a simple data layer, that mapps the data mapper domain objects into your application's domain objects and vice versa.

The following chapters show how the OR mapper has to be configured and how you can use it. The module usermanagement shipped with the APF release is completely based on the GenericORMapper and thus can be used as an extended implementation example. Details on the module can be seen on the User management module page.

2. Configuration of the OR mapper

2.1. Basics

To be able to user the OR mapper, two configuration files must be present:

• {ENVIRONMENT}_{NAMEAFFIX}_objects.ini
• {ENVIRONMENT}_{NAMEAFFIX}_relations.ini

The first file defines the objects and attributes, the second one is intended to define the relations between the objects from the first file. Due to the fact, that the GenericORRelationMapper uses the ConnectionManager for database access, a database connection configuration must be created if not done yet.

The {ENVIRONMENT} part of the configuration file names is taken from the registry directive Environment from the apf::core namespace. The {NAMEAFFIX} can be defined freely by the developer. This part of the name is inteded to provide the possibility of different mapper configurations for one context and one environment. This enables you to create applications, that are able to use multiple data sources.

2.2. Configuration examples

Imagine, that a developer wants to create a guestbook. The source code files are located in the modules::myguestbook namespace and the guestbook's data layer should us the OR mapper. Further, the registry value Environment is not touched (so it is still the default value) and the current application context is sites::mysite. Moreover, he decides, that the name affix should be identical to guestbook. In this case, the object configuration file must be named and the relation configuration file These must reside within the folder Further details on configuration, namespaces and contexts can be taken from the configuration scheme definition.

2.3. Object and relation definition

The way of object and relation definition is described in the next two chapters:

2.3.1. Object definition

The GenericORRelationMapper provides a generic domain object (GenericDomainObject) that represents a persistence object. The type of the concrete object is classified by the domain object's ObjectName property.

The object definition thus contains the name of the object (=name of the section) and the attributes (=properties of the GenericDomainObject class). The following codebox shows a typical object configuration: The values of the attributes represent the database data types of the object's properties. The mapper knows the following values and translates them into the right create table statements:

• VARCHAR({LENGTH})
• TEXT
• DATE

The {LENGTH} place holder must be replaced by any number. All other values are directly used for the data type of a property. These must be valid data type definitions. Otherwise, the CREATE TABLE statements will fail. The values presented above should be suitable for most application cases. The attributes of a domain object can then be addressed as follows:

2.3.2. Relation definition

The file *_relations.ini defines the relations between the objects defined in the previous chapter. The mapper knows two types of relations: compositions and associations. Due to the fact, that compositions are strong relations, objects, that compose other objects, cannot be deleted due to data consistency. This case is checked by the mapper and it throws an error, if a object is tried to be deleted, that must not.

Note: The persistancy theory contains the rule, that each object should be composed exactly one time. This is because an object cannot have more than one strong binding to another object in real life, too. Futhermore, a composition relation defines the object's right to exist. Hence, be aware that your objects are composed concerning this rule. For example, a guestbook entry cannot exist without the guestbook object. Instead, a user can exist without the guestbook. This means, that the relation between a guestbook and an entry must be a composition, the relation of the entry to the user must be an association.

The following codebox shows a typical relation configuration: The section name (e.g. Group2User) should be named self-explanatory, because this relation key can be used to load objects, that are related to others and to create a relation between two or more objects. The type attribute contains the quality of relation, the SourceObject and TargetObject params reference the relevant object definition sections of the object definition file.

Since version 1.14 you also can use self-references, which means that an object can reference another object of the same object type. There is no difference to normal references, you just configure the same name in source- and targetobject:

Also, when using this feature, you do not take care of anything, as long as the SQL-statements get generated from the methods of the OR mapper, and do not get written on your own.

Note:

• The count of the relation definitions is not limited, each definition should be created to fit the requirements of the data model of the application. The rule of thumb here says, that when using one attribute more than one time in different objects, it should be outsourced to an independent object and referenced (associated) by the relevant objects. A typical example is the language.
• If you have created an object tree using the method addRelatedObject(), you can read the related objects of the desired node (GenericDomainObject) within the tree using getRelatedObjects() for futher manipulation or processing.

2.4. Additional indices

Since version 1.12 it is possible to define additional indices along with the objct definition. This may be necessary due to performance reasons and it is strongly recommended to use this feature, if you are heavily requesting data using index restriction.

In such cases an object definition can be added the AddIndices key. The information provided there is used during setup and update to create additional indices to speed up the query execution time.

The subsequent code box describes a simple example with three types of indices defined within a user's object definition:

The additional index definition underlies the following scheme:

• Each additional index is defined by the included properties and the index type. Multiple definitions are separated by "|" (Pipe).
• Valid index types are: INDEX (normal index), UNIQUE (property may only contain a unique value), And FULLTEXT (search index, that can be searched using a MATCH AGAINST() statement). All index types are noted in brackets.
• In case multiple properties should be included in one index definition, the properties must be separated by colon (","). The names of the properties must be equal to the names used for the usual object definition.

3. Database setup

After the configuration files have been created, the database must be prepared for usage. This can be done manually or automatically. The manual way is described in the manual database setup chapter.

The following script shows, how the automated database setup can be done with aim of the GenericORMapperSetup tool. If you are searching for an example script, have a look at the /apps/modules/genericormapper/data/tools folder in the apf-codepack-* release. The file is named setup.php and must be adapted to your application case: The place holders within the script have the following meaning:

• {ENVIRONMENT}: This is the environment indicator of the application. It is used for addressing configuration files and must be adopted, if your environment is set to a value different than the default one. For details have a look at the Configuration (since 1.13) chapter.
• {CONTEXT}: This is the context of the application. It is used for addressing configuration files and must be adopted, if your environment is set to a value different than the default one. For details have a look at the Configuration (since 1.13) chapter.
• {CONFIG_NAMESPACE}: The namespace, that contains the mapper configuration files (see chapter 2.2).
• {CONFIG_NAME_AFFIX}: The name affix for the configuration files (see chapter 2.1).
• {CONNECTION_NAME}: The name of the database connection, that is used for the setup and for productional use.

Further, it is important that the database, that should be initialized, must exist before setup is started. Additionally, the user connecting to the database must have CREATE TABLE rights. Otherwise, the setup could not be done. If no error is displayed during setup, the setup has finished successfully. The result can be checked by using phpMyAdmin or a MySQLAdmin tool.

Executing the script to display the create statements only, the output should look like this:

Using phpMyAdmin you will get the following screen:

Now, the configuration of the mapper has finished and you can use it. Changes to the data model (at the moment) cannot be automatically applied to the database. For this reason, the affected tables must be altered manually. Due to the fact, that the database layout follows some easy ruls, you can easily do this yourself. Hints can be taken from the manual database setup chapter.

4. Usage of the OR mapper

The OR mapper, more precisely the GenericORRelationMapper, offers a list of API methods, that can be used for data and relation usage and manipulation. The following list gives you an overview of the existing functions and their meaning:

• loadObjectListByCriterion(): Loads an object list by a criterion object.
• loadObjectByCriterion(): Loads an object by a criterion object.
• loadRelatedObjects(): Loads a list of objects, that are related to a dedicated object, by a relation key.
• loadNotRelatedObjects(): Loads a list of objects by a relation key, that are *not* related to a dedicated object.
• loadRelationMultiplicity(): Returns the number of objects, that are related to a dedicated object.
• saveObject(): Saves an object or object tree, that consists of objects related to each other using the defined relations.
• deleteObject(): Deletes an object. Associations and compositions are deleted as well.
• createAssociation(): Creates an association between two objects.
• deleteAssociation(): Deletes the associations between two objects.
• deleteAssociations(): Deletes all associations that the given object has.
• isAssociated(): Checks, if two objects are associated.
• loadObjectListByStatement(): Loads a list of objects by a statement.
• loadObjectListByTextStatement(): Loads a list of objects by a statement present as a string.
• loadObjectListByIDs(): Loads a list of objects by a list of ids.
• loadObjectByStatement(): Loads an object by a statement.
• loadObjectByTextStatement(): Loads an object by a statement present as a string.
• loadObjectByID(): Loads an object by a given id.
• loadObjectsWithRelation(): Loads a list of objects specified by the applied object type (object name as noted within the configuration) and the relation it should have.
• loadObjectsWithoutRelation(): Loads a list of objects specified by the applied object type (object name as noted within the configuration) and the relation it should *not* have.
• loadRelatedObject(): Loads a an object that is related to the current object using the applied relation name.

The *Statement* methods are provided due to performance optimization reasons. For details, please have a look at the performance hacks chapter. Details on the aruments can be taken from the API documentation page for the modules.

4.1. Creating an instance of the mapper

4.1.1. Classic approach

The instance of the OR mapper must be created using the GenericORMapperFactory. This is necessary, because the concrete mapper must be initialized prior to use and to have the possibility to use more than one instance per module. The latter one is probably not necessary within easy applications, but in complexe environments this may be a knock-out criterion.

The next code box shows a typical call of the mapper:

The place holders have the following meaning:

• {SERVICE_OBJECT_TYPE}: The type of service object of the factory. This param implicitly defines service type of the mapper. Allowed values NORMAL, SINGLETON, and SESSIONSINGLETON. Default is SINGLETON. Details can be taken from the service object section.
• {CONFIG_NAMESPACE}: The namespace, the configuration files reside (see chapter 2.2).
• {CONFIG_NAME_AFFIX}: The name affix, the configuration files have (see chapter 2.1).
• {CONNECTION_NAME}: The name of the database connection used for setup and usage.

Please note, that the factory must be created by the getServiceObject() function to avoid unnecessary configuration side-effects.

4.1.2. Creation via DI

As of release 1.12 the GORM can also be created using the DIServiceManager. This approach implies advantages to testability and decoupling of business layer and presentation layer.

Creating an instance of the GORM is thus directly done by the DIServiceManager and not using the factory described above. This is because the DIServiceManager only accepts explicit service objects for dynamic initialization of other services. For this reason, three new services are available that do not contain any logic but the necessary configuration information:

• GenericORMapperDIConfiguration: injection of the basic configuration
• GenericORMapperDIMappingConfiguration: injection of additional mapping configurations
• GenericORMapperDIRelationConfiguration: injection of additional relation configurations

Details in the configuration beside an application sample can be found on the wiki page Erzeugen des GORM mit dem DIServiceManager (German).

4.2. Loading data

To have a concrete example for the next code samples, the following UML diagram should be used. The picture contains the business object definition of the usermanagement module contained in the APF. The code presented here is thus taken from the module's code files.

4.2.1. Loading objects

To load objects, you can use the functions

• loadObjectByCriterion()
• loadObjectByTextStatement()
• loadObjectByStatement()
• loadObjectByID()

If you intend to display the details of a user (see UML), you kan take the methods listed above to achieve this:

The content of the statement file load_user_by_id is:

Details on the statement execution can be taken from the statement files documentation.

4.2.2. Loading lists

For loading lists, the OR mapper features the following methods:

• loadObjectListByCriterion()
• loadObjectListByTextStatement()
• loadObjectListByStatement()
• loadObjectListByIDs()

If you like to display a list of users (see UML) you can use these methods as presented below: The content of the statement file load_user_list looks like this:

4.2.3. Loading related objects

If you have to display the corresponding groups while listing the user details, you can use the

• loadRelatedObjects()

function. This method returns the objects related to a dedicated object by the desired relation key. The next example shows, how to load the groups associated to a user: To ease the handling of loading related objects, the GenericDomainObject posesses the loadRelatedObjects() function. This enables you to load the related objects using a relation key, where no instance of the mapper is available. To apply this to the example above, the user's groups could be loaded using Note: The amount of objects loaded, can be limited using the GenericCriterionObject. So if you like to load the first 10 groups only, include the following code in your application:

4.2.4. Loading not related objects

Often you have to select objects, that are not (yet) related with a given object, but a relation is defined. A good example, concerning the UML diagram above, is the listing of groups, that a certain user has not been added yet. For this purpose, the

• loadNotRelatedObjects()

function could be used. The next example shows, how groups not associated with desired user can be selected: Note: The amount of objects loaded, can be limited using the GenericCriterionObject. A typical application case is to limit the list by relations to other objects. The following example explains, how to load all groups, that are not associated to the desired user but are composed under a Application object:

4.2.5. Loading the relation multiplicity

To be able to find out, how much objects are related to a certain one, the

• loadRelationMultiplicity()

method can be used. It returns the multiplicity by a given object and a relation key. In order to count the users within a group, add the follwing code to your business layer:

4.2.6 Loading the object count

Beneath the amount of objects related to another object, release 1.12 introduces a method to request the amount of objects of a certain kind stored in the database. For this reason, the

• loadObjectCount()

method has been added. It takes the name of the object as defined in the mappin configuration as it's first parameter. As an optional second parameter, you can pass a GenericCriterionObject that limits the amount of objects using attribute indicators.

Requesting the amount of objects of type User and all users who's last name starts with character A can be requested as follows:

4.3. Saving objects

Saving objects is quite easy. Regardless you save objects or object trees, the

• saveObject()

function can be used. The next code box shows how to save a user:

4.4. Saving object trees

As already mentioned above, the OR mapper is not only able to save flat object structures but also object trees. This feature can especially be used within your application's data layer to create the necessary relations.

Problem: When you create a User, it should be composed under the Application object. The latter one is used to ensure multi-client capability for the user management module.

Solution: To create the relation between these two objects (Application and User), the addRelatedObject() method of the GenericDomainObject can be used. The following code box shows, how the implementation is like: If you intend to add a group and a role at the same time, the php code above must be added the following lines:

5. The GenericCriterionObject

The present chapter is intended to describe the usage of the GenericCriterionObject. As already mentioned in the chapters above, the class can be used to configure your request rather than to write SQL statements. The object can be used with all load*ByCriterion() methods and while loading relation objects on existing domain objects or domain object lists.

5.1. Basics

The code box below presents an application use case of the GenericCriterionObject, where a list of users should be loaded. The users should be assigned to a special group and must be composed under a certain application object:

Notes on the source code:

• Relations:
  Adding a relation indicator to the criterion object says, that the object or object list to be loaded must have a relation to the object within the criterion. If a relation to the Application object (composition) and to the Group object (association) is added, this means that the resulting object list belongs to a dedicated application and is assigned to a special group.
  If a developer is likely to select all users, that belong to a dedicated application and are are member of a group and are assigned a role, three relation indicators must be added to the criterion object.
• Sort sequence:
  The order of calls decides the sort sequences. If you like to sort in another direction, the sort indicators must be changed. ASC stands for ascending and DESC for descending sortation.

5.2. Combination

Since release 1.14 the GenericCriterionObject provides the possibility to use enhanced logical operators such as AND OR, XOR, and NOT. To support this feature, the facility to combine criterion objects has been introduced. You are now enabled to create any mixture of operators you need.

The definition of the logical operator can be defined by setLogicalOperator() method invoked on any criterion. By default, AND is used to guarantee backward compatibility. To define the logical operator, just add these two lines of code:

Please note, that the logical operator is not applied to the whole criterion instance but is stored to be used for the next call of addPropertyIndicator().

The above code block creates the following condition. Please note, that the table names and the aliases the GORM uses are left out for better readability:

As you can see with this example, the operator is stored until it's next change.

Due to the fact, that the last condition evaluates to true even if only `field4` contains 'value4' adding conditions directly after changing the the operator may often not make sense. In case you want to build up the condition to evaluate to true only if the `field1` must contain 'value1' and at least one of the other fields contains the defined value, the second block must be noted in brackets. You can realize this as follows:

As you can get from the addPropertyIndicator() call this method takes a string or a criterion object as it's second argument. This kind of combining criterion objects is not limited. Using the above code to execute a query, the subsequent sql is generated:

5.3. Comparison operators

Since 1.14 the GenericCriterionObject supports configurable comparison operators. In the past, all comparisons have been done using the "=" sign. To be able to apply custom operators the addPropertyIndicator() has been added a third argument that takes the comparison operator.

The above sample shows the usage of the lesser than operator. As noted above, all types of operators can be used that are suitable for the database driver you use.

6. Enhancement of mapping and relation table

If the GenericORRelationMapper should be used for several applications or multiple application cases, sometimes it is good to split the configuration into several pieces. This makes configuration more generic and the mapper can thus be enabled to use specific parts of a greater database. To do so, you have two different choices: you create one configuration set for each application case or you create only a basic configuration, that is interessting for all application cases (e.g. user management) and use the

• addMappingConfiguration()
• addRelationConfiguration()

to extend the configuration for the special use cas. With these functions, any object and relation configuration files can be added. The following example shows to you, how the functions can be used to upgrade the scope of the mapper: The syntax of the object and relation configuration is the same as the default configuration described in the chapter 2.3. Object and relation definition. The additional object configuration file contains the following objects: and the newly added relations are

7. Notes

Hints on performance relevant issues can be found in the performance hacks chapter, the manual database setup is discussed in the manual database setup section. The source files of the usermanagement module can be used as an extended example.

Comments

QUICKNAVI

• All releases
• Roadmap
• Subversion repository
• Bugtracking
• Why APF?
• Articles
• Wiki
• RPM Installation HOWTO
• Partner sites
• APF auf SourceForge.net

• Imprint
• Contact
• Privacy policy
• Legal notice
• Security
• License

Adventure PHP Framework (APF) is a product developed by the APF Developer Team. It's released under the GNU Lesser General Public License (LGPGL)
Commercial use is permitted.

Copyright © 2004 - 2011 Adventure PHP Framework
All textual content on this site is protected by Copyright Law and may be used under the Terms of the GNU Free Documentation License (GNU FDL) See Legal notice for more information.