Fear for renaming (refactoring) ADF BC objects in JDeveloper 10.1.3.3 is not unfounded

5

Growing insight during development of a project often results in a wish to rename a BC object (entity object, view object, association, view object attribute, alias, usage, etc.) in JDeveloper. Or in JHeadstart to rename objects like a group, item or a region. Often, developers are not renaming objects because it is not clear to them what the impact will be, and the amount of work which might be involved in case unpredicted errors arise. And the fear for incorrect renaming/refactoring in JDeveloper is certainly not unfounded. ....   In this article I will give a table overview of what JDeveloper does for each BC object you rename, and what happens when you rename a JHeadstart group, item and region:

  • Which files are updated correctly?
  • Which files, if any, are NOT updated correctly by JDeveloper (bugs)?
  • Solutions – in case JDeveloper does not correctly update your renamed object.
  • Does renaming an ADF BC object have any consequence when using JHeadstart?

When you rename an object, it is best to rename only one object at a time, and then test whether your application still works fine. For ADF BC objects you can test it directly in de JDeveloper test-browser.  

 

Overview of issues and bugs when refactoring (or renaming) ADFBC objects in JDeveloper 10.1.3.3   

ADF-BC object Refactor issues?        Impact What happens during refactoring? Consequences when using JHeadstart?
       
  • entity object (EO)
YES        Impact: medium refactored correctly:      

  • <EO>.xml
  • <associationName>.xml (all <association>.xml files involved for this renamed EO)
  • <EO>Impl.java
  • entities.xml
  • <VO>.xml (all <VO>.xml files based on this EO)
  • <VO>.RowImpl.java  

NOT CORRECTLY REFACTORED:

  • <destinationEOofAssoc>.xml in case your renamed EO is the source EO in an association. To be precise: any EO which has an association with your renamed EO and has an accessor which returns a single entity row of type <yourRenamedEO>Impl (and doesn’t return an object of type RowIterator).

For details see the ADF-BC solutions table below. 

Note: After renaming this object you could consider (but is absolutely not necessary) to change:

  • an entity alias in a VO that use this EO
  • VO name based on this EO.

If so, check this table for issues involving renaming an entity alias in a view object or a VO name.

YES (Impact: very small)

You only have to regenerate. ApplicationResources_< ServiceName>.sql is correctly updated and updates rows in the JHS_TRANSLATIONS table where the TEXT column is updated for the KEY1 column (these are rows referring to errortext of all FK constraints regarding this EO).

  • entity association
- refactored correctly:      

  • <associationName>.xml
  • <sourceEO>.xml
  • <destinationEO>.xml
  • entities.xml
  • <associationName|without ‘Assoc’|>Link.xml
-
  • entity association accessors (source and destination accessors)
- refactored correctly:      

  • <associationName>.xml
  • <sourceEO>.xml
  • <destinationEO>.xml
  • <sourceEO>Impl.java
-
       
  • view object (VO)
YES       Impact:small refactored correctly:      

  • <serviceName>.xml
  • <VL>.xml (involving this VO, more than one <VL>.xml files possible)
  • <VO>.xml
  • <VO>Impl.java
  • <VO>RowImpl.java
  • <VO>DefImpl.java
  • views.xml  

NOT CORRECTLY REFACTORED:

  • <ServiceName>Impl.java. The return type of <VOInstance> getter methods that return your renamed <VO>Impl still reflect the old <VO>Impl name.  

For details see the ADF-BC solutions table below. 

Note: After renaming this object you could consider (but is absolutely not necessary) to change a VO instance (or usage) name based on this renamed VO. If so, check this table for issues involved with refactoring VO instance names.

YES (impact: very small and not fatal)   

Refresh corresponding JHS ‘data collection implementation’ by refreshing the ‘data collection’. No need to regenerate. For details see the ADF-BC solutions table below.  

  • view object attributes

YES*

(*only in case  JHeadstart is not used. Impact: medium)

refactored correctly:      

  • <VO>.xml
  • <VO>RowImpl.java  

Note: After renaming this object you could consider (but is absolutely not necessary) to change the corresponding JHS item name after changing the VO attribute name.

ISSUE in case you don’t use JHeadstart:

Be aware that (!) refactoring a VO attribute does NOT rename any object in any pageDefinition or jspx file! Refactoring any BC object is NOT updated in the ADF model layer, which is correct (but maybe not expected) because the BC and model are separated layers. After refactoring, the old VO attribute name could still be used in the element ‘attributeValues’ (sub-element ‘AttrNames’) in corresponding pageDef files or in JSF components in .jspx files. This is also the case if you do use JHeadstart but has unchecked the JHS group setting ‘Generate Page Definition’.

YES (impact: small)       

