Basic Mappings

Direct-to-Field Mappings

The direct-to-field mappings are instances of the DirectToFieldMapping class and require the following elements:

• The attribute being mapped, set by sending the setAttributeName() message

• The field to store the value of the attribute, set by sending the setFieldName() message

The Descriptor class provides the addDirectMapping() method that creates a new DirectToFieldMapping, sets the attribute and field name parameters, and registers the mapping with the descriptor.

You create a direct-to-field mapping in one of two ways:

• Map one attribute to one field

• Map more than one attribute to one field (to create different views of the same field)

Mapping an Attribute

Example 3-1 and Example 3-2 illustrate common ways of mapping one attribute to one field.

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

// 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);

// Alternate method which does the same thing.
descriptor1.addDirectMapping("city", "CITY");
descriptor2.addDirectMapping("city", "getCity", "setCity", "CITY");

Mapping Multiple Attributes to the Same Field

You must pay special attention when you map more than one attribute to the same field in which some mappings are read-only and some are not. By default, with DatabaseLogin.setShouldOptimizeDataConversion(true)—OracleAS TopLink uses the data type of the attribute of the last writable mapping for all subsequent read-only mappings. In this context, "last" is relative to the order in which the attributes are declared in the mapped class.

This behavior can lead to a loss of precision.

Note the following example: First you want to map the class that appears in Example 3-4 to create two different views of the same, underlying database field. Then you want attribute view1 to represent the database field as an integer and attribute view2 to represent the same database field as a double. Finally, you want attribute view1 to be writable and attribute view2 to be read-only.

public class ClassToMap
{
    private String name;
    private long id;
    private int view1; 
    private double view2; // READONLY 
    ... 
}

<database-mapping>
    <attribute-name>view1</attribute-name>
    <read-only>false</read-only>
    <field-name>CLASSTOMAP.NUM_VIEW</field-name>
    <type>oracle.toplink.mappings.DirectToFieldMapping</type>
</database-mapping>

<database-mapping>
    <attribute-name>view2</attribute-name>
    <read-only>true</read-only>
    <field-name>CLASSTOMAP.NUM_VIEW</field-name>
    <type>oracle.toplink.mappings.DirectToFieldMapping</type>
</database-mapping>

Session sess = SessionManager.getManager().getSession("test"); 
Vector v = sess.readAllObjects(ClassToMap.class) 

• Disable data conversion optimization with DatabaseLogin.setShouldOptimizeDataConversion(false).

• Map the attribute with the highest precision as writable.

To change your design so that view1 is read-only and view2 is writable, proceed as follows:

<database-mapping>
    <attribute-name>view1</attribute-name>
    <read-only>true</read-only>
    <field-name>CLASSTOMAP.NUM_VIEW</field-name>
    <type>oracle.toplink.mappings.DirectToFieldMapping</type>
</database-mapping>

<database-mapping>
    <attribute-name>view2</attribute-name>
    <read-only>false</read-only>
    <field-name>CLASSTOMAP.NUM_VIEW</field-name>
    <type>oracle.toplink.mappings.DirectToFieldMapping</type>
</database-mapping>

For more information about the available methods for DirectToFieldMapping, see the Oracle Application Server TopLink API Reference.

Type Conversion Mappings

Type conversion mappings and instances of the TypeConversionMapping class require the following elements:

• The attribute mapped, set by sending the setAttributeName() message

• The field to store the value of the attribute, set by the setFieldName() message

• The Java type stored in the attribute, set by sending the setAttributeClassification() message

• The database type to be written, set by sending the setFieldClassification() message

// Create a new mapping and register it with the descriptor.
TypeConversionMapping typeConversion = new TypeConversionMapping();
typeConversion.setFieldName("J_DAY");
typeConversion.setAttributeName("joiningDate");
typeConversion.setFieldClassification(java.sql.Date.class);
typeConversion.setAttributeClassification(java.util.Date.class);
descriptor.addMapping(typeConversion);

Object Type Mappings

Object type mappings are instances of the ObjectTypeMapping class and require the following elements:

• The attribute mapped, set by sending the setAttributeName() message

• The field to store the value of the attribute, set by the setFieldName() message

• A set of values and their conversions, added by sending the addConversionValue() message

The following methods are useful in a legacy environment or when you want to change the values of the fields:

