Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

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