Configuring a Mapping (ELUG)
From Eclipsepedia
This section describes how to configure EclipseLink mapping options common to two or more mapping types. This table lists the types of EclipseLink mappings that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.
| If you are creating... | See... |
|---|---|
The Common Mapping Options table lists the configurable options shared by two or more EclipseLink mapping types.
For more information, see the following:
Configuring Common Mapping Options
This table lists the configurable options shared by two or more EclipseLink mapping types. In addition to the configurable options described here, you must also configure the options described for the specific mapping types (see Mapping Types), as shown in the Configuring EclipseLink Mappings table.
| Option to Configure | Workbench | Java |
|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
Configuring Read-Only Mappings
Mappings that are read-only will not be affected during insert, update, and delete operations.
Use read-only mappings when multiple attributes in an object map to the same fields in the database but only one of the mappings can write to the field.
You can also use read-only mappings with bi-directional many-to-many mappings to designate which mapping will be responsible for updating the many-to-many join table.
|
Note: The primary key mappings cannot not be read-only. |
Mappings defined for the write-lock or class indicator field must be read-only, unless the write-lock is configured not to be stored in the cache or the class indicator is part of the primary key.
Use read-only mappings only if specific mappings in a descriptor are read-only. If the entire descriptor is read-only, use the descriptor-level setting (see Configuring Read-Only Descriptors).
This table summarizes which mappings support this option.
| Mapping | Using the Workbench | Using Java |
|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
|
How to Configure Read-Only Mappings Using Workbench
To specify a mapping as read-only, use this procedure:
- Select the mapped attribute in the Navigator. Its properties appear in the Editor.
- Click the General tab. The General tab appears.
General Tab, Read-Only Option
Select the Read-Only option to set the mapping to be read-only and not affected during update and delete operations.
See Also
How to Configure Read-Only Mappings Using Java
Use the following DatabaseMapping methods to configure the read access of a mapping:
- readOnly–configures mapping read access to read-only;
- readWrite–configures mapping read access to read and write (default).
This example shows how to use these methods with a class that has a read-only attribute named phones.
Configuring Read Only Mappings in Java
// Map the phones attribute
phonesMapping.setAttributeName("phones");
// Specify read-only
phonesMapping.readOnly();
Configuring Indirection (Lazy Loading)
If indirection is not enabled, when EclipseLink retrieves a persistent object, it retrieves all of the dependent objects to which it refers. When you enable indirection (lazy loading) for an attribute mapped with a relationship mapping, EclipseLink uses an indirection object as a placeholder for the referenced object: EclipseLink defers reading the dependent object until you access that specific attribute. This can result in a significant performance improvement, especially if the application is interested only in the contents of the retrieved object rather than the objects to which it refers.
We strongly recommend using indirection for all relationship mappings. Not only does this allow you to optimize data source access, but it also allows EclipseLink to optimize the unit of work processing, cache access, and concurrency.
This table summarizes which mappings support this option.
| Mapping | Value Holder Indirection | Transparent Indirect Container Indirection | Proxy Indirection | How to Configure Indirection Using Workbench | How to Configure Indirection Using Java |
|---|---|---|---|---|---|
| | | | | | |
|
|
|
|
|
| |
|
|
|
|
|
| |
|
|
|
|
|
| |
|
|
|
|
|
| |
|
|
|
|
|
| |
|
|
|
|
|
| |
|
|
|
|
|
| |
|
|
|
|
|
| |
|
|
|
|
|
| |
| | | | | | |
|
|
|
|
|
| |
|
|
|
|
|
| |
| | | | | | |
|
|
|
|
|
| |
|
|
|
|
|
| |
| | | | | | |
|
|
|
|
|
|
In general, we recommend that you use value holder indirection for one-to-one mappings and transparent indirect container indirection for collection mappings. Enable indirection for transformation mappings if the execution of the transformation is a resource-intensive task (such as accessing a database, in a relational project).
When using indirection with EJB, the version of EJB and application server you use affects how indirection is configured and what types of indirection are applicable.
When using indirection with an object that your application serializes, you must consider the effect of any untriggered indirection objects at deserialization time.
For JPA entities or POJO classes that you configure for weaving, EclipseLink weaves value holder indirection for one-to-one mappings. If you want EclipseLink to weave change tracking and your application includes collection mappings (one-to-many or many-to-many), then you must configure all collection mappings to use transparent indirect container indirection only (you may not configure your collection mappings to use eager loading nor value holder indirection).
For more information, see the following:
- Indirection (Lazy Loading)
- Value Holder Indirection
- Transparent Indirect Container Indirection
- Indirection, Serialization, and Detachment
- Using Weaving
- Using EclipseLink JPA Weaving
How to Configure Indirection Using Workbench
To complete the indirection options on a mapping's General tab use this procedure:
- Select the mapped attribute in the Navigator. Its properties appear in the Editor.
- Click the General tab. The General tab appears.
General Tab, Indirection Options
- Select the Use Indirection option and indicate the type of indirection to use.
Use the following information to complete the Indirection fields on the tab:
| Field | Description |
|---|---|
| Use Indirection | Specify if this mapping uses indirection. |
| :ValueHolder |
Specify that the mapping uses Value Holder indirection. See Value Holder Indirection for more information. |
| :Proxy |
Specify that the mapping uses Proxy indirection. See Proxy Indirection for more information. |
See Also
How to Configure Indirection Using Java
When creating mappings through the Java API, all foreign reference mappings default to using value-holder indirection and all transformation mappings default to not using indirection.
To disable indirection use ForeignReferenceMapping method dontUseIndirection.
To enable value holder indirection, use ForeignReferenceMapping method useBasicIndirection.
To enable transparent container indirection, use one of the following CollectionMapping methods:
- useTransparentCollection
- useTransparentList
- useTransparentMap
- useTransparentSet
To enable proxy indirection, use ObjectReferenceMapping method useProxyIndirection.
This section provides additional information on the following:
- Configuring ValueHolder Indirection
- Configuring ValueHolder Indirection With Method Accessing
- Configuring IndirectContainer Indirection
- Configuring Proxy Indirection
Configuring Value Holder Indirection
Instances of org.eclipse.persistence.mappings.ForeignReferenceMapping and org.eclipse.persistence.mappings.foundation.AbstractTransformationMapping provide the useBasicIndirection method to configure a mapping to an attribute that you code with an org.eclipse.persistence.indirection.ValueHolderInterface between it and the real object.
If the attribute is of a Collection type (such as a Vector), then you can either use an IndirectContainer (see Configuring IndirectContainer Indirection) or define the ValueHolder in the constructor as follows:
addresses = new ValueHolder(new Vector());
This example illustrates the Employee class using ValueHolder indirection. The class definition conceals the use of ValueHolder within the existing getter and setter methods.
Class Using ValueHolder Indirection
public class Employee {
protected ValueHolderInterface address;
// Initialize ValueHolders in constructor
public Employee() {
address = new ValueHolder();
}
public Address getAddress() {
return (Address) this.addressHolder.getValue();
}
public void setAddress(Address address) {
this.addressHolder.setValue(address);
}
}
This example shows how to configure a one-to-one mapping to the address attribute.
Mapping Using ValueHolder Indirection
OneToOneMapping mapping = new OneToOneMapping();
mapping.useBasicIndirection();
mapping.setReferenceClass(Employee.class);
mapping.setAttributeName("address");
The application uses Employee methods getAddress and setAddress to access the Address object. Because basic indirection is enabled, EclipseLink expects the persistent fields to be of type ValueHolderInterface.
Configuring Value Holder Indirection with Method Accessing
If you are using ValueHolder indirection with method accessing (see Configuring Method or Direct Field Accessing at the Mapping Level), in addition to changing your attributes types in your Java code to ValueHolderInterface, you must also provide EclipseLink with two pairs of getter and setter methods:
- getter and setter of the indirection object that are registered with the mapping and used only by EclipseLink. They include a get method that returns an instance that conforms to ValueHolderInterface, and a set method that accepts one argument that conforms to the same interface;
- getter and setter of the actual attribute value used by the application.
This example illustrates the Employee class using ValueHolder indirection with method access. The class definition is modified so that the address attribute of Employee is a ValueHolderInterface instead of an Address, and appropriate getter and setter methods are supplied.
Class Using ValueHolder Indirection with Method Accessing
public class Employee {
protected ValueHolderInterface address;
// Initialize ValueHolders in constructor
public Employee() {
address = new ValueHolder();
}
// getter and setter registered with the mapping and used only by EclipseLink
public ValueHolderInterface getAddressHolder() {
return address;
}
public void setAddressHolder(ValueHolderInterface holder) {
address = holder;
}
// getter and setter methods used by the application to access the attribute
public Address getAddress() {
return (Address) address.getValue();
}
public void setAddress(Address theAddress) {
address.setValue(theAddress);
}
}
This example shows how to configure a one-to-one mapping to the address attribute.
Mapping Using ValueHolder Indirection with Method Accessing
OneToOneMapping mapping = new OneToOneMapping();
mapping.useBasicIndirection();
mapping.setReferenceClass(Employee.class);
mapping.setAttributeName("address");
mapping.setGetMethodName("getAddressHolder");
mapping.setSetMethodName("setAddressHolder");
The application uses Employee methods getAddress and setAddress to access the Address object. Because basic indirection is enabled, EclipseLink uses Employee methods getAddressHolder and setAddressHolder methods when performing persistence operations on instances of Employee.
Configuring Value Holder Indirection with JPA
When using indirection with JPA, if your application serializes any indirection-enabled (lazily loaded) entity (see Indirection, Serialization, and Detachment), then, to preserve untriggered indirection objects on deserialization, configure your client to use EclipseLink agent, as follows:
- Include the following JAR files (from <ECLIPSELINK_HOME>\jlib) in your client classpath:
- eclipselink.jar
- <your-application-persistence>.jar
- Add the following argument to the Java command line you use to start your client: -javaagent:eclipselink-agent.jar
You can also use static weaving. This will provide you with better error messages and will resolve merging issues.
|
Note: The use of static weaving will not affect serialization as it functions without static weaving enabled. |
Configuring IndirectContainer Indirection
Instances of org.eclipse.persistence.mappings.ForeignReferenceMapping and org.eclipse.persistence.mappings.foundation.AbstractTransformationMapping provide the useContainerIndirection method to configure a mapping to an attribute that you code with an org.eclipse.persistence.indirection.IndirectContainer between it and the real object.
Using an IndirectContainer, a java.util.Collection class can act as an EclipseLink indirection object: the Collection will only read its contents from the database when necessary (typically, when a Collection accessor is invoked). Without an IndirectContainer, all members of the Collection must be retrieved when the Collection attribute is accessed.
The following example illustrates the Employee class using IndirectContainer indirection with method access. Note that the fact of using indirection is transparent.
Class Using IndirectContainer Indirection
public class Employee {
protected List addresses;
public Employee() {
this.addresses = new ArrayList();
}
public List getAddresses() {
return this.addresses;
}
public void setAddresses(List addresses) {
this.addresses = addresses;
}
}
The following example shows how to configure a one-to-one mapping to the addresses attribute.
Mapping Using IndirectContainer Indirection
OneToOneMapping mapping = new OneToOneMapping();
mapping.useBasicIndirection();
mapping.setReferenceClass(Employee.class);
mapping.setAttributeName("addresses");
mapping.setGetMethodName("getAddresses");
mapping.setSetMethodName("setAddresses");
Configuring Proxy Indirection
This example illustrates an Employee to Address one-to-one relationship.
Classes Using Proxy Indirection
public interface Employee {
public String getName();
public Address getAddress();
public void setName(String value);
public void setAddress(Address value);
. . .
}
public class EmployeeImpl implements Employee {
public String name;
public Address address;
. . .
public Address getAddress() {
return this.address;
}
public void setAddress(Address value) {
this.address = value;
}
}
public interface Address {
public String getStreet();
public void setStreet(String value);
. . .
}
public class AddressImpl implements Address {
public String street;
. . .
}
In the preceding example, both the EmployeeImpl and the AddressImpl classes implement public interfaces (Employee and Address respectively). Therefore, because the AddressImpl class is the target of the one-to-one relationship, it is the only class that must implement an interface. However, if the EmployeeImpl is ever to be the target of another one-to-one relationship using transparent indirection, it must also implement an interface, as the following example shows:
Employee emp = (Employee) session.readObject(Employee.class);
System.out.println(emp.toString());
System.out.println(emp.getAddress().toString());
// Would print:
[Employee] John Smith
{ IndirectProxy: not instantiated }
String street = emp.getAddress().getStreet();
// Triggers database read to get Address information
System.out.println(emp.toString());
System.out.println(emp.getAddress().toString());
// Would print:
[Employee] John Smith
{ [Address] 123 Main St. }
Using proxy indirection does not change how you instantiate your own domain objects for an insert operation. You still use the following code:
Employee emp = new EmployeeImpl("John Smith");
Address add = new AddressImpl("123 Main St.");
emp.setAddress(add);
The following example illustrates an Employee to Address one-to-one relationship mapping.
Mapping Using Proxy Indirection
OneToOneMapping mapping = new OneToOneMapping();
mapping.useProxyIndirection();
mapping.setReferenceClass(Employee.class);
mapping.setAttributeName("address");
mapping.setGetMethodName("getAddress");
mapping.setSetMethodName("setAddress");
Configuring XPath
EclipseLink uses XPath statements to map the attributes of a Java object to locations in an XML document. When you create an XML mapping or EIS mapping using XML records, you can specify the XPath based on any of the following:
- Name
- Position
- Path and name
This table summarizes which mappings support this option.
| Mapping | Using the Workbench | How to Use Java |
|---|---|---|
| | | |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
| | | |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
1 When used with XML records only.
2 Supports the self XPath (".") so that the EclipseLink runtime performs all read and write operations in the parent's element and not an element nested within it (see Mappings and the jaxb:class Customization).
Before you can select an XPath for a mapping, you must associate the descriptor with a schema context (see Configuring Schema Context for an EIS Descriptoror Configuring Schema Context for an XML Descriptor).
For more information, see Mappings and XPath.
How to Configure XPath Using Workbench
Use this table to select the XPath for an XMl mapping or EIS mapping using XML records:
- Select the mapped attribute in the Navigator. Its properties appear in the Editor.
- If necessary, click the General tab. The General tab appears.
General Tab, XPath Options
XPath Options for Composite Object Mappings
- Click Browse and select the XPath to map to this attribute (see Choosing the XPath).
For an EIS composite object mapping using XML records or an XML composite object mapping, you can choose one of the following:
- Specify XPath: select the XPath to map to this attribute (see Choosing the XPath).
- Aggregate into parent element: select the self XPath (".") (see Self XPath) so that the EclipseLink runtime performs all read and write operations in the parent's element, and not an element nested within it (see Mappings and the jaxb:class Customization).
Choosing the XPath
From the Choose XPath dialog box, select the XPath and click OK. Workbench builds the complete XPath name.
Choose XPath Dialog Box
Configuring a Default Null Value at the Mapping Level
A default null value is the Java Object type and value that EclipseLink uses instead of null when EclipseLink reads a null value from a data source.
When you configure a default null value at the mapping level, EclipseLink uses it to translate in the following two directions:
- When EclipseLink reads null from the data source, it converts this null to the specified type and value.
- When EclipseLink writes or queries to the data source, it converts the specified type and value back to null.
This table summarizes which mappings support this option.
| Mapping | Using Workbench | Using Java |
|---|---|---|
| | | |
|
|
| |
|
|
| |
| | | |
|
|
| |
| | | |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
|
Note: A default null value must be an Object. To specify a primitive value (such as int), you must use the corresponding Object wrapper (such as Integer). |
You can also use EclipseLink to set a default null value for all mappings used in a session (see Configuring a Default Null Value at the Login Level).
How to Configure a Default Null Value at the Mapping Level Using Workbench
To configure a default null value for a mapping, use this procedure.
- Select the mapped attribute in the Navigator. Its properties appear in the Editor.
- Click the General tab. The General tab appears.
General Tab, Default Null Value Options
- Complete the Default Null Value fields on the tab.
Use the following information to complete the Default Null Value fields on the tab:
| Field | Description |
|---|---|
| Default Null Value | Specify if this mapping contains a default value in the event that the data source is null. If selected, you must enter both the Type and Value of the default. |
| Select the Java type of the default value. |
| Enter the default value. |
How to Configure a Default Null Value at the Mapping Level Using Java
To configure a mapping null value using Java API, use the AbstractDirectMapping method setNullValue.
For example:
// Defaults a null salary to 0 salaryMapping.setNullValue(new Integer(0));
Configuring Method or Direct Field Accessing at the Mapping Level
By default, EclipseLink uses direct access to access public attributes. Alternatively, you can use getter and setter methods to access object attributes when writing the attributes of the object to the database, or reading the attributes of the object from the database. This is known as method access.
Using private, protected or package variable or method access requires you to enable the Java reflect security setting. This is enabled by default in most application servers (see How to Set Security Permissions), but may need to be enabled explicitly in certain JVM configurations. If necessary, use the java.policy file to grant ReflectPermission to the entire application or the application's code base. For example:
grant{
permission java.lang.reflect.ReflectPermission;
};
We recommend using direct access whenever possible to improve performance and avoid executing any application-specific behavior while building objects.
This table summarizes which mappings support this option.
| Mapping | Using Workbench | Using Java |
|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
|
For information on configuring method accessing at the project level, see Configuring Method or Direct Field Access at the Project Level.
If you enable change tracking on a property (for example, you decorate method getPhone with @ChangeTracking) and you access the field (phone) directly, note that EclipseLink does not detect the change. For more information, see Using Method and Direct Field Access.
How to Configure Method or Direct Field Accessing Using Workbench
To complete the field access method for a mapping, use this procedure:
- Select the mapped attribute in the Navigator. Its properties appear in the Editor.
- Click the General tab. The General tab appears.
General Tab, Method Accessing Options
- Complete the Method Accessing fields on the tab.
Use the following information to complete the Method Accessing fields on this tab:
| Field | Description |
|---|---|
| Method Accessing | Specify if this mapping uses specific accessor methods instead directly accessing public attributes. By default, this option is not selected (that is, the mapping uses direct access). |
| Select a specific get method. |
| Select a specific set method. |
To change the default access type used by all new mappings, use the Defaults tab on the project Editor window. See Configuring Method or Direct Field Access at the Project Level for more information.
See Also
- Configuring Method or Direct Field Accessing at the Mapping Level
- Using Method and Direct Field Access
How to Configure Method or Direct Field Accessing Using Java
Use the following DatabaseMapping methods to configure the user-defined getters and setters that EclipseLink will use to access the mapped attribute:
For mappings not supported in Workbench, use the setGetMethodName and setSetMethodName methods to access the attribute through user-defined methods, rather than directly, as follows:
- setGetMethodName–set the String name of the user-defined method to get the mapped attribute;
- setSetMethodName–set the String name of the user-defined method to set the mapped attribute.
This example shows how to use these methods with a class that has an attribute phones and accessor methods getPhones and setPhones in an object-relational data type mapping.
Configuring Access Method in Java
// Map the phones attribute
phonesMapping.setAttributeName("phones");
// Specify access method
phonesMapping.setGetMethodName("getPhones");
phonesMapping.setSetMethodName("setPhones");
Configuring Private or Independent Relationships
In EclipseLink, object relationships can be either private or independent:
- In a private relationship, the target object is a private component of the source object. The target object cannot exist without the source and is accessible only through the source object. Destroying the source object will also destroy the target object.
- In an independent relationship, the source and target objects are public ones that exist independently. Destroying one object does not necessarily imply the destruction of the other.
|
Tip: EclipseLink automatically manages private relationships. Whenever an object is written to the database, any private objects it owns are also written to the database. When an object is removed from the database, any private objects it owns are also removed. Be aware of this when creating new systems, since it may affect both the behavior and the performance of your application. |
This table summarizes which mappings support this option.
| Mapping | Implicitly Private | Private or Independent | Using Workbench | Using Java |
|---|---|---|---|---|
| | | | | |
|
|
|