• addToAttributeOnlyConversionValue(Object fieldValue, Object attributeValue): This is a one-way mapping from the field to the attribute. Use this mapping if multiple database values map to the same object value. When written to the database, the value entered by addConversionValue(Object fieldValue, Object attributeValue) is used, and the original values in the database change.

• setDefaultAttributeValue Object defaultAttributeValue): Substitutes the default value for any unmapped value retrieved from the database. When writing to the database, the value entered by addConversionValue(Object fieldValue, Object attributeValue) is used, and the original values in the database change.

// Create a new mapping and register it with the descriptor.
ObjectTypeMapping typeMapping = new ObjectTypeMapping();
typeMapping.setAttributeName("gender");
typeMapping.setFieldName("GENDER");
typeMapping.addConversionValue("M", "Male");
typeMapping.addConversionValue("F", "Female");
typeMapping.setNullValue("F");
descriptor.addMapping(typeMapping);

Relationships and Entity Beans

Persistent objects use relationship mappings to store references to instances of other persistent classes. The appropriate mapping type is selected based on the cardinality of the relationship (for example, a one-to-one or one-to-many). Entity beans can have relationships to regular Java objects, other entity beans, or both.

http://java.sun.com/products/ejb/
http://java.sun.com/products/ejb/docs.html
http://java.sun.com/j2ee/white/index.html

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, in which, entity bean is the source and the regular Java object is the target of the relationship.

One-to-one mappings are instances of the OneToOneMapping() class and require the following elements:

• The attribute mapped, set by sending the setAttributeName() message

• The reference class, set by sending the setReferenceClass() message

• The foreign key information, normally specified by sending the setForeignKeyFieldName() message and passing the foreign key field from the source table that references the primary key of the target table

  
  

  Note: If the target primary key is composite, send the addForeignKeyFieldName() message for each of the foreign fields and target primary key fields that make up the relationship.

  
  

// 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);

// 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);

Aggregate Object Mappings

Two objects are related by aggregation if there is a strict one-to-one relationship between the objects, and if all the attributes of the second object can be retrieved from the same tables as the owning object. So if the target (or child) object exists, then the source (or parent) object must also exist. The child object cannot exist without its parent.

Aggregate object mappings are instances of the AggregateObjectMapping class. This mapping relates to an attribute in each of the parent classes. Aggregate object mappings require the following information:

• The attribute mapped, set by sending the setAttributeName() message

• The target (child) class, set by sending the setReferenceClass() message

Aggregate object mappings also require the following modifications to the target class descriptor:

• Send the descriptorIsAggregate() message to the descriptor to indicate that all information must come from the rows of its parent object's rows

• Include no table or primary key information for the target class

By default, the mapping allows null references to its target class, so it does not create an instance of the target object. To prevent a parent from having a null reference, send the dontAllowNull() message, which results in an instance of the child with its attributes set to null.

// Create a new mapping and register it with the source descriptor.
AggregateObjectMapping aggregateMapping = new AggregateObjectMapping();
aggregateMapping.setAttributeName("employPeriod");
aggregateMapping.setReferenceClass(Period.class);
descriptor.addMapping(aggregateMapping);

// Create a descriptor for the aggregate class. The table name and primary key // are not specified in the aggregate descriptor.
Descriptor descriptor = new Descriptor();
descriptor.setJavaClass(Period.class);
descriptor.descriptorIsAggregate();

// Define the attribute mappings or relationship mappings.
descriptor.addDirectMapping("startDate", "START_DATE");
descriptor.addDirectMapping("endDate", "END_DATE");
return descriptor;

// Create a new mapping and register it with the parent descriptor.
AggregateObjectMapping aggregateMapping = new AggregateObjectMapping();
aggregateMapping.setAttributeName("projectPeriod");
aggregateMapping.setReferenceClass(Period.class);
aggregateMapping.addFieldNameTranslation("S_DATE", "START_DATE");
aggregateMapping.addFieldNameTranslation("E_DATE", "END_DATE");
descriptor.addMapping(aggregateMapping);

One-to-Many Mappings

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

For more information about one-to-many mappings, see the Oracle Application Server TopLink Mapping Workbench User's Guide.

One-to-many mappings are instances of the OneToManyMapping class and require the following elements:

• The attribute being mapped, set by sending the setAttributeName() message

• The reference class, set by sending the setReferenceClass() message

