Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Creating a Mapping (ELUG)
You can create a database mapping using the Workbench or Java code. We recommend using the Workbench to create and manage your mappings.
For more information on creating mappings in Java, see EclipseLink API Reference.
For complete information on the various types of mapping that EclipseLink supports, see Mapping Types.
During development, you can create mappings individually (see Creating Mappings Manually During Development) or you can allow Workbench to automatically map all attributes (see Creating Mappings Automatically During Development).
For JPA projects, you can create mappings using JPA annotations (see Object Relational Mapping with EclipseLink JPA). JPA lets you create mappings automatically at run time.
After you create a mapping, you must configure its various options (see Configuring a Mapping).
Creating Mappings Manually During Development
You can manually create a mapping from each persistent field of a class to a data source using Workbench or Java code. We recommend that you use Workbench.
How to Create Mappings Manually During Development Using Workbench
To manually create a mapping using Workbench, use this procedure:
- Select a descriptor in the Navigator. Its properties appear in the Editor.
- On the Descriptor Info tab, associate the descriptor with its data source:
- For a relational project, in the Editor, select the table for this descriptor from the Associated Table menu. The Workbench populates this menu with tables from the database login you associated with your project. For more information, see Configuring Login Information at the Project Level.
- For an XML project, in the Editor, select the appropriate schema context for this descriptor by clicking on the Browse button next to the Schema Context field. The Workbench displays the schema context from the XML schema you associated with your project. For more information, see Using XML Schemas.
- In the Navigator, expand the descriptor to display its attributes.
- Select an attribute and do one of the following:
Continue with Configuring a Mapping to complete the mapping.
How to Create Mappings During Development Using Java
You create mappings using the constructor of the particular mapping type, as the following examples show:
Creating Relational One-to-One Mapping
org.eclipse.persistence.mappings.OneToOneMapping oom = new OneToOneMappiing();
Creating Relational Direct Collection Mapping
org.eclipse.persistence.mappings.DirectCollectionMapping dcm =new DirectCollectionMappiing();
Creating Object-Relational Data Type Structure Mapping
org.eclipse.persistence.mappings.structures.StructureMapping sm = new StructureMappiing();
Creating Object-Relational Data Type Array Mapping
org.eclipse.persistence.mappings.structures.ArrayMapping am = new ArrayMappiing();
Creating Mappings Automatically During Development
For relational database projects, the Workbench can automatically map class attributes to a similarly named database field. For example, these tools can map the attribute province to the database field PROV, the attribute street to the field ST, and the attribute postalCode to the field POSTAL_CODE.
The Automap function creates mappings only for unmapped attributes–it does not change previously defined mappings.
You can automatically map classes for an entire project or for specific classes or descriptors.
Note: Associating a descriptor with a database table (see Configuring Associated Tables) before using the Automap function can aid the automapper if it cannot guess the correct table for a class.
How to Create Mappings Automatically During Development Using Workbench
To automatically map all the descriptors in a project, right-click the project icon in the Navigator window and choose Automap from the context menu or choose Selected > Automap from the menu.
To automatically map a specific descriptor or attribute, choose the descriptor or attributes and right-click, and then select Automap from the context menu or choose Selected > Automap from the menu.
Creating Mappings to Oracle LOB Database Objects
In an Oracle Database, large amounts of binary or character data is stored as a BLOB (binary large object) or CLOB (character large object), respectively. Depending on the size of the LOB value and your Oracle Database database version, the value may be stored either inside or outside of the table, as follows:
- With Oracle8i version 8.1.6 and earlier, LOB values less than 4K are stored inline; values more than 4K are stored outside the table.
- With Oracle8i version 8.1.7 and later, LOB values less than 5.9K are stored inline; values more than 5.9K are stored outside the table.
A client application (such as EclipseLink) must use a LOB locator to write a LOB value, if the value is stored outside of the database. The Oracle JDBC OCI driver and server driver handle these LOB (large object) values differently than the Oracle JDBC thin driver.
How to Create Mappings to Oracle LOB Database Objects Using the Oracle JDBC Thin Driver
When using the Oracle JDBC thin driver, EclipseLink is responsible for acquiring the LOB locator before writing the value. You can use a type conversion mapping (see Configuring a Type Conversion Converter) to retrieve the locator during a commit operation.
Use this procedure to map LOB values using the Oracle JDBC thin driver:
- Use a type conversion mapping to map the attributes of a EclipseLink descriptor to a LOB value. The followiing figure shows a type conversion mapping to a BLOB value in Workbench. The Mapping a BLOB in Java Code example shows the Java code for the same mapping.
Mapping a BLOB in Workbench
Mapping a BLOB in Java Code
TypeConversionMapping pictureMapping = new TypeConversionMapping(); pictureMapping.set.AttributeName("picture"); pictureMapping.setFieldName("IMAGE.PICTURE"); pictureMapping.setFieldClassification(java.sql.Blob.class); descriptor.addMapping(pictureMapping);
- Acquire the DatabaseLogin from the session: DatabaseLogin login = session.getLogin();
- Configure a platform that provides locator support, as follows:
- For Oracle8i, use the org.eclipse.persistence.oraclespecific.Oracle8Platform class:
- For Oracle9i Database Server, use the org.eclipse.persistence.oraclespecific.Oracle9Platform class:
- Oracle Database 10g, use the org.eclipse.persistence.oraclespecific.Oracle10Platform class:
Selecting Database Platform in Workbench
If you are using the Workbench, you can unmap any mapped attribute.
How to Remove Mappings Using Workbench
To unmap an attribute (that is, remove its mapping), use this procedure:
To unmap all the attributes in a descriptor or Java package, use this procedure:
How to Remove Mappings Using Java
Use the ClassDescriptor method removeMappingForAttributeName to unmap an attribute.