EclipseLink/Examples/JPA/ORMMappings

In an EclipseLink application, you persist objects by storing, or mapping, information about them in a relational database. A mapping has three components:

• The object being mapped
• The descriptor, or object-to-database table translator
• The database table or tables in which you stored the object

Although EclipseLink supports more complex mappings, most EclipseLink classes map to a single database table that defines the type of information available in the class. Each object instantiated from a given class maps to a single row comprising the object’s attributes, plus an identifier (the primary key) that uniquely identifies the object.

Mappings are defined either in a Project Class or Project XML file that is loaded from a sessions.xml file.

Direct Mappings

Use direct mapping to map primitive object attributes, or nonpersistent regular objects, such as the JDK classes. For example, use a direct-to-field mapping to store a String attribute in a VARCHAR field. You can map entity bean attributes using direct mappings without any special considerations.

All direct mappings include optional setGetMethodName() and setSetMethodName() messages. These messages allow EclipseLink to access the attribute through user-defined methods, rather than directly through the attribute.

Creating a Direct-to-Field Mapping in Java and Registering It with the Descriptor

// Create a new mapping and register it with the descriptor.
DirectToFieldMapping mapping = new DirectToFieldMapping();
mapping.setAttributeName("city");
mapping.setFieldName("CITY");
descriptor.addMapping(mapping);

Creating a Mapping that Uses Method Access

This mapping example assumes that the persistent class has getCity() and setCity() methods defined.

// Create a new mapping and register it with the descriptor.
DirectToFieldMapping mapping = new DirectToFieldMapping();
mapping.setAttributeName("city");
mapping.setFieldName("CITY");
mapping.setGetMethodName("getCity");
mapping.setSetMethodName("setCity");
descriptor.addMapping(mapping);

Relationship Mappings

Relationship mappings define how persistent objects reference other persistent objects. EclipseLink supports several relationship mapping types. EclipseLink mappings are defined in the org.eclipse.persistence.mappings package. Some of those mappings are defined here, for more info on the other supported mappings please visit their implementations.

One-To-One Mappings

One-to-one mappings represent simple pointer references between two objects. One-to-one mappings for relationships between entity beans, or between an entity bean and a regular Java object, where the entity bean is the source and the regular Java object is the target of the relationship.

Creating a Simple One-to-One Mapping and Registering It with the Descriptor

// Create a new mapping and register it with the descriptor.
OneToOneMapping oneToOneMapping = new OneToOneMapping();
oneToOneMapping.setAttributeName("address");
oneToOneMapping.setReferenceClass(Address.class);
oneToOneMapping.setForeignKeyFieldName("ADDRESS_ID");
descriptor.addMapping(oneToOneMapping);

Implementing a Bidirectional Mapping Between Two Classes that Reference Each Other

If the mapping has a bidirectional relationship in which the two classes in the relationship reference each other with one-to-one mappings, then set up the foreign key information as follows:

• One mapping must send the setForeignKeyFieldName() message.
• The other must send the setTargetForeignKeyFieldName() message.

The foreign key is stored in the Policy’s table referencing the composite primary key of the Carrier.

// In the Policy class, which will hold the foreign key, create the mapping that references the Carrier class.
OneToOneMapping carrierMapping = new OneToOneMapping();
carrierMapping.setAttributeName("carrier");
carrierMapping.setReferenceClass(Carrier.class);
carrierMapping.addForeignKeyFieldName("INSURED_ID", "CARRIER_ID");
carrierMapping.addForeignKeyFieldName("INSURED_TYPE", "TYPE");
descriptor.addMapping(carrierMapping);

// In the Carrier class, create the mapping that references the Policy class.
OneToOneMapping policyMapping = new OneToOneMapping();
policyMapping.setAttributeName("masterPolicy");
policyMapping.setReferenceClass(Policy.class);
policyMapping.addTargetForeignKeyFieldName("INSURED_ID", "CARRIER_ID");
policyMapping.addTargetForeignKeyFieldName("INSURED_TYPE", "TYPE");
descriptor.addMapping(policyMapping);

One-To-Many Mappings

One-to-many mappings represent the relationship between a single source object and a collection of target objects.

Creating a Simple One-to-Many Mapping and Registering It with the Descriptor

// In the Employee class, create the mapping that references the Phone class.
oneToManyMapping = new OneToManyMapping();
oneToManyMapping.setAttributeName("phoneNumbers");
oneToManyMapping.setReferenceClass(PhoneNumber.class);
oneToManyMapping.setTargetForeignKeyFieldName("EMPID");
descriptor.addMapping(oneToManyMapping);

// In the Phone class, which will hold the foreign key, create the mapping that references the Employee class.
OneToOneMapping oneToOneMapping = new OneToOneMapping();
oneToOneMapping.setAttributeName("owner");
oneToOneMapping.setReferenceClass(Employee.class);
oneToOneMapping.setForeignKeyFieldName("EMPID");
descriptor.addMapping(oneToOneMapping);

Direct Collection Mappings

Direct collection mappings store collections of Java objects that are not EclipseLink-enabled. Direct collections usually store Java types, such as strings.

Creating a Simple Direct Collection Mapping

DirectCollectionMapping directCollectionMapping = new DirectCollectionMapping();
directCollectionMapping.setAttributeName ("responsibilitiesList");
directCollectionMapping.setReferenceTableName ("RESPONS");
directCollectionMapping.setDirectFieldName("DESCRIP");
directCollectionMapping.setReferenceKeyFieldName ("EMP_ID");
directCollectionMapping.useCollectionClass (Vector.class); // the default
descriptor.addMapping(directCollectionMapping);

Many-To-Many Mappings

Many-to-many mappings represent the relationships between a collection of source objects and a collection of target objects. This requires an intermediate table that manages the associations between the source and target records.

Creating a Simple Many-to-Many Mapping and Registering It with the Descriptor

// In the Employee class, create the mapping that references the Project class.
ManyToManyMapping manyToManyMapping = new ManyToManyMapping();
manyToManyMapping.setAttributeName("projects");
manyToManyMapping.setReferenceClass(Project.class);
manyToManyMapping.setRelationTableName("PROJ_EMP");
manyToManyMapping.setSourceRelationKeyFieldName ("EMPID");
manyToManyMapping.setTargetRelationKeyFieldName ("PROJID");
descriptor.addMapping(manyToManyMapping);