• The foreign key information, which you specify by sending the setTargetForeignKeyFieldName() message and passing a field in the target object's associated table that refers to the primary key in the owning object's table

  
  

  Note: If the target primary key is composite, send the addTargetForeignKeyFieldName() message for each of the fields that make up the key.

  
  

• A one-to-one mapping in the target class back to the source class

  For more information, see "One-to-One Mappings" .

  
  

  Note: Because indirection is enabled by default for a one-to-many mapping, the attribute must implement ValueHolderInterface.

  
  

// 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);

• useBasicIndirection(): implements OracleAS TopLink valueholder indirection.

• useTransparentCollection(): if you use transparent indirection, this element places a special collection in the source object's attribute.

• dontUseIndirection(): implements no indirection.

For more information about the available methods for OneToManyMapping, see the Oracle Application Server TopLink API Reference.

Aggregate Collections

Aggregate collection mappings represent the aggregate relationship between a single-source object and a collection of target objects. Unlike the OracleAS TopLink one-to-many mappings, no back reference is required for the aggregate collection mappings because the foreign key relationship is resolved by the aggregation.

Aggregate collection mappings require a target table for the target objects.

To implement an aggregate collection mapping:

• The descriptor of the target class must declare itself as an aggregate collection object. Unlike the aggregate object mapping, in which the target descriptor does not have a specific table to associate with, there must be a target table for the target object.

• The descriptor of the source class must add an aggregate collection mapping that specifies the target class.

// In the PolicyHolder class, create the mapping that references the Phone class
AggregateCollectionMapping phonesMapping = new AggregateCollectionMapping();
phonesMapping.setAttributeName("phones");
phonesMapping.setGetMethodName("getPhones");
phonesMapping.setSetMethodName("setPhones");
phonesMapping.setReferenceClass("Phone.class");
phonesMapping.dontUseIndirection();
phonesMapping.privateOwnedRelationship;
phonesMapping.addTargetForeignKeyFieldName("INS_PHONE.HOLDER_SSN","HOLDER.SSN");
descriptor.addMapping(phonesMapping);

Direct Collection Mappings

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

Direct collection mappings are instances of the DirectCollectionMapping class and require the following elements:

• The attribute mapped, set by sending the setAttributeName() message

• The database table that holds the values to be stored in the collection, set by sending the setReferenceTableName() message

• The field in the reference table from which the values are read and placed into the collection; this is called the direct field and is set by sending the setDirectFieldName() message

• The foreign key information, which you specify by sending the setReferenceKeyFieldName() message and passing the name of the field that is a foreign reference to the primary key of the source object

  
  

  Note: If the target primary key is composite, send the addReferenceKeyFieldName() message for each of the fields that make up the key.

  
  

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);

• useBasicIndirection(): implements OracleAS TopLink valueholder indirection.

• useTransparentCollection(): If you use transparent indirection, this element places a special collection in the attribute of the source object.

• dontUseIndirection(): implements no indirection.

For more information about the available methods for DirectCollectionMapping, see the Oracle Application Server TopLink API Reference.

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.

Many-to-many mappings are instances of the ManyToManyMapping class and require the following elements:

• The attribute mapped, set by sending the setAttributeName() message

• The reference class, set by sending the setReferenceClass() message

• The relation table, set by sending the setRelationTableName() message

• The foreign key information (for noncomposite target primary keys), which you specify by sending the setSourceRelationKeyFieldName() and setTargetRelationKeyFieldName() messages

• The foreign key information if the source or target primary keys are composite, which you specify by sending the addSourceRelationKeyFieldName() or addTargetRelationKeyFieldName() messages

// 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);

• useBasicIndirection(): implements OracleAS TopLink valueholder indirection.

• useTransparentCollection(): If you use transparent indirection, this element places a special collection in the attribute of the source object.

• dontUseIndirection(): implements no indirection.

For more information about the available methods for ManyToManyMapping, see the Oracle Application Server TopLink API Reference.

Valueholder Indirection

Valueholder indirection is a native OracleAS TopLink feature that implements the OracleAS TopLink ValueHolderInterface on your objects to achieve indirection. A valueholder represents an instance of a related class and stores the information necessary to retrieve the object it represents from the database. If the application does not access the valueholder, the replaced object is never read from the database.

