Reusable ADF Components—Application Modules

In the course of application development, certain components will often be reused. Creating and consuming reusable components should be included in the early design and architectural phases of software projects.

Whether the reuse happens within the same application, or across different applications, it is often advantageous to package these reusable components into a library that can be shared between different teams. These shared libraries can be added to a repository. Later if you need a component, you may look into the repository for something to be reused.

Multiple Oracle ADF components are reusable, which include^[1]:

• Application modules
• Business Components
• Data controls
• Task flows
• Page templates
• Declarative components

These reusable components can be packaged into the ADF Library for reuse in applications (see [4] for how-to). Creating an ADF Library JAR involves compiling the project and validating the components, creating a resource service file, control files, an adflibREADME.txt, and adding the relevant project files into a JAR.

In this article, we will discuss a specific reusable component—Application Module. Application modules are associated with Business Components. When the reusable application module was packaged, the JAR includes the Business Components used to create the application module. These components will be available for reuse.

For packaging application modules, JDeveloper adds three control files to the JAR:

1. oracle.adf.common.services.ResourceService.sva
2. Manifest.mf
3. adfm.xml

The service resource file for an application module includes entries for the Business Components associated with the application module, as well as an entry for the application module data control.

When you add an application module to a project, the application module appears in the Data Controls panel.

What's Application Module

Within a running BC4J application, one can think of the following containership of application objects:

• Root Application Module contains nested Application Modules
• An Application Module contains View Objects
• A View Object contains Row Sets
• A Row Set contain Row Set Iterators

Application Modules can be nested. That is, an Application Module can (logically) contain one or more other Application Modules (i.e., nested AMs) as well as View Objects. The outermost containing Application Module is referred to as the "root" Application Module.

What Do You Need to Know about Nested Application Module

In this Andrejus Baranovskis' article, it has two application modules which contain View Objects created from Employee and Job tables and are packaged into two ADF libraries

1. adflibEmplooyeesApp.jar
2. adflibJobsApp.jar
   

These two libraries can be imported into an ADF web application in two ways:

1. Integrating ADF JAR's directly into the ViewController project (i.e., using Application Modules directly from ADF JAR's)
2. Integrating ADF JAR's into the Model project with its own Application Module (i.e., Application Components from imported libraries are created as nested Application Modules)

Using either approach, you need to add both JAR's to the application first. When you add an ADF Library JAR to a project, either by using the Resource Palette or by manually adding the JAR, an ADF Library definition is created in the project. The ADF Library JAR file will be added to the class path of the project. The project will access and consume the components in the JAR by reference. See here for how to add an ADF Library JAR to a project using the Resource Palette.

In the first approach, two JAR's are added to the consuming project's (i.e., ViewController project) class path and so is available for reuse. See here on how to add them to the ViewController project manually. As shown below, adflibEmployeesApp.jar and adflibJobsApp.jar are added to the ViewController project's class path:
In the second approach, you first create a new Application Module (i.e., HrModule) in the Model project. See here on how-to. To specify a composite root application module that nests an instance of an existing application module, you use the overview editor for the application module. See here on how-to.

As shown below, EmpModule and JobsModule are nested under root Application Module HrModule in the second approach:
Important notes about nested application modules:

• A nested Application Module design is useful for applications that define several functional
sub-applications that share the same transaction context and transaction caches.

• With a nested Application Module design, it is easy to re-deploy nested Application Modules as standalone Application Modules in different client applications without having to modify the metadata for the other existing Application Module.
• When a root application module contains other nested application modules, they all participate in the root application module's transaction and share the same database connection and a single set of entity caches.
  • This sharing is handled for you automatically by the root application module and its "Transaction" object.
• A nested Application Module cannot see the instances of any other Application Modules that might be nested beneath the same root.
• The API for application modules also supports nesting of application modules at runtime.
• Nested Application Module can help performance by reducing database connection usage (i.e., sharing a single database connection instead of owning a separate connection per AM).
  

Further Considerations

• You should consider how to organize and group the library JARs in a structure that fits your organizational needs. For example,
  • Usually you want to have two separate application modules to support UIs and define services because
    • UI application modules may contain additional view objects and context values
      that are only required for a particular UI, but not needed by a business service.
    • Application modules that define public services are versioned, but internal UI
      application modules are not.
      
• You should also consider creating standardized naming conventions so that both creators and consumers of ADF Library JARs can readily identify the component functionality.
  • You want to try to have unique names to avoid naming conflicts with other projects, components, or connections in the application.
  • Naming conflicts could arise from components created in the consuming application and those loaded from other JAR files.
• A project corresponds to one ADF Library JAR.
  • If you create multiple projects and want to reuse components from each of the projects, you may need to create an ADF Library JAR for each project.
• You can package multiple components into one JAR file, or you can package a single component into a JAR file.
  • Oracle ADF and JDeveloper give you the option and flexibility to create reusable components that best suit you and your organization.
• You should avoid metadata naming conflicts between projects that will be combined at runtime.
  • The basic package naming requirement is that ADF metadata registries (.dcx,.cpx, and so on) are generated based on the project's package name. So, make the package name unique.
    

References

1. Reusing Application Components
2. Defining Nested Application Modules
3. What you may need to know about Nested Application Module
   
4. How to Package a Component into an ADF Library JAR