Refresh corresponding JHS ‘item’ in JHS group and regenerate. For details see the ADF-BC solutions table below.

  • view object instance (VO usage)

YES*

(*only in case  JHeadstart is not used. Impact: medium)

refactored correctly:      

  • <serviceName>.xml
  • <serviceName>Impl.java  

Note: After renaming this object you could consider (but is absolutely not necessary) to change the corresponding JHS group name after changing the VO instance name. If so, check the issues involved in the table for renaming JHS objects.

ISSUE in case you don’t use JHeadstart:

Be aware that (!) refactoring  a VO instance does NOT rename any object in any pageDefinition file ! Refactoring any BC object is NOT updated in the ADF model layer, which is correct (but maybe not expected) because the BC and model are separated layers. This is also the case if you do use JHeadstart but has unchecked the JHS group setting ‘Generate Page Definition’. After refactoring, the old VO instance name is still used in the element ‘iterator’ (attribute ‘Binds’) and element ‘action’ (attribute ‘InstanceName’) of:

  • <parentVOInstance>PageDef.xml
  • <VOInstance>PageDef.xml>

YES (impact: small)      

Refresh corresponding JHS ‘data collection’ and regenerate. For details see the ADF-BC solutions table below.

  • entity alias in view object
YES        Impact:small refactored correctly:      

  • <VO>.xml
  • <VO>RowImpl.java
  • SQL-query (the SELECT list and FROM clause, in case expert mode is not used)  

NOT CORRECTLY REFACTORED:

  • SQL-query, when a custom query clause (where, order by, group by) is present. Be aware that in expert-mode it is not possible to rename the entity alias because it is read-only.  

For details see the ADF-BC solutions table below.

Note: After renaming this object you could consider (but is absolutely not necessary) to change the VO name after changing the entity alias. If so, check this table for issues involved with refactoring VO names.

-
  • viewLink (VL)
- refactored correctly:      

  • <serviceName>.xml
  • <serviceName>Impl.java
  • <sourceVO>.xml
  • <VL>.xml
  • views.xml

Note: After renaming this object you could consider (but is absolutely not necessary) to change the VO instance (or usage) name after renaming the VL. If so, check this table for issues involved with refactoring VO instance names.

-
  • viewLink accessor (VL source- and destination accessor)
YES        Impact:small refactored correctly:      

  • <destinationVO>RowImpl.java (in case you change source accessor)
  • <sourceVO>RowImpl.java (in case you change destination accessor)
  • <VL>.xml

NOT CORRECTLY REFACTORED:

  • <destinationVO>.xml (in case you change source accessor). The ‘name’ attribute of element ‘ViewLinkAccessor’ is not updated.
  • <sourceVO>.xml (in case you change destination accessor) The ‘name’ attribute of element ‘ViewLinkAccessor’ is not updated.  

For details see the ADF-BC solutions table below. 

Note: After renaming this object you could consider (but is absolutely not necessary) tochange the VO instance (or usage) name after renaming a VL accessor. If so, check this table for issues involved with refactoring VO instance names.

-

 

 

Solution details for issues when refactoring (or renaming) ADFBC objects in JDeveloper 10.1.3.3     

  • entity object (EO)

 

The file <EO>.xml, which represents an EO that has an association to your renamed EO is not updated correctly in case this EO has an accessor which returns an entity row of type <yourRenamedEO>Impl (and doesn’t return an object of type RowIterator). This is especially the case in hierarchical entity relations described by entity associations.      

For example, a Countries entity object has a hierarchical association with a Locations entity object. A Country is composed of Location entries, and it does not make sense for a Location entity row to exist independently from a Country. When you refactor a Countries entity object to ‘MyCountries’, Location.xml is not updated correctly and will still contain a reference to the old name of the Java <EO>Impl. file, ‘CountryImpl’ instead of ‘MyCountriesImpl’ in the ‘Type’ attribute of the ‘AccessorAttribute’ element:

Because all <EO>.xml files are protected or read-only in JDeveloper, you must open Location.xml in your own editor, for example Notepad, and rename the ‘Type’ attribute of the ‘AccessorAttribute’ element to the correct new <EO>Impl name. Refactor not more than one EO at a time, and test it in the BC-test browser in JDeveloper. An entity object may have multiple (hierarchical) associations.

Note: As you can see in the image, there seems to be still a reference to the old EO name, ‘Countries’ (attribute ‘AssociationEnd’ in the element ‘AccessorAttribute’) and this can be confusing. In reality, this name is a reference to the AssociationEnd ‘Name’ attribute in de file <associationName>.xml, in this case ‘LocCidFkAssoc’. JDeveloper maintains this name correctly. In the file ‘LocCidFkAssoc’.xml is also an attribute ‘Owner’ (in the element ‘AssociationEnd’) which points correctly to the renamed EO.

 

  • View Object (VO)

