About Oracle ADF Application Modules

Oracle ADF application modules are business components that represent particular application tasks. The application module provides a data model for the task by aggregating the view object and view link instances required for the task. It also provides services that help the client accomplish the task. For example, an application module can represent and assist with tasks such as:

Updating customer information
Creating a new order
Processing salary increases

To define an application module, see Assembling a Data Model.

Data Models

An application module contains view object instances that retrieve the data needed by the client, as well as view link instances that specify the relationships between the view object instances. The view object and view link instances can be represented by a tree, called the application module's data model.

For example, suppose you have the following business component definitions:

CustomersView, a view object definition containing the query
SELECT * FROM CUSTOMERS

OrdersView, a view object definition containing the query
SELECT * FROM ORDERS

CustOrdLink, a view link definition linking CustomersView and OrdersView, with CustomersView's CustomerId as the source attribute and the parametrized WHERE clause
WHERE :1 = ORDERS.CUSTOMER_ID

You could then define an application module, FindOrdersForCustomerModule, with the following data model:

A three-level tree.

In this data model, AllCustomers is an instance of CustomersView, CustomerOrders is an instance of OrdersView, and CustOrdLink1 is an instance of CustOrdLink. When a particular row of AllCustomers (for example, Customer 101) is selected, CustomerOrders' rowset will be restricted to be the results of the query

SELECT * FROM ORDERS
WHERE 101 = ORDERS.CUSTOMER_ID

That is, only the orders of Customer 101 will be visible through CustomerOrders.

You could also define an application module, ShowOrdersAndCustomersModule, with the following data model:

A two-level tree.

In this data model, AllCustomers is an instance of CustomersView, and AllOrders is an instance of OrdersView. Selections of rows from AllCustomers and AllOrders are independent; all rows from CustomersView and OrdersView are visible at all times.

For more information, see the related topics list.

Application Module Definitions and Application Module Instances

Often, it is important to distinguish between the following:

Application module definitions, which consist of the XML file and possibly an extended application module class (see below) for the application module
Application module instances, which are particular references to a Oracle ADF application module definition

You create an application module definition using JDeveloper's tools. Then, your client can create an instance of that application module to access data. You can also add an application module instance to another application module definition. This process, called nesting application modules, allows you to reuse small tasks (represented by small application module definitions) as parts of larger tasks (represented by application module definitions containing an instance of the smaller application module). For more information, see the related topics list.

Application Modules and Clients

Because application modules are data model components, you should consider your client's data needs when defining them. Ask yourself the following questions before designing an application module:

What task is my client going to perform with this application module?
What data does it need to perform that task? Which view object definitions provide this data? How many instances of each will I need?
What sets of data should stand in master-detail relationships?

This will allow you to design your application module efficiently, without retrieving and storing more data than necessary and without having to programmatically relate data for your client.

Application modules can also contain service methods--methods that perform complex operations on data. These methods can be called from clients, requiring very little data manipulation processing in the client itself. For more information, see the realted topics list.

Application Modules and Transactions

In general, one application module instance owns a single database transaction. All changes made through that instance are made in a single transaction, which can be rolled back or committed at any time.

There are two cases where an application module instance does not own a database transaction:

Application modules deployed as EJB session beans with container-managed transactions. In this case, the transaction is owned by the EJB container. For more information, see the related topics list.
Nested application module instances. These share the top-level application module's transaction.

For more information about working with transactions, see the related topics list.

Application Modules, XML Files, and Java Classes

Like most business components, individual application modules are partially defined by XML files. These files specify the data model and nested application module instances for the application module definition.

If an XML file satisfies your needs for a particular application module, you may not need to extend any classes or write any Java code.

In addition to XML files, application modules are optionally defined by a Java class, the application module class. This class includes any service methods or extended code required by the application module.