2011/01/16 - Apache ObJectRelationalBridge has been retired.

Polymorphism

OJB allows us to use interfaces, abstract or concrete base classes in queries, or in type definitions of reference attributes. A Query against the interface InterfaceArticle must not only return objects of type Article but also of CdArticle and BookArticle!
The following example method searches for all objects implementing InterfaceArticle with an articleName equal to Hamlet (provided that the object mapping is correct, details will described later). The Collection is e.g filled with one matching BookArticle object.

public void testCollectionByQuery() throws Exception
{
    Criteria crit = new Criteria();
    crit.addEqualTo("articleName", "Hamlet");
    Query q = QueryFactory.newQuery(InterfaceArticle.class, crit);

    Collection result = broker.getCollectionByQuery(q);
}

Of course it is also possible to define reference attributes of an interface or baseclass type. The example class Article has a reference attribute (1:1 reference) of type ProductGroup and this can be a concrete/abstract class or interface.

Extents

The query in the last example returned just one object. Now, imagine a query against the InterfaceArticle interface with no selecting criteria. OJB returns all the objects implementing InterfaceArticle. E.g. all Article, BookArticle and CdArticles objects.
In the following example the method prints out the collection of all InterfaceArticle objects:

public void testExtentByQuery() throws Exception
{
    // no criteria signals to omit a WHERE clause
    Query q = QueryFactory.newQuery(InterfaceArticle.class, null);
    Collection result = broker.getCollectionByQuery(q);

    System.out.println(
        "The InterfaceArticle Extent objects: " +result);
}

In our class diagram we find:

1. two simple one-class-only extents, BookArticle and CdArticle.
2. A compound extent Article containing all Article and BookArticle instances.
3. An interface extent containing all Article, BookArticle and CdArticle instances.

There is no extra coding necessary to define extents, but they have to be declared in the metadata mapping file. The classes from the above example require the following declarations:

1. one-class-only extents require no declaration
2. A declaration for the base class Article, defining which classes are subclasses of Article:

   <!-- Definitions for org.apache.ojb.ojb.broker.Article -->
   <class-descriptor
       class="org.apache.ojb.broker.Article"
       proxy="false"
       table="Artikel"
       ...
   >
       <extent-class class-ref="org.apache.ojb.broker.BookArticle" />
   ...
   </class-descriptor>

3. A declaration for InterfaceArticle, defining which classes implement this interface:

   <!-- Definitions for org.apache.ojb.broker.InterfaceArticle -->
   <class-descriptor class="org.apache.ojb.broker.InterfaceArticle">
       <extent-class class-ref="org.apache.ojb.broker.Article" />
       <extent-class class-ref="org.apache.ojb.broker.CdArticle" />
       <!-- not needed to declare -->
       <!--<extent-class class-ref="org.apache.ojb.broker.BookArticle" />-->
   </class-descriptor>

   No need to declare BookArticle here, because it's a declared sub class of Article, so it's implicit declared by Article extent.

Why is it necessary to explicitely declare which classes implement an interface and which classes are derived from a base class?
Of course it is quite simple in Java to check whether a class implements a given interface or extends some other class. But sometimes it may not be appropiate to treat special implementors (e.g. proxies) as proper implementors.

Other problems might arise because a class may implement multiple interfaces, but is only allowed to be regarded as member of one extent.