If you use method access, the get and set methods specified for the mapping must access an instance of ValueHolderInterface, rather than the object that the valueholder is referencing. To obtain the object represented by the valueholder, use the getValue() and setValue() methods of the ValueHolderInterface class. You can hide the getValue and setValue methods of the ValueHolderInterface inside get and set methods.

You can change the attribute types in the class editor—if you do this, remember to also change the attribute types in your Java code, as well as their accessor methods.

If the instance variable returns a vector instead of an object, define the valueholder in the constructor as follows:

addresses = new ValueHolder(new Vector());

The application uses the getAddress() and setAddress() methods to access the Address object. When you use indirection, OracleAS TopLink uses the getAddressHolder() and setAddressHolder() methods to save instances to and retrieve instances from the database.

// Initialize ValueHolders in Employee Constructor
public Employee() {
    address = new ValueHolder();
}
protected ValueHolderInterface address;

// 'Get' and 'Set' accessor methods registered with the mapping and used by 
// OracleAS TopLink.
public ValueHolderInterface getAddressHolder() {
    return address;
}
public void setAddressHolder(ValueHolderInterface holder) {
    address = holder;
}

// Get and Set accessor methods used by the application to access the attribute.
public Address getAddress() {
    return (Address) address.getValue();
}
public void setAddress(Address theAddress) {
    address.setValue(theAddress);
}

Proxy Indirection

Proxy indirection enables you to use dynamic proxy objects as stand-ins for a defined interface. You can configure all the following mapping types to use proxy indirection, which gives you the benefits of indirection without the need to include OracleAS TopLink classes in your domain model:

• One-to-one mapping

• Variable one-to-one mapping

• Reference mapping

• Transformation mapping

Note that all these mapping types map one-to-one relationships.

The useProxyIndirection()method indicates that OracleAS TopLink must use proxy indirection for the current mapping. When you read the source object from the database, OracleAS TopLink creates a proxy for the target object and uses it in place of the target object. When you call any method other than toString() on the proxy, OracleAS TopLink reads the target object from the database.

Proxy indirection is not directly supported in OracleAS TopLink Mapping Workbench. To implement proxy indirection, use the useProxyIndirection method in an amendment method.

Proxy indirection does not use the OracleAS TopLink ValueholderInterface, and nor are target objects typed as ValueHolderInterface. Instead, to implement proxy indirection, make changes to both the object model and the descriptor mapping for the source object.

To use proxy indirection, your domain model must satisfy the following criteria:

• The target class of the one-to-one relationship must implement a defined public interface.

• The one-to-one attribute on the source class must be of the interface type defined in the target class.

• If you employ method accessing, the get() and set() methods must use the interface.

In the descriptor, invoke the useProxyIndirection method in the source object descriptor that defines mapping between the source and target objects.

//Step 1. Define an interface "IAddress" for "Address"
public interface IAddress {
    public String getCity();
    public void setCity(String aCity);
}

// Step 2. Implement this interface on the "Address" class
public class Address implements IAddress {
    String city;
    public String getCity() { return city;}
    public void setCity(String aCity){city = aCity;}

    public Address() {
    ...
    }

}

//Step 3. Declare the attribute "address" as interface "IAddress" on the Employee.
public class Employee {
    public BigInteger id;
    public String firstName;
    public String lastName; 
    public IAddress address;

    //Step 4. Configure the Set and get methods "getAddress()", "setAddress()" to use 
    // interface IAddress"

    // get and set methods for instance variables
    public IAddress getAddress() {return this.address;}
    public void setAddress (IAddress newAddress) {this.address=newAddress;}


    public Employee() {
    ...
    }
}

//Step 5. The mapping between Employee and Address must invoke the useProxyIndirection() 
// API. Also, the target class, which implements the interface, must be passed to the 
// setReferenceClass() method as the argument.

//Define the 1:1 mapping, and specify that ProxyIndirection should be used
OnetoOnemapping addressMapping = new OneToOneMapping();
addressMapping.setAttributeName("address");
addressMapping.setReferenceClass(Address.class);
addressMapping.setForeignKeyFieldName("ADDRESS_ID");
addressMapping.setSetMethodName("setAddress");
addressMapping.setGetMethodName("getAddress");
addressMapping.useProxyIndirection();
descriptor.addMapping(addressMapping);

UnitOfWork uow = session.acquireUnitOfWork();
Employee emp = (Employee)session.readObject(Employee.class);

// Register the source object
Employee empClone = (Employee)uow.registerObject(emp); 