When you refactor a view object your renamed view object is not changed in your applicationModule file, <yourServiceName>Impl.java. For each of your view object instances (or usages) a get<nameUsageVO>() method is created in <yourServiceName>Impl.java, which returns an object of type of your renamed <VO>Impl. After refactoring, this return type is not corrected by JDeveloper so you have to correct this yourself.      

For example, an ‘AllCountries’ VO is refactored to ‘All_MY_Countries’. As you can see in the image below, the return type is not updated (still of type AllCountriesImpl instead of All_MY_CountriesImpl. JDeveloper can not find the old <VO>Impl file anymore and shows you by the red lines. You have to rename the return type (and the cast) yourself to the new <VO>Impl name for all the VO instance-getters that return your renamed VO.

 

JHeadstart

Has a very small consequence for JHeadstart. It is not fatal, the application will still work, but it is a good practice to refresh the corresponding ‘data collection implementation’ (this is the ADFBC VO definition) for the JHS groups (or detail groups) that use this renamed view object. To refresh you only have go to the selected groups in the JHS application definition editor and go to query settings, and property ‘data collection’ (this is the view object usage or instance). Click at this ‘data collection’ dropdown-list once and select the new <VO> name and (at the read-only) ‘data collection implementation’ will automatically be refreshed.

   

It is not necessary to regenerate the application. *If you already had the JHeadstart application definition editor opened, just close and reopen it and the list will be refreshed and contain your new view object name.  

  • view object instance (VO usage)

JHeadstart      

Renaming a VO instance has a medium consequence for JHeadstart. It is fatal, the application will not work. You have to refresh the corresponding ‘data collection’ for the JHS groups (or detail groups) that use this renamed view object. To refresh you only have go to the selected groups in the JHS application definition editor and go to query settings, and property ‘data collection’ (this is the view object usage or instance). Click at this ‘data collection’ dropdown-list once and the new <VOInstance> name will automatically appear.  

 

  

Then you have to regenerate the application.

*If you already had the JHeadstart application definition editor opened, just close and reopen it and the list will be refreshed and contain your new view object instance name.  

  • view object attribute name

JHeadstart      

Renaming a VO attribute name has a small consequence for JHeadstart. Go to the JHS group which corresponds to the VO of the attribute name you changed, and go the corresponding JHS item. You only have to refresh, in the JHS editor, this item by clicking on the dropdown-list and selecting the new name, which is automatically available. For example, you changed the ‘CountryName’ attribute name of the VO ‘AllCountries’ view object to ‘MY_CountryName’ (‘RegionCountries’ is a VO instance of the VO ‘AllCountries’).

Then you have to regenerate the application. *If you already had the JHeadstart application definition editor opened, just close and reopen it and the list will be refreshed and contain your new attribute name. 

  • viewLink accessor (VL source- and destination accessor)

When you refactor a VL accessor your renamed VL accessor is not changed in your <VODestination>.xml (or <VOSource>.xml, depending whether you change the source or destination accessor).      

Correct the ‘name’ attribute, which reflects still the old VL accessor name, of the ‘ViewLinkAccessor’ element in the <VODestination>.xml (or <VOSource>.xml) file with your new VL accessor name. You have to correct this in your own editor, for example Notepad, as this file is protected (read-only) in JDeveloper.

 

  • entity alias in view object

When you rename an entity alias in a view object, your renamed entity alias should be corrected in your SQL query. In case you have made any custom query clauses, the entity alias is not updated by JDeveloper, you have to correct this yourself.      

For example, if you renamed an entity alias ‘Countries’ to ‘MY_Countries’, the SELECT-clause is correctly updated, but not the custom WHERE-clause (all custom clauses, so also the ORDER BY or GROUP BY clause).  

 

Be aware that in expert-mode it is not possible to rename the entity alias because it is read-only.

 

 

 

Overview of issues when renaming a group-, item- and region name in JHeadstart 10.1.3.2.51

JHeadstart (JHS) object Renaming issues? Impact What happens during refactoring?
  • group name
YES        impact: medium to big New files created:      

  • <newGroupName>.jspx
  • <newGroupName>Table.jspx (in case your group has layout style ‘table-form’.)
  • <newGroupName>.pageDef.xml
  • <newGroupName>-beans.xml

Files correctly updated:

  • <serviceName>ApplicationDefinition.xml
  • <parentGroupName>.pageDef.xml in case your renamed group is a detailgroup in a region of this parent group.
  • <parentGroupName>.jspx in case your renamed group is a detailgroup in a region of this parent group.
  • <detailGroupName>.jspx in case your renamed group is a parentgroup and has a this detail group in a region.
  • <serviceName>-Breadcrumb-beans.xml
  • faces-config.xml
  • ApplicationResources_<serviceName>.sql (also other locales, for example ApplicationResources_nl_<serviceName>.sql)
  • <serviceName>MenuTabs.jspx
  • <serviceName><nameTopParentGroup>Menu2Tabs.jspx (if present)

Files correctly added with new elements BUT NOW HAVE OBSOLETE ELEMENTS:

  • DataBindings.cpx (new and old (obsolete) elements in this file, <pageMap> and <pageDefinitionUsages>, referring to the new- and old <GroupName>.jspx and <GroupName>.pageDef files)
  • web.xml (one new and one old (obsolete) entry in the attribute <param-value> in the element <context-param> (with param-name ‘javax.faces.CONFIG_FILES’) referring to <newGroupname>-beans.xml and the obsolete <oldGroupname>-beans.xml)
  • JHS_TRANSLATIONS table (the file ApplicationResources_<ServiceName>.sql is correctly updated and inserts new rows in the JHS_TRANSLATIONS table but it does not delete (obsolete) rows referring to the old group name (titels, labels))

OBSOLETE FILES:

  • <oldGroupName>.pageDef.xml
  • <oldGroupName>.jspx
  • <oldGroupName>Table.jspx
  • <oldGroupName>-beans.xml  

Important: Realize JHS will generate a complete new pageDefinition for your renamed group and if you made custom post generation changes in your <oldGroupName>PageDef.xml file, these changes (of course) won’t be in the <newGroupName>PageDef.xml, you have to make your post generation changes yourself again!

After you have renamed the group name you must regenerate the application. The application will still work fine, but now you have a lot of obsolete code and files that you don’t need to maintain anymore, and these files or parts of files are recommended to be removed:

  • Obsolete files can be deleted in JDeveloper.
  • Removing obsolete elements in DataBindings.cpx and one element web.xml is straightforward but you have to localize the elements yourself and remove them manually in JDeveloper.
  • Removing rows from the JHS_TRANSLATIONS table is also straightforward. You can manually remove the obsolete rows or you can run the following SQL script: "  delete from jhs_translations where key1 like ‘%<oldGroupName -minus last character of oldGroupName>%  ".

Note: If your group that you want to rename is detailgroup that is presented in a region, you also have to correct the group name for that region.

  • item name

-YES

impact: very small

Only one very small issue: If the item you rename is on group-level the value for a ‘Default Search Item’ and/or a ‘Descriptor Item’, you have to refresh these values by selecting the new name in the dropdown-list. And then regenerate. There are no obsolete files or obsolete elements in files.

Files correctly updated:  

  • <parentGroupOfGroupOfItem>.pageDef.xml in case the group of your renamed item is a detailgroup in a region of this parent group.
  • <parentGroupOfGroupOfItem>.jspx in case the group of your renamed item is a detailgroup in a region of this parent group.
  • <childGroupOfGroupOfItem>.jspx in case the group of your renamed item is a parentgroup and has a region containing this child group.
  • <GroupOfItem>.jspx
  • <GroupOfItem>.pageDef.xml
  • <GroupOfItem>-beans.xml
  • <serviceName>-Breadcrumb-beans.xml
  • <serviceName>ApplicationDefinition.xml
  • region name
-

Files correctly updated:

  • <serviceName>ApplicationDefinition.xml 
  • <groupOfRegion>.jspx 

 

Share.

About Author

Frank Houweling is an Oracle ADF and Java specialist with AMIS (The Netherlands). He focuses mainly on Oracle Fusion ADF, Java Enterprise development and performance management. During the past years he has been requested several times as troubleshooter of ADF projects with bad performance. As such he has been performing performance analysis, bottleneck detection and developing mitigating solutions based on these analysis. He is also the creator of the AMIS ADF Performance Monitor, an advanced monitor that can identify, report and help solve performance bottlenecks in ADF applications.

5 Comments

  1. Frank Houweling on

    Lucas, John: I have added:
    -Renaming an item and a region in a JHeadstart Application Definition.
    -Remarks about consequences for the AFD model layer, particularly that pageDefinition en JSPX files are not updated when you rename a VO instance or VO attribute, which is correct (but maybe not expected) because the BC and model are separated layers.

  2. Very useful overview Frank.Well done.

    Have you per chance also looked at renaming an Item (and a Region) in a JHeadstart Application Definition? What is your recommendation for removing the obsolete entries from the DataBindings.cpx file or the Resource Bundles? Are these straightforward but manual actions?

    Steve Muench writes that in JDeveloper 11g (from TP3 onwards) refactoring for ADF BC is enabled: Refactoring ADF BC.
    Lucas

  3. Frank,

    Well done! I believe there are also probably some pageDef.xml issues when re-factoring straight BC objects (without JHeadstart), particularly if a VO or AM is renamed.

    But well, done, sir, well done

    John