OJB repository files map the following information:

Currently, OJB is used as the underlying persistence layer. It converts database rows into java objects upon retrieval, and vice versa upon updates/deletes. This section assumes that the reader is familiar with the basic mapping constructs/principles described on these pages:

OJB provides a way to convert data before they are persisted to and retrieved from the database. This is accomplished by specifying a class that implements org.apache.ojb.broker.accesslayer.conversions.FieldConversion in the <field-descriptor> element.

The following are the more often used converters in KFS/Rice:

Both OJB and the KNS offer a number of FieldConversion implementations beyond these two for use in client applications.

Example converter declaration for a sample Business Object

<field-descriptor name="bankAccountNbr" column="BNK_ACCT_NBR" jdbc-type="VARCHAR" conversion="org.kuali.core.util.OjbKualiEncryptDecryptFieldConversion"/>

OJB relationships should be used to define relationships between tables that are guaranteed to exist within the same database.

For example, assume a sample Business Object class “Bank”. The Bank class contains a BankType reference object. Typically a BankType class table would exist in the same database as the Bank class table. In this example the relationship between Bank and BankType can be defined by OJB. However, a “User” business object table typically will exist in an external system since it will likely be referenced by more than one Rice client application. If a BO had a relationship with a “User” BO, the mapping would require that the relationship be set up via the data dictionary files (which will be discussed in detail later in this document). Any business object implementing the org.kuali.rice.kns.bo.ExternalizableBusinessObject interface needs to be related to via the data dictionary.

Here is an example directly from Rice in the file OJB-repository-kns.xml:

<class-descriptor class="org.kuali.rice.kns.bo.StateImpl" table="KR_STATE_T">
    <field-descriptor name="postalCountryCode" column="POSTAL_CNTRY_CD" jdbc-type="VARCHAR" primarykey="true" index="true" />
    <field-descriptor name="postalStateCode" column="POSTAL_STATE_CD" jdbc-type="VARCHAR" primarykey="true" index="true" />
    <field-descriptor name="postalStateName" column="POSTAL_STATE_NM" jdbc-type="VARCHAR" />
    <field-descriptor name="objectId" column="OBJ_ID" jdbc-type="VARCHAR" index="true" />
    <field-descriptor name="versionNumber" column="VER_NBR" jdbc-type="BIGINT" locking="true" />
    <field-descriptor name="active" column="ACTV_IND" jdbc-type="VARCHAR" conversion="org.kuali.rice.kns.util.OjbCharBooleanConversion"/>

    <reference-descriptor name="country" class-ref="org.kuali.rice.kns.bo.CountryImpl" auto-retrieve="true" auto-update="none" auto-delete="none">
        <foreignkey field-ref="postalCountryCode" />
    </reference-descriptor>
</class-descriptor>

In this OJB mapping, we can determine the following information:

We can determine the following information about the "country" reference object:

A mapping may also define a collection-descriptor tag as follows:

<class-descriptor class="org.kuali.rice.kns.test.document.bo.AccountManager" table="TRV_ACCT_FO">
    <field-descriptor name="id" column="acct_fo_id" jdbc-type="BIGINT" primarykey="true" autoincrement="true" sequence-name="TRV_FO_ID_S" />
    <field-descriptor name="userName" column="acct_fo_user_name" jdbc-type="VARCHAR" />

    <collection-descriptor name="accounts" collection-class="org.apache.ojb.broker.util.collections.ManageableArrayList" element-class-ref="org.kuali.rice.kns.test.document.bo.Account" auto-retrieve="true" auto-update="object" auto-delete="object" proxy="true" >
        <orderby name="accountNumber" sort="ASC" />
        <inverse-foreignkey field-ref="amId" />
    </collection-descriptor>
</class-descriptor>

We can determine the following information about the "accounts" collection reference:

For references mapped within OJB, the framework automatically takes care of the logic to enable refreshing of a reference. Under certain circumstances, it's able to automatically refresh references upon retrieval of the main BO from the database, and refreshing can also be invoked manually.

Note that this means that if the value of a foreign key field is changed, the corresponding reference object is not refreshed automatically. Taking the CampusImpl BO example above, if the code alters the CampusImpl’s campusTypeCode field, the framework will not automatically retrieve the new associated CampusTypeImpl BO reference object. To refresh the CampusImpl’s CampusTypeImpl reference object with the new campus type code, refresh/retrieve must be manually called (see below).

For references with relationships that are not mapped in OJB, code will need to be written to accommodate refreshing. A common example of this is Person object references, because institutions may decide to use another source for Identity Management (e.g. LDAP).