In other cases it may be neccessary to treat certain classes as implementors of an interface or as derived from a base even if they are not (we don't recommend to use this feature it's bad design, but if you don't have an alternative...).
As an example, you will find that the ClassDescriptor of abstract test class org.apache.ojb.broker.CollectionTest$BookShelfItem in the OJB's Test Suite contains an entry declaring class org.apache.ojb.broker.CollectionTest$Candie as a derived class:

<class-descriptor class="org.apache.ojb.broker.CollectionTest$BookShelfItem">
   <extent-class class-ref="org.apache.ojb.broker.CollectionTest$Book"/>
   <extent-class class-ref="org.apache.ojb.broker.CollectionTest$DVD"/>
    <!-- This class isn't a subclass of Book or DVD or a implementation of
    BookShelfItem, anyway it's possible to declare it as extent (but not recommended) -->
   <extent-class class-ref="org.apache.ojb.broker.CollectionTest$Candie"/>
</class-descriptor>

Performance Tip

When using extents OJB will produce some overhead for each declared extent (e.g. execute a separate select-query for each extent or using complex table joins).
Thus it's important to avoid unnecessary extent declarations. If in the above example class InterfaceArticle is never used in queries, don't declare the extents for the implementing classes (Article, CdArticle). It's always possible to add additional extents in mapping files.

Mapping Each Class of a Hierarchy to a Distinct Table (table per class)

This is the most simple solution. Just write a complete ClassDescriptor with FieldDescriptors for all of the attributes, including inherited attributes.

The classes of our mapping example would look like:

public class Employee implements Serializable
{
    private Integer id;
    private String name;

    public Employee()
    {
    }
....
// getter/setter for id and ojbConcreteClass
}

public class Executive extends Employee
{
    private String department;
....
// getter/setter
}

public class Manager extends Executive
{
    private int consortiumKey;
....
// getter/setter
}

The ClassDescriptors include all fields of the representing java-class and each descriptor points to a different table:

<class-descriptor
    class="Employee"
    table="EMPLOYEE"
>
    <extent-class class-ref="Executive" />
    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
    />
    <field-descriptor
        name="name"
        column="NAME"
        jdbc-type="VARCHAR"
    />
</class-descriptor>

<class-descriptor
    class="Executive"
    table="EXECUTIVE"
>
    <extent-class class-ref="Manager" />
    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
    />
    <field-descriptor
        name="name"
        column="NAME"
        jdbc-type="VARCHAR"
    />
    <field-descriptor
        name="department"
        column="DEPARTMENT"
        jdbc-type="VARCHAR"
    />
</class-descriptor>

<class-descriptor
    class="Manager"
    table="MANAGER"
>
    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
    />
    <field-descriptor
        name="name"
        column="NAME"
        jdbc-type="VARCHAR"
    />
    <field-descriptor
        name="department"
        column="DEPARTMENT"
        jdbc-type="VARCHAR"
    />
    <field-descriptor
        name="consortiumKey"
        column="CONSORTIUM_KEY"
        jdbc-type="INTEGER"
    />
</class-descriptor>
                

The extent-class element is needed to declare the inheritance between the classes.

The DDL for the tables would look like:

CREATE TABLE EMPLOYEE
(
    ID      INT NOT NULL PRIMARY KEY,
    NAME    VARCHAR(150)
)
CREATE TABLE EXECUTIVE
(
    ID      INT NOT NULL PRIMARY KEY,
    NAME    VARCHAR(150),
    DEPARTMENT    VARCHAR(150)
)
CREATE TABLE MANAGER
(
    ID              INT NOT NULL PRIMARY KEY,
    NAME            VARCHAR(150),
    DEPARTMENT      VARCHAR(150),
    CONSORTIUM_KEY  INT
)

Mapping Class Hierarchy on the Same Table (table per hierarchy)

Mapping several classes on one table works well under OJB. There is only one special situation that needs some attention:

Storing Employee, Executive and Manager objects to this table works fine. But now consider a Query against the baseclass Employee. How can the correct type of the stored objects be determined?

OJB needs a discriminator column of type CHAR or VARCHAR that contains the class name to be used for instantiation. This column must be mapped on a special attribute ojbConcreteClass. On loading objects from the table, OJB checks this attribute and instantiates objects of this type.

The classes of our mapping example would look like:

public class Employee implements Serializable
{
    private Integer id;
    /**
     * This special attribute telling OJB which concrete class
     * this Object has.
     * NOTE: this attribute MUST be called ojbConcreteClass
     */
    private String ojbConcreteClass;
    private String name;

    public Employee()
    {
        // this guarantee that always the correct class name will be set
        this.ojbConcreteClass = this.getClass().getName();
    }
....
// getter/setter for id and ojbConcreteClass
}

public class Executive extends Employee
{
    private String department;

    public Executive()
    {
        super();
    }
....
// getter/setter
}

public class Manager extends Executive
{
    private int consortiumKey;

    public Manager()
    {
        super();
    }
....
// getter/setter
}

Here are the metadata mappings of our mapping example:

<class-descriptor
    class="Employee"
    table="MANPOWER"
>
    <extent-class class-ref="Executive" />

    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
    />
    <field-descriptor
        name="ojbConcreteClass"
        column="CLASS_NAME"
        jdbc-type="VARCHAR"
    />
    <field-descriptor
        name="name"
        column="NAME"
        jdbc-type="VARCHAR"
    />
</class-descriptor>

<class-descriptor
    class="Executive"
    table="MANPOWER"
>
    <extent-class class-ref="Manager" />

    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
    />
    <field-descriptor
        name="ojbConcreteClass"
        column="CLASS_NAME"
        jdbc-type="VARCHAR"
    />
    <field-descriptor
        name="name"
        column="NAME"
        jdbc-type="VARCHAR"
    />
    <field-descriptor
        name="department"
        column="DEPARTMENT"
        jdbc-type="VARCHAR"
    />
</class-descriptor>

<class-descriptor
    class="Manager"
    table="MANPOWER"
>
    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
    />
    <field-descriptor
        name="ojbConcreteClass"
        column="CLASS_NAME"
        jdbc-type="VARCHAR"
    />
    <field-descriptor
        name="name"
        column="NAME"
        jdbc-type="VARCHAR"
    />
    <field-descriptor
        name="department"
        column="DEPARTMENT"
        jdbc-type="VARCHAR"
    />
    <field-descriptor
        name="consortiumKey"
        column="CONSORTIUM_KEY"
        jdbc-type="INTEGER"
    />
</class-descriptor>

The column CLASS_NAME is used to store the concrete type of each object.

The extent-class element is needed to declare the inheritance between the classes.

The DDL for the table would look like:

CREATE TABLE MANPOWER
(
    ID      INT NOT NULL PRIMARY KEY,
    CLASS_NAME      VARCHAR(150)
    NAME    VARCHAR(150),
    DEPARTMENT      VARCHAR(150),
    CONSORTIUM_KEY  INT
)

Implement your own Discriminator Handling

If you cannot provide such an additional column, but need to use some other means of indicating the type of each object you will require some additional programming:

You have to derive a Class from org.apache.ojb.broker.accesslayer.RowReaderDefaultImpl and override the method RowReaderDefaultImpl.selectClassDescriptor() to implement your specific type selection mechanism. The code of the default implementation looks like follows:

protected ClassDescriptor selectClassDescriptor(Map row)
                                        throws PersistenceBrokerException
{
    // check if there is an attribute which tells us
    // which concrete class is to be instantiated
    ClassDescriptor result = m_cld;
    Class ojbConcreteClass = (Class) row.get(OJB_CONCRETE_CLASS_KEY);
    if(ojbConcreteClass != null)
    {
        result = m_cld.getRepository().getDescriptorFor(ojbConcreteClass);
        // if we can't find class-descriptor for concrete
        // class, something wrong with mapping
        if (result == null)
        {
            throw new PersistenceBrokerException(
                "Can't find class-descriptor for ojbConcreteClass '"
                 + ojbConcreteClass + "', the main class was "
                 + m_cld.getClassNameOfObject());
        }
    }
    return result;
}

After implementing your own RowReader you must edit the ClassDescriptor for the respective class in the XML repository to specify the usage of your RowReader Implementation:

<class-descriptor
      class="my.Object"
      table="MY_OBJECT"
      ...
      row-reader="my.own.RowReaderImpl"
      ...
>
...

You will learn more about RowReaders in this section.

Mapping Each Subclass to a Distinct Table (table per subclass)

This mapping strategy maps all subclass fields of a hierarchy to a distinct table (but do not map super class fields to derived class tables - except the primary key fields) and use joins to materialize over all tables to materialize the objects.

The classes of the inheritance hierarchy don't need any specific fields or settings, thus our mapping example java-classes look would look like the classes for the table-per-class mapping.

The next code block contains the class-descriptors of our mapping example.

<class-descriptor
    class="Employee"
    table="EMPLOYEE"
>
    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
    />
    <field-descriptor
        name="name"
        column="NAME"
        jdbc-type="VARCHAR"
    />
</class-descriptor>

<class-descriptor
    class="Executive"
    table="EXECUTIVE"
>
    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
    />
    <field-descriptor
        name="department"
        column="DEPARTMENT"
        jdbc-type="VARCHAR"
    />

    <reference-descriptor name="super"
        class-ref="Employee"
    >
        <foreignkey field-ref="id"/>
    </reference-descriptor>
</class-descriptor>

<class-descriptor
    class="Manager"
    table="MANAGER"
>
    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
    />
    <field-descriptor
        name="consortiumKey"
        column="CONSORTIUM_KEY"
        jdbc-type="INTEGER"
    />

    <reference-descriptor name="super"
        class-ref="Executive"
    >
        <foreignkey field-ref="id"/>
    </reference-descriptor>
</class-descriptor>

The mapping for base class Employee is ordinary and we using a autoincrement primary key field.
In the subclasses Executive and Manager it's not allowed to use autoincrement primary keys, because OJB will automatically copy the primary keys of the base class to all subclasses.

As you can see this mapping needs a special reference-descriptor in the subclasses Executive and Manager that advises OJB to load the values for the inherited attributes from the super-class by a JOIN using the foreign key reference.
The name="super" attribute is not used to address an actual attribute of the super-class but as a marker keyword defining the JOIN to the super-class.

The DDL for the tables would look like:

CREATE TABLE EMPLOYEE
(
    ID      INT NOT NULL PRIMARY KEY,
    NAME    VARCHAR(150)
)
CREATE TABLE EXECUTIVE
(
    ID      INT NOT NULL PRIMARY KEY,
    DEPARTMENT    VARCHAR(150)
)
CREATE TABLE MANAGER
(
    ID              INT NOT NULL PRIMARY KEY,
    CONSORTIUM_KEY  INT
)

Attributes from the base- or superclasses can be used the same way as attributes of the target class when querying - e.g. for Executive or Manager. No path-expression is needed in this case. The following examples returns all Executive and Manager matching the criteria:

Criteria c = new Criteria();
// attribute defined in base class Employee
c.addEqualTo("name", "Kent");
// attribute defined in Executive
c.addEqualTo("department", "press");
Query q = QueryFactory.newQuery(Executive.class, c);
// returns all matching Executive and Manager instances
Collection result = broker.getCollectionByQuery(q);

Table Per Subclass via Foreign Key

The above example is based on the assumption that the primary key attribute Employee.id and its underlying column EMPLOYEE.ID is also used as the foreign key attribute in the the subclasses.

Now let us consider a case where this is not possible, then it's possible to use an additional foreign key field/column in the subclass referencing the base-/superclass.

In this case the layout for class Executive would need an additional field employeeFk to store the foreign key reference to Employee.
To avoid the additional field in the subclass (if desired) we can use OJB's anonymous field feature to get everything working without the employeeFk attribute in subclass Employee (thus the java classes of our mapping example). We keep the field-descriptor for employeeFk, but declare it as an anonymous field. We just have to add an attribute access="anonymous" to the new field-descriptor employeeFk:.

<class-descriptor
    class="Employee"
    table="EMPLOYEE"
>
    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
    />
    <field-descriptor
        name="name"
        column="NAME"
        jdbc-type="VARCHAR"
    />
</class-descriptor>

<class-descriptor
    class="Executive"
    table="EXECUTIVE"
>
    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
    />
    <field-descriptor
        name="department"
        column="DEPARTMENT"
        jdbc-type="VARCHAR"
    />
    <field-descriptor
        name="employeeFk"
        column="EMPLOYEE_FK"
        jdbc-type="INTEGER"
        access="anonymous"
    />
    <reference-descriptor name="super"
        class-ref="Employee"
    >
        <foreignkey field-ref="employeeFk"/>
    </reference-descriptor>
</class-descriptor>

<class-descriptor
    class="Manager"
    table="MANAGER"
>
    <field-descriptor
        name="id"
        column="ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
    />
    <field-descriptor
        name="consortiumKey"
        column="CONSORTIUM_KEY"
        jdbc-type="INTEGER"
    />

    <field-descriptor
        name="executiveFk"
        column="EXECUTIVE_FK"
        jdbc-type="INTEGER"
        access="anonymous"
    />

    <reference-descriptor name="super"
        class-ref="Executive"
    >
        <foreignkey field-ref="executiveFk"/>
    </reference-descriptor>
</class-descriptor>

Now it's possible to use autoincrement primary key fields in all classes of the hierarchy (because they are decoupled from the inheritance references).
The foreignkey-element have to refer the new (anomymous) foreign-key field.

Rowreader Example

Assume that for some reason we do not want to map a 1:1 association with a foreign key relationship to a different database table but read the associated object 'inline' from some columns of the master object's table. This approach is also called 'nested objects'. The section nested objects contains a different and much simpler approach to implement nested fields.

The class org.apache.ojb.broker.ArticleWithStockDetail has a stockDetail attribute, holding a reference to a StockDetail object. The class StockDetail is not declared in the XML repository. Thus OJB is not able to fill this attribute by ordinary mapping techniques.

We have to define a RowReader that does the proper initialization. The Class org.apache.ojb.broker.RowReaderTestImpl extends the RowReaderDefaultImpl and overrides the readObjectFrom(...) method as follows:

public Object readObjectFrom(Map row, ClassDescriptor cld)
{
    Object result = super.readObjectFrom(row, cld);
    if (result instanceof ArticleWithStockDetail)
    {
        ArticleWithStockDetail art = (ArticleWithStockDetail) result;
        boolean sellout = art.isSelloutArticle;
        int minimum = art.minimumStock;
        int ordered = art.orderedUnits;
        int stock = art.stock;
        String unit = art.unit;
        StockDetail detail = new StockDetail(sellout, minimum,
                                    ordered, stock, unit, art);
        art.stockDetail = detail;
        return art;
    }
    else
    {
        return result;
    }
}

To activate this RowReader the ClassDescriptor for the class ArticleWithStockDetail contains the following entry:

<class-descriptor
  class="org.apache.ojb.broker.ArticleWithStockDetail"
  table="Artikel"
  row-reader="org.apache.ojb.broker.RowReaderTestImpl"
>

Types Allowed for Implementing 1:n and m:n Associations

OJB supports different Collection types to implement 1:n and m:n associations. OJB detects the used type automatically, so there is no need to declare it in the repository file. There is also no additional programming required. The following types are supported:

1. java.util.Collection, java.util.List, java.util.Vector as in the example above. Internally OJB uses java.util.Vector to implement collections.
2. Arrays (see the file ProductGroupWithArray).
3. User-defined collections (see the file ProductGroupWithTypedCollection). A typical application for this approach are typed Collections.
   Here is some sample code from the Collection class ArticleCollection. This Collection is typed, i.e. it accepts only InterfaceArticle objects for adding and will return InterfaceArticle objects with get(int index). To let OJB handle such a user-defined Collection it must implement the callback interface ManageableCollection and the typed collection class must be declared in the collection-descriptor using the collection-class attribute. ManageableCollection provides hooks that are called by OJB during object materialization, updating and deletion.

public class ArticleCollection implements ManageableCollection,
                                      java.io.Serializable
{
    private Vector elements;

    public ArticleCollection()
    {
        super();
        elements = new Vector();
    }

    public void add(InterfaceArticle article)
    {
        elements.add(article);
    }

    public InterfaceArticle get(int index)
    {
        return (InterfaceArticle) elements.get(index);
    }

    /**
     * add a single Object to the Collection. This method is
     * used during reading Collection elements from the
     * database. Thus it is is save to cast anObject
     * to the underlying element type of the collection.
     */
    public void ojbAdd(java.lang.Object anObject)
    {
        elements.add((InterfaceArticle) anObject);
    }

    /**
     * adds a Collection to this collection. Used in reading
     * Extents from the Database.
     * Thus it is save to cast otherCollection to this.getClass().
     */
    public void ojbAddAll(
          ojb.broker.ManageableCollection otherCollection)
    {
        elements.addAll(
          ((ArticleCollection) otherCollection).elements);
    }

    /**
     * returns an Iterator over all elements in the collection.
     * Used during store and delete Operations.
     */
    public java.util.Iterator ojbIterator()
    {
        return elements.iterator();
    }
}

And the collection-descriptor have to declare this class:

<collection-descriptor
name="allArticlesInGroup"
element-class-ref="org.apache.ojb.broker.Article"
collection-class="org.apache.ojb.broker.ArticleCollection"
auto-retrieve="true"
auto-update="false"
auto-delete="true"
>
<inverse-foreignkey field-ref="productGroupId"/>
</collection-descriptor>

Which collection-class type should be used?

Earlier in this section the org.apache.ojb.broker.ManageableCollection was introduced. Now we talk about which type to use.

By default OJB use a removal-aware collection implementation. These implementations (classes prefixed with Removal...) track removal and addition of elements.
This tracking allow the PersistenceBroker to delete elements from the database that have been removed from the collection before a PB.store() operation occurs.

This default behaviour is undesired in some cases:

• In m:n relations, e.g. between Movie and Actor class. If an Actor was removed from the Actor collection of a Movie object expected behaviour was that the Actor be removed from the indirection table, but not the Actor itself. Using a removal aware collection will remove the Actor too. In that case a simple manageable collection is recommended by set e.g. collection-class="org.apache.ojb.broker.util.collections.ManageableArrayList" in collection-descriptor.
• In 1:n relations when the n-side objects be removed from the collection of the main object, but we don't want to remove them itself (be careful with this, because the FK entry of the main object still exists - more info about linking here).