You use a persistence mapper to store and retrieve objects from an MDriven model; this page is for developers choosing or understanding the storage layer used by an application.

What a persistence mapper does

A persistence mapper is the MDriven Framework component that transforms in-memory modeled objects into persistent storage and transforms stored data back into objects. With a relational mapper, it generates the database operations needed to read and write the modeled data.

For example, if your model contains a Customer class with a Name attribute and related Order objects, the persistence mapper is responsible for representing that object data in the selected storage mechanism. Your application works with the model objects; the mapper handles the storage representation.

A persistence mapper is part of MDriven's object-relational mapping (ORM) support when the target is a relational database. Read OR Mapping for the general object-to-relational-database concepts.

Where the mapper runs

In an application that connects directly to a database, the application uses the MDriven Framework and its persistence mapper to communicate with the database. The mapper generates the queries used for reading and writing data.

Situation	Role of the persistence mapper
Direct database connection	The application uses the mapper to communicate with its database storage.
MDrivenServer-based deployment	MDrivenServer provides the persistence-side settings described as defaults in Working with Code and Persistence Mapping. Do not assume that the SQL-database-specific configuration described there applies to XML persistence mappers.

Persistence mappers are also a place where persistence-side behavior can be implemented. For example, MDrivenServer can use database-side administrative information to track changes for cache invalidation. This concerns how changed stored data is observed by clients; it does not change the model that you work with in the application.

Built-in persistence mapper targets

MDriven includes persistence mappers for the following targets.

Mapper target	Use
XML file	Persist modeled objects in an XML file.
SQL Server	Persist modeled objects in a Microsoft SQL Server database. See SQL Server.
MySQL	Persist modeled objects in a MySQL database.
SQLite	Persist modeled objects in a SQLite database.

Choose a mapper that matches the storage technology your application uses. The mapper owns the translation between model objects and that target's storage format; application code should work against the model rather than duplicate that translation.

How mapping relates to your model

The model is the source for persistence structure. A class, its attributes, and its associations provide the information from which MDriven derives persistence mapping for relational storage.

For example:

• A modeled Customer class contributes stored customer data.
• A Name attribute contributes a value that must be stored and restored with a customer.
• An association from Customer to Order contributes relationship information so that a customer's orders can be restored as related objects.

The persistence mapper does not make an arbitrary database schema independent of the model. When the model changes, MDriven compares mapping information to determine the database-mapping changes needed during database evolution.

Mapping information during database evolution and runtime

For SQL database persistence, MDriven can generate the mapping when the database is evolved. You normally do not need to generate and maintain a mapping XML file yourself.

The mapping process uses three distinct roles:

Role	Purpose
NewMappingProvider	Describes how the mapping should look after the database is evolved.
OldMappingProvider	Describes the mapping in the current database.
RuntimeMappingProvider	Supplies the mapping used while the application accesses the database at runtime.

MDriven compares the old mapping with a newly generated mapping to determine the detailed effects of model changes on the database mapping. For the SQL-specific workflow, including generating default mapping XML when you need to inspect it, see Working with Code and Persistence Mapping.

Attribute-level mapper overrides

MDriven has standard persistence behavior for modeled attribute types. You can override the mapper for an individual attribute or select from supplied mappers, but this is a specialized compatibility technique.

For example, MDriven's standard enum storage is the enum's text representation. A legacy database may instead store the enum as an integer. An attribute-level enum mapper can address that storage requirement, but query parameters do not have the attribute context. MDriven therefore resolves a parameter mapper by first looking for one named after the parameter type and then, for enum parameters, one named Enum.

This distinction matters when a query compares an enum attribute with an enum parameter: changing only the attribute mapper may leave the parameter using a different mapper. Custom per-attribute mappers can also prevent generic tools, including MDriven Prototyping and MDrivenServer, from functioning correctly because those tools use MDriven's standard mapping behavior.

Follow Using other than standard Persistence Mappers per attribute for the complete enum example, mapper-resolution order, and required configuration choices.

Scope and limitations

This page describes MDriven persistence mappers and their role in storing modeled objects. It does not describe every persistence technology or storage architecture.

• MDriven does not support NoSQL databases unless you provide a persistence mapper for the required NoSQL database. See Persistence.
• The SQL-database mapping details in Working with Code and Persistence Mapping do not apply to XML persistence mappers.
• Do not use a custom attribute mapper as a general replacement for standard mapping. Use it when you must meet a specific storage requirement, such as an established legacy representation.

See also

• Documentation:Persistence
• Documentation:OR Mapping
• Documentation:Working with Code and Persistence Mapping
• Documentation:Using other than standard Persistence Mappers per attribute
• Documentation:SQL Server

Persistence mapping and existing databases

MDriven persistence mapping creates a relationship between an object-oriented model and a storage target. For relational databases, classes are mapped to database tables and attributes are mapped to table columns. MDriven translates object-oriented operations into SQL statements for the database. Persistence mappers

Built-in persistence mappers

MDriven documentation lists the following built-in persistence mappers:

• XML file
• SQL Server
• MySQL
• SQLite

Persistence mappers

Reverse engineering an existing database

MDriven can reverse engineer a database schema into a model. In MDriven Designer, right-click the package, choose Functions, and select Reverse Database. Use Analyze db to inspect the schema.

A database schema may not express every relationship needed by the model. For example, SQL joins can exist without explicit primary-key or foreign-key definitions. When schema information is incomplete, you can add missing classes, primary-key information, and associations manually. The Reverse worker tool can be used to inspect tables and columns without clearing the existing package content. Reverse Engineer a Database

Specialized attribute mapping

You can create a persistence mapper for an individual attribute or select from supplied mappers. This is intended for specialized cases, including compatibility with legacy databases.

For enums, MDriven's documented standard is to store the enum value as its text representation. A legacy database may instead store enum values as integers. An attribute can use an integer enum mapper, but query parameters need compatible mapper resolution as well; otherwise a query can fail because the database receives an incompatible value type.

Attribute-level mapper specialization can prevent generic tools, including MDriven Prototyping and MDriven Server, from functioning properly because those tools use the standard mapping. Using other than standard Persistence Mappers per attribute

Review considerations

• Confirm that the selected persistence mapper matches the intended storage target.
• When reverse engineering, review the resulting model for missing classes, attributes, primary keys, and associations.
• Use attribute-level mapper overrides only for confirmed compatibility requirements.
• Test queries that use parameters when an attribute uses a nonstandard persistence mapper.

See also

• OR Mapping
• Reverse Engineer a Database
• Using other than standard Persistence Mappers per attribute