Although there are alternative strategies for accommodating refreshing, typically getter methods of these non-OJB mapped reference objects include the code that retrieves the reference object from the underlying datasource.

In contrast to OJB-mapped references, note that this strategy allows for the automatic refreshing of reference objects when a foreign key field value has been changed. If, in our example using CampusImpl above, the reference object for CampusTypeImpl was not defined in OJB, the string campusTypeCode may be changed and that would be enough to alter the getter method for CampusTypeImpl to properly retrieve the correct row from the database.

Business objects fall into two broad, and for the most part mutually exclusive, categories: those that are edited by maintenance documents and those that are not. This section refers only to business objects that are edited by maintenance documents that have updatable collections.

When constructing this type of BusinessObject, initialize each of the updatable collection references to an instance of org.kuali.rice.kns.util.TypedArrayList. TypedArrayList is a subclass of ArrayList that takes in a java.lang.Class object in its constructor. All elements of this list must be of that type, and when the get(int) method is called, if necessary, this list will automatically construct items of the type to avoid an IndexOutOfBoundsException. Take the example below, the SummaryAccount BO contains an updatable reference to a list of PurApSummaryItem objects.

public class SummaryAccount {
    private List<PurApSummaryItem> items;


    public SummaryAccount() {
        super();
        items = new TypedArrayList(PurApSummaryItem.class);
    }
}

When a collection is non-updatable (i.e. read only from the database), it is not necessary to initialize the collection. OJB will take care of list construction and population.

activeFromDate - The date for which the record becomes active (inclusive when checking active status).

activeToDate - The date to which the record is active (exclusive when checking active status).

active - The active field is calculated from the active from and to dates. If the active from date is less than or equal to current date (or from date is null) and the current date is less than the active to date (or to date is null) the active getter will return true, otherwise it will return false.

current - The current field is set to true for records with the greatest active from date less than or equal to the current date.

For example say we have two employee records:

With 03/01/2010 <= current date < 01/01/2011 both of these records will be active, however only rec 2 would be current since it has a later active begin date.

To determine the maximum active begin date, records are grouped by the fields declared in the data dictionary for the business object.

activeAsOfDate - By default when checking the active or current status the current date is used, however this field can be set to check the status as of another date.

For example say we have a record with active from date 01/01/2010 and active to date 06/01/2010, with the current date equal to 08/01/2010. With the active as of date empty, the current date will be used and this record will be determined inactive. However if we set the active as of date equal to 05/01/2010 (which falls between the active date range) and query, this record will be determined active.

Business objects that implement InactivateableFromTo can participate in default existence checks and inactivation blocking functionality. In addition, the lookup framework contains special logic for searching on InactivateableFromTo instances. This includes:

For finding active and current InactivateableFromTo records InactivateableFromToService can be used. This service provides many methods for dealing with InactivateableFromTo objects in code.

In order to determine whether or not an InactivateableFromTo record is current, the framework must know what fields of the business object to group by (see ‘current’ in ‘Explanation of InactivateableFromTo fields’). This is configured by setting the groupByAttributesForEffectiveDating property on the data dictionary BusinessObjectEntry.

Example:

<bean id="TravelAccountUseRate-parentBean" abstract="true" parent="BusinessObjectEntry">
    <property name="businessObjectClass" value="edu.sampleu.travel.bo.TravelAccountUseRate"/>
    <property name="inquiryDefinition">
        <ref bean="TravelAccountUseRate-inquiryDefinition"/>
    </property>
    <property name="lookupDefinition">
        <ref bean="TravelAccountUseRate-lookupDefinition"/>
    </property>
    <property name="titleAttribute" value="Travel Account Use Rate"/>
    <property name="objectLabel" value="Travel Account Use Rate"/>
    <property name="attributes">
        <list>
            <ref bean="TravelAccountUseRate-id"/>
            <ref bean="TravelAccountUseRate-number"/>
            <ref bean="TravelAccountUseRate-rate"/>
            <ref bean="TravelAccountUseRate-activeFromDate"/>
            <ref bean="TravelAccountUseRate-activeToDate"/>
            <ref bean="TravelAccountUseRate-activeAsOfDate"/>
            <ref bean="TravelAccountUseRate-active"/>
            <ref bean="TravelAccountUseRate-current"/>
        </list>
    </property>
    <property name="groupByAttributesForEffectiveDating">
        <list>
            <value>number</value>
        </list>
    </property>
</bean>