FAQ #15 - How to synchronize ADF Entity Objects with database changes in JDeveloper

Introduction

For ADF applications, as the database schema evolves, there will be a need to synchronize the corresponding Entity and View objects involved, to reflect the changes in the schema. This is a pretty straightforward task in JDeveloper; there are a few things to watch out however.

Main Theme

The task of synchronizing an Entity Object to its respective database table is done by simply right-clicking on the Entity Object in the Application Navigator and selecting Synchronize with Database...

Selecting to synchronize, will bring up the Synchronize with Database dialog where the actions that require synchronization, if any, will be displayed. For the HR schema, the screen below indicates that there are no synchronization actions for the Employee Entity Object since no changes were done to the EMPLOYEES table.

The consequences of the Entity and View Object synchronization differ for the following cases:

• when new fields are added to the database table
• when existing fields are removed from the database table
• when existing fields of the database table are modified

New fields are added to the database table

When new fields are added to the database table, the synchronization feature will determine the new fields and upon synchronization it will add them to the Entity Object. The screen below shows the effect of synchronizing the Employee Entity Object when a new field - MIDDLE_NAME, the employee's middle name - is added to the EMPLOYEES database table of the HR schema.

To reflect this change in the Employee Entity, you can click the Synchronize All (or Synchronize for selected changes) button. JDeveloper proceeds with the synchronization and a new attribute - MiddleName - is added to the Entity Object. This can be verified by reviewing the Attributes page of the Employee Entity Object.

In all cases, synchronization applies only to the Entity Object. The newly added attribute must be added manually to all View Objects that refer the synchronized Entity. This can be done by opening each View Object and in the Attributes page selecting Add Attribute from Entity....

This will bring up the Attributes dialog from where we can shuttle the new attribute from the Available to the Selected list. This is effect will add the new attribute to the View Object as well.

Existing fields are removed from the database table

When a field is removed from the database table, the synchronization feature will not actually remove the corresponding attribute from the Entity Object but instead will make the attribute transient. The screen below shows what happens when we synchronize the Employee Entity Object after we remove the MIDDLE_NAME field from the EMPLOYEES table.

After the synchronization process we can verify that indeed the MiddleName attribute has been made transient and remove it manually ourselves. The attribute indeed is not mapped to the removed table column. Instead it displays a "Synchronize:Fix_SQL" string in the column.

If the attribute is used somewhere else in the project, attempting to delete it will display a "Usages were found" warning message.

Clicking on the View Usages button will determine where the attribute is referenced and display these usages in the Log window. In this case it is used in the Employees View Object.

We need to ensure that we remove the attribute ourselves from everywhere else that is used in the project.


Existing fields of the database table are modified


The synchronization feature will also determine and synchronize the Entity Object for any changes to the precision of the database table fields. For example, after changing the size of the EMPLOYEE table LAST_NAME column from 25 characters to 30 and synchronizing we will see the following:

Reviewing the LastName attribute in the Employee Entity Attributes page reflects this change. The change is also propagated to all View Objects that reference the LastName attribute as it shown below:

The synchronization feature will also detect changes to a database table's column data type. In this case however, although the changes to column's data type will be reflected to the Database Column Type of the Entity Object, the change will not be reflected to the Entity Object's attribute type and you will have to make this change by yourself. To demonstrate this case we will add a VARCHAR2 column called PHONE_EXTENSION to the EMPLOYEE table and then change its data type to a NUMBER. In this case the synchronization feature determines the change in data type as it is shown below.

Reviewing the synchronization results however, we can see that although the change is reflected in the Database Column Type of the Entity Object's PhoneExtension attribute, it is not applied to the Entity's attribute type, which retains the old data type (String).

In this case we will need to make the change to the appropriate data type for the attribute ourselves. This also applies to all View Objects where the specific attribute is referenced.


Conclusion

The ADF Entity synchronization feature in JDeveloper comes pretty handy when updating your Entity Objects to reflect changes to their corresponding tables in the database schema. Be aware however, that depending on whether columns are added, deleted or modified, the synchronization feature will behave slightly different.

Until the next time, keep on JDeveloping!