Configuring Container Policy

Collection mapping container policy specifies the concrete class TopLink should use when reading target objects from the database.

Collection mappings can use any concrete class that implements the java.util.List, java.util.Set, java.util.Collection, or java.util.Map interface. You can map object attributes declared as List, Set, Collection, Map, or any subinterface of these interfaces, or as a class that implements one of these interfaces.

By default, the TopLink runtime uses the following concrete classes from the oracle.toplink.indirection package for each of these container types:

• List–IndirectList or EJBIndirectList

• Set–IndirectSet or EJBIndirectSet

• Collection–IndirectList or EJBIndirectList

• Map–IndirectMap or EJBIndirectMap

Alternatively, you can specify in the mapping the concrete container class to be used. When TopLink reads objects from the database that contain an attribute mapped with a collection mapping, the attribute is set with an instance of the concrete class specified. For example, TopLink does not sort in memory. If you want to sort in memory, override the default Set type (IndirectList) with java.util.TreeSet as the concrete collection type. By default, a collection mapping's container class is java.util.Vector.

Note: If you are using TopLink Workbench and you override the default Collection class with a custom Collection class of your own, you must put your custom Collection class on the TopLink Workbench classpath (see "Configuring the TopLink Workbench Environment").

Table 35-15 summarizes which mappings support this option.

Table 35-15 Mapping Support for Container Policy

Mapping	List	Set	Collection	Map	Using TopLink Workbench	Using Java
Relational Mappings
One-to-Many Mapping
Many-to-Many Mapping
Aggregate Collection Mapping
Direct Collection Mapping
Direct Map Mapping
Object-Relational Mappings
Object-Relational Array Mapping
Object-Relational Object Array Mapping
Object-Relational Nested Table Mapping
EIS Mappings
EIS Composite Direct Collection Mapping
EIS Composite Collection Mapping
EIS One-to-Many Mapping
XML Mappings
XML Composite Direct Collection Mapping
XML Composite Collection Mapping
XML Any Collection Mapping

Using TopLink Workbench

To specify a mapping's container policy, use this procedure:

1. Select the mapped attribute in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab appears.

3. Click the Advanced button. The Advanced Container Options appear on the General tab.

   Figure 35-14 General Tab, Advanced Container Options

   
   Description of "Figure 35-14 General Tab, Advanced Container Options"
   
   

FieldFoot 1	Description
Container Type	Specify the type of Collection class to use: List–use a java.util.List Set–use a java.util.Set Collection–use a java.util.Collection Map–use a java.util.Map
Override Default Class	Specify to use a custom class as the mapping's container policy. Click Browse to select a different class. The container class must implement (directly or indirectly) the java.util.Collection interface.
Key Method	If you configure Container Type as Map, use this option to specify the name of the zero argument method whose result, when called on the target object, is used as the key in the Hashtable or Map. This method must return an object that is a valid key in the Hashtable or Map.

^Footnote 1 Not all mappings support all options. For more information, see Table 35-15.

Using Java

Classes that implement the oracle.toplink.mappings.ContainerMapping interface provide the following methods to set the container policy:

• useCollectionClass(java.lang.Class concreteClass)–Configure the mapping to use an instance of the specified java.util.Collection container class to hold the target objects.

• useMapClass(java.lang.Class concreteClass, java.lang.String methodName)–Configure the mapping to use an instance of the specified java.util.Map container class to hold the target objects. The key used to index a value in the Map is the value returned by a call to the specified zero-argument method. The method must be implemented by the class (or a superclass) of any value to be inserted into the Map.

Classes that extend oracle.toplink.mappings.CollectionMapping (which implements the ContainerMapping interface) also provide the following methods to set the container policy:

• useSortedSetClass(java.lang.Class concreteClass, java.util.Comparator comparator)–Configure the mapping to use an instance of the specified java.util.SortedSet container class. Specify the Comparator to use to sort the target objects.

Example 35-16 shows how to configure an ObjectArrayMapping to use a java.util.ArrayList container class.

Example 35-16 Object Array Mapping

// Create a new mapping and register it with the source Object-relational descriptor
ObjectArrayMapping phonesMapping = new ObjectArrayMapping();
phonesMapping.setAttributeName("phones");
phonesMapping.setGetMethodName("getPhones");
phonesMapping.setSetMethodName("setPhones");
phonesMapping.setStructureName("PHONELIST_TYPE");
phonesMapping.setReferenceClass(Phone.class);
phonesMapping.setFieldName("PHONES");
phonesMapping.useCollectionClass(ArrayList.class);
orDescriptor.addMapping(phonesMapping);