Background 

Most Oracle ADF-based development projects require code reorganisation  during their lifetime.  A significant reason of the reorganisation task is that the application was developed using the default JDeveloper ADF Application project structure. Reorganisation of this structure , along with good source control practices will save significant effort during the project lifetime.

Oracle Default Project Structure

Oracle JDeveloper provides a New Application Wizard which allows the user to create a new ADF application. This application consists of two projects, one for the model and the other for the view-controller. The model will contain one or more application modules. The view controller project will use the model to access the database. A sample new ADF project is displayed in Figure 1 below.

It is common in new projects\greenfield developments for projects to commence by placing all model objects for the application in a single application module. The application module is created when the wizard is called for the first time to generate ADF business components from the database tables. It is this placing of all model objects in a single application module that gives rise to problems later in the project, particularly in the areas of developer code sharing and code conflicts. To avoid these problems another approach can be employed. The developer can group application\business logic into smaller application modules (e.g. customer management, order entry), each one in its own Oracle ADF project and producing its own separate jar file.

Best Practice ADF Project Structure

The following approach may be taken to ensure that an ADF application scales successfully (i.e. scales as more modules are added and scales as more developers are added to the project):

Use root and nested application modules in your ADF application. The detailed information on how to implement it is out of scope of this document, however there are many blogs and tutorials on how to achieve it for example Oracle doc http://docs.oracle.com/cd/E24382_01/web.1112/e16182/bcservices.htm#ADFFD1506 . Another good example is Andrejus Baranovskis Blog: http://andrejusb.blogspot.com/2010/06/adf-regions-and-nested-application.html.
Make sure that your application modules subclass one application module with all relevant generic code included. This superclass should act as a “buffer zone” to accommodate any future additional requirements for all modules. In fact this approach is recommended by Oracle ADF best practice and applies to all basic model classes like ViewObjectImpl. The information about it can be found in the section “Setting Up Your Own Layer of Framework Base Classes” in the page : http://www.oracle.com/technetwork/developer-tools/jdev/index-083535.html#settingupbaseclasses
Group business logic into logical groups\functional areas. Create an application module for each grouping in a separate Oracle ADF project with each producing a separate jar file. Doing so allows the application to be logically decomposed, facilitates easier understanding of the application and enables efficient team work/reduces conflicts. As an aside, one nice feature of JDeveloper is the ability to view the contents of a jar file which is included in a project. Figure two below illustrates how to configure a read only view of libraries.

Project Source Control

Source control in JDeveloper can be performed on an integrated basis with JDeveloper or externally via source control products like Subversion. It is important that the initial check in of the ADF application should include all application files. It should be noted that JDeveloper changes a large number of files within the application when checking in so a complete check in is necessary. Using source control properly forces the developer to pay attention to which files have changed in the application.  An understanding of what and why files change is of significant learning value to the developer.

To summarize:

• The structure of new Oracle ADF applications should be carefully designed as early as possible in the project lifecycle.
• You should  split the application into smaller logical units which group related application logic together.
• You should use root and nested application modules.
• You should use Framework Base Classes (refer to above links for details).
• Every application file should be checked into the source control system and carefully reviewed during each commit process.

If you would like further details about any of the topics raised in this post please email Tomasz Zwierzchowski.