// All of source object's relationships are cloned when source object is cloned
Address addressClone = empClone.getAddress();
addressClone.setCity("Toronto"); 

Transparent Indirection

Transparent indirection enables you to declare any relationship attribute of a persistent class that holds a collection of related objects as a java.util.Collection, java.util.Map, java.util.Vector, or java.util.Hashtable. OracleAS TopLink uses an indirection object that implements the appropriate interface and performs just-in-time reading of the related objects.

When using transparent indirection, you do not have to declare the attributes as ValueHolderInterface.

You can specify transparent indirection from OracleAS TopLink Mapping Workbench. Newly created collection mappings use transparent indirection by default if their attribute is not a ValueHolderInterface.

Do not include OracleAS TopLink classes in the domain class for transparent indirection.

Choosing Your Indirection Type

Although there are no universal rules for the use of indirection, the following guidelines illustrate when indirection is beneficial, and help you choose the appropriate type of indirection.

Indirection and EJBs

OracleAS TopLink offers mechanisms to implement indirection for relationships between EJBs. As with regular Java objects, these mechanisms include:

• The use of indirection objects

• Transparent indirection

• Proxy indirection

The Oracle Application Server TopLink Mapping Workbench User's Guide describes these indirection mechanisms.

Note the following guidelines when you use indirection with EJBs, particularly when you migrate objects between client and server:

• Uninstantiated valueholders (indirection objects) do not survive serialization. If you send a valueholder from the server to the client, it will no longer function unless it has been previously triggered.

• You can use valueholders in bean-to-bean relationships and bean-to-object relationships, but avoid them in relationships in which the source is likely to be serialized to the client.

• Do not serialize collections that use untriggered transparent indirection to the client application. These collections do not function if they are serialized.

• Proxy indirection is unavailable for relationships whose target is an entity bean. The proxies used for this kind of indirection interfere with the RMI stubs and skeletons generated for the entity. If proxies exist, instantiate them before serializing to the client.

• Use valueholders for bean-to-bean relationships and for bean-to-object relationships. You can also use transparent indirection for collections that are not exposed to the client application.

Serialization and Indirection

A common cause of problems with serialization is the use of indirection in serialized objects. Indirection valueholders rely on the OracleAS TopLink session for context (mapping information, JDBC connectivity, and so on); however, because the OracleAS TopLink session is stored in the object in a transient variable, it does not survive serialization, leaving the serialized valueholders with no context and no way to resolve the links to the data they represent. As a result, when you marshall the object for serialization, the values held by valueholders are replaced with a null value. If the application on the receiving JVM invokes the valueholder, the result is a null pointer exception.

Note that no null pointer exception is thrown during the serialization process, nor does OracleAS TopLink prevent you from serializing an untriggered valueholder. This enables you to serialize objects and retain the efficiency advantages of indirection if you know that the receiving JVM does not use the valueholders.

protected void writeObject(ObjectOutputStream out) throws IOException

Merging Clones on Deserialization

Unmarshalling a serialized object always occurs in the context of a Unit of Work when you integrate changes made outside of the JVM with the affected objects in the OracleAS TopLink application. Several options are available for the merge:

• Merge only the direct attributes of the object being read: Use the shallowMergeClone(java.lang.Object rmiClone) method to capture changes in the deserialized object only. Use this option when you know that changes to the object do not extend to related objects.

• Merge the deserialized object and its privately owned parts: Use the mergeClone(java.lang.Object rmiClone) method to capture changes in the deserialized object and any of its privately owned objects.

• Merge the deserialized object and all referenced objects: Use the mergeCloneWithReferences(java.lang.Object rmiClone) method to capture changes to the deserialized object, its privately owned objects, and all its referenced objects. Note that the referenced objects include only those objects with a direct relationship to the deserialized object.

• Merge the entire relationship graph of the deserialized object: Use the deepMergeClone(java.lang.Object rmiClone) method to capture all changes to the relationship graph of the deserialized object. This method causes OracleAS TopLink to traverse all relationships from the deserialized object to its leaf objects and merge any changes it finds.

Limitations on Merge

To maintain data integrity, OracleAS TopLink imposes a restriction on merging back serialized objects. If the outside JVM adds objects to the structure passed to it, and then passes back the new objects, then OracleAS TopLink merges those objects into the model if one of the following conditions is met:

• The new objects do not exist in the OracleAS TopLink model.

• The new objects exist in the OracleAS TopLink model and are registered with the Unit of Work.

Primary Keys and EJB Entity Beans

A primary key is a mechanism by which OracleAS TopLink and other applications identify persistent objects and entity beans. EJB entity beans use primary keys in much the same way as regular Java objects, and as with Java objects, you usually set primary keys for entity beans in OracleAS TopLink Mapping Workbench.

EJB entity beans support both simple primary keys, which are composed of information from a single field in the bean, and composite primary keys, which are composed of information from one or more fields and are stored in a custom class.

Sequencing and Database Tables

OracleAS TopLink offers three ways to implement sequencing. Although each method is unique, the three techniques have some commonality.

You store persistent objects for your application in database tables that represent the class of instantiated object. Each row of the table represents an instantiated object from that class, and one column in that table holds the primary key for each object. Sequencing populates the primary key row in the table.

When you configure sequencing, specify two settings for these tables, regardless of the type of sequencing you plan to use:

• The name of the table that stores the primary key for the class

• The name of the column in the table that stores the primary key for each object (the sequencing column)

Figure 3-3 Sequencing Elements in a Class Table

Description of the illustration seqtable.gif

In addition to these two elements, table sequencing requires you to specify a SEQ_NAME (a name to identify the class in a special sequencing table name) for each sequenced object. You configure these elements in OracleAS TopLink Mapping Workbench.

Sequencing and Preallocation Size

To improve sequencing efficiency, OracleAS TopLink allows you to preallocate sequence numbers. Preallocation enables OracleAS TopLink to build a pool of available sequence numbers that are assigned to new objects as they are created and inserted into the database. OracleAS TopLink assigns numbers from the pool until the pool is exhausted.

The preallocation size specifies the size of the pool of available numbers. Preallocation improves sequencing efficiency by substantially reducing the number of database accesses required by sequencing. By default, OracleAS TopLink sets preallocation size to 50. You can specify preallocation size either in OracleAS TopLink Mapping Workbench or as part of the session login.

For more information about setting sequencing parameters at session login, see "Setting Sequencing at Login".

Preallocation is available in table sequencing and is required for Oracle native sequencing.

Table Sequencing

Table sequencing involves creating and maintaining an extra database table that includes sequencing information for sequenced objects in the project. OracleAS TopLink maintains this table to track sequence numbers.

Sequencing information appears in this table for any class that uses sequencing. The default table is called SEQUENCE and contains two columns:

• SEQ_NAME, which specifies the class type to which the selected row refers

• SEQ_COUNT, which specifies the highest sequence number currently allocated for the object represented in the selected row

Figure 3-4 OracleAS TopLink SEQUENCE Table

Description of the illustration seqtblmn.gif

The rows of the SEQUENCE table represent every class that participates in sequencing. When you configure sequencing in OracleAS TopLink Mapping Workbench, you specify the SEQ_NAME for the class. OracleAS TopLink adds a row with that name to the SEQUENCE table and initializes the SEQ_COUNT column to the value 1.

You can create the SEQUENCE table on the database in one of two ways:

• Use OracleAS TopLink Mapping Workbench to create the table, in the same way as you do any other table.

  For more information about specifying tables in OracleAS TopLink Mapping Workbench, see "Working with Database Tables in the Navigator Pane" in the Oracle Application Server TopLink Mapping Workbench User's Guide.

• Use the OracleAS TopLink table creator to create and update the table manually.

  For more information, see "Creating the Sequence Table".

Oracle Native Sequencing

OracleAS TopLink support for native sequencing with Oracle databases is similar to table sequencing, except that OracleAS TopLink does not maintain a table in the database. Instead, the Oracle database contains a SEQUENCE object that stores the current maximum number and preallocation size for sequenced objects.

Using SEQUENCE Objects

Your Database Administrator (DBA) must create a SEQUENCE object on the database for every sequencing series your application requires. If every class in your application requires its own sequence, the DBA creates a SEQUENCE object for every class; if you design several classes to share a sequence, the DBA need only create one SEQUENCE object for those classes.

For example, consider the case of a sporting goods manufacturer that manufactures three styles of tennis racquet. The data for these styles of racquet are stored in the database as follows:

• Each style of racquet has its own class table.

• Each manufactured racquet is an object, represented by a line in the class table.

• The system assigns serial numbers that use sequencing to the racquets.

