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? |
|
YES Impact: medium | refactored correctly:
NOT CORRECTLY REFACTORED:
For details see the ADF-BC solutions table below. Note: After renaming this object you could consider (but is absolutely not necessary) to change:
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). |
|
– | refactored correctly:
|
– |
|
– | refactored correctly:
|
– |
|
YES Impact:small | refactored correctly:
NOT CORRECTLY REFACTORED:
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. |
|
YES*
(*only in case JHeadstart is not used. Impact: medium) |
refactored correctly:
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. |
|
YES*
(*only in case JHeadstart is not used. Impact: medium) |
refactored correctly:
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:
|
YES (impact: small)
Refresh corresponding JHS ‘data collection’ and regenerate. For details see the ADF-BC solutions table below. |
|
YES Impact:small | refactored correctly:
NOT CORRECTLY REFACTORED:
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. |
– |
|
– | refactored correctly:
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. |
– |
|
YES Impact:small | refactored correctly:
NOT CORRECTLY REFACTORED:
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
|
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.
|
|
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. |
|
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. |
|
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. |
|
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.
|
|
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? |
|
YES impact: medium to big | New files created:
Files correctly updated:
Files correctly added with new elements BUT NOW HAVE OBSOLETE ELEMENTS:
OBSOLETE FILES:
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:
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. |
|
–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:
|
|
– | Files correctly updated:
|
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.
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
hi
This forum thread is somewhat related, “ADF BC : change Entity attribute type to DBSequence”:
http://forums.oracle.com/forums/thread.jspa?threadID=602081
regards
Jan Vervecken
Great post Frank.
CM
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