Figure 3-5 Example of Database Tables—Racquet Information

Description of the illustration orseqa.gif

The manufacturer can:

• Use separate sequencing for each racquet style. The DBA builds three separate SEQUENCE objects, perhaps called ATTACK_SEQ, VOLLEY_SEQ, and PROX_SEQ. Each different racquet line has its own serial number series, and there may be duplication of serial numbers between the lines (for example, all three styles may include a racquet with serial number 1234).

• Use a single sequencing series for all rackets. The DBA builds a single SEQUENCE object (perhaps called RACQUET_SEQ). The manufacturer assigns serial numbers to racquets as they are produced, without regard for the style of racquet.

  
  

  Note: If the manufacturer chooses this second option, he may also choose to combine the three tables into a single table to improve database efficiency.

  
  

Native Sequencing with Other Databases

Several databases support a type of native sequencing in which the database management system (DBMS) generates the sequence numbers. When you create a class table for a class that uses sequencing, include a specified primary key column, and set the column type as follows:

• For Sybase SQL Server and Microsoft SQL Server databases, set the primary key field to the type IDENTITY.

• For IBM Informix databases, set the primary key field to the type SERIAL.

  
  

  Note: OracleAS TopLink does not support native sequencing in IBM DB2 databases.

  
  

When you insert a new object into the table, OracleAS TopLink populates the object before insertion into the table, but does not include the sequence number. As the database inserts the object into its table, the database automatically populates the primary key field, with a value equal to the primary key of the previous object, plus 1.

At this point, and before the transaction closes, OracleAS TopLink reads back the primary key for the new object so that the object has an identity in the OracleAS TopLink cache.

Sequencing with CMP Entity Beans

To implement sequencing for CMP entity beans, use a sequencing strategy that implements preallocation, such as table sequencing or Oracle native sequencing. Preallocation ensures that the bean primary key is available at ejbPostCreate() time. If you use native sequencing as offered in Sybase SQL Server, Microsoft SQL Server, or IBM Informix databases, be aware that:

• Native sequencing does not strictly conform to any EJB specification, because it does not initialize the primary key for a created object until you commit the transaction that creates the object. EJB specifications expect that the primary key is available at ejbPostCreate() time.

• OracleAS TopLink CMP integration for IBM WebSphere does not support native sequencing other than Oracle native sequencing.

• BEA WebLogic supports native sequencing; however, this type of native sequencing does not assign or return a primary key for a created object until you commit the transaction in which the object is created. Because of this, if you use native sequencing, commit a transaction immediately after calling the ejbCreate method to avoid problems with object identity in the OracleAS TopLink cache and the container.

public Integer ejbCreate() throws CreateException {
    oracle.toplink.ejb.cmp.was.SessionLookupHelper.getHelper().getSession(this)
      .getActiveUnitofWork().assignSequenceNumber(this);
    return null;
}

public Integer ejbCreate() throws CreateException {
    return null;
}

Sequencing with Stored Procedures

If you have stored procedures that perform sequencing for your application, use an amendment method to direct sequencing queries to use the stored procedures.

DataModifyQuery seqUpdateQuery = new DataModifyQuery();
StoredProcedureCall call = new StoredProcedureCall();
call.setProcedureName("UPDATE_SEQ");
seqUpdateQuery.addArgument("SEQ_NAME"};
seqUpdateQuery.setCall(call);
project.getLogin().setUpdateSequenceQuery(seqUpdateQuery));

ValueReadQuery seqReadQuery = new ValueReadQuery();
StoredProcedureCall call = new StoredProcedureCall();
call.setProcedureName("SELECT_SEQ");
seqReadQuery.addArgument("SEQ_NAME"};
seqReadQuery.setCall(call);
project.getLogin().setSelectSequenceNumberQuery (seqReadQuery));

EJBs and OracleAS TopLink Mapping Workbench

If you use OracleAS TopLink Mapping Workbench to build projects with entity beans, you can load the bean classes themselves into OracleAS TopLink Mapping Workbench. You do not need to load the Remote, Local, Home, and localHome interfaces, or the primary key class, nor must you use these classes to define mappings.

To avoid errors when you load the beans, ensure that classes referenced by the entity beans are on the project classpath used by OracleAS TopLink Mapping Workbench project. The Remote, Local, Home, and localHome interfaces must also be on the classpath, because they may be used during EJB validation.