5.3 Using a View Object in an Application Module's Data Model

Any view object you create is a reusable component that can be used in the context of one or more application modules to perform the query it encapsulates in the context of that application module's transaction. The set of view objects used by an application module defines its data model, in other words, the set of data that a client can display and manipulate through a user interface. To start simple, create an application module and use the single view object you created above in the application module's data model.

5.3.1 How to Create an Application Module

To create an application module, use the Create Application Module wizard. The wizard is available from the New Gallery in the Business Tier > ADF Business Components category. As shown in Figure 5-6, provide a package name, and an application module name. The figure shows creating an application module UserService in the devguide.examples package.

Figure 5-6 Defining the Package and Component Name for a New Application Module

In step 2 on the Data Model page, Figure 5-7 illustrates that initially the data model is empty. That is, it contains no view object instances yet. The Available View Objects list shows all available view objects in your project, organized by package.

Figure 5-7 Defining the Data Model For a New Application Module

To add an instance of a view object to the data model, first select it in the Available list. The Name field below the list shows the name that will be used to identify the next instance of that view object that you add to the data model. By typing in a different name before pressing the add instance button >, you can change the name to be anything you like. Finally, to add an instance of the selected view object to the data model, identified by the instance name shown below, click the add instance button (>).

Assuming you decide on the instance name of UserList, Figure 5-8 shows what the Data Model page would look like after adding the instance. The Instance Name field below the selected view object instance in the Data Model list allows you to see and change the instance name if necessary. The Definition field displays the fully-qualified name of the view object component that will be used to create this view object instance at runtime. You see as expected that the definition that will be used is devguide.examples.Users view object.

Figure 5-8 Data Model With One Instance Named UserList of the Users View Object

5.3.1.1 Understanding the Difference Between View Object Components and View Object Instances

It is important to understand the distinction between a view object component and a view object instance. The easiest way to understand the distinction is to first consider a visual example. Imagine that you need to build a Java user interface containing two buttons. Using JDeveloper's visual editor, you might create the page shown in Figure 5-9 by using the Component Palette to select the JButton component and click to add a JButton component to your panel. Repeating that same step a second time, you can drop another button onto the panel. You are designing a custom JPanel component that uses two instances of the JButton component. The panel does not own the JButton class, it's just using two instances of it.

Figure 5-9 Designing a Panel That Contains Two Instances of the JButton Component

If you were to peek into the Java code of this new panel you're designing, you'd notice that there are two member fields of type JButton to hold a reference to the two instances of the button the panel is using. To distinguish the two instances in the code, one member field is named myButton, and the other member field is named anotherButton:

Example 5-1 Two Instances of a JButton Component

public class Panel1 extends JPanel implements JUPanel {
  private JButton myButton      = new JButton(); // First instance
  private JButton anotherButton = new JButton(); // Second instance
  // etc.
}

Even though the application module is a nonvisual component, you can still apply this same intuition about components, instances, and distinct member names to help understand the concept better. While designing an application module, you use instances of a view object component to define its data model. Figure 5-10 shows a JDeveloper business components diagram of a UserService application module. Just as the panel in Example 5-1 contained two instances of the JButton component with member names of myButton and anotherButton to distinguish them, your application module contains two instances of the Users view object component, with member names of UserList and AnotherUserList to distinguish them. At runtime, the two JButton instances are both based on the same definition — which explains why they both have the same set of properties and both exhibit JButton-like behavior. However the values of their properties like Position and Text are different. So too for the different instances of the Users view object in your UserService application module. At runtime, both instances share the same Users view object component definition — ensuring they have the same attribute structure and Users view object behavior — however, each might be used independently to retrieve data about different users. For example, some of the runtime properties like an additional filtering WHERE clause or the value of a bind variable might be different on the two distinct instances.

Figure 5-10 Designing an Application Module That Contains Two Instances of the Users View Object Component

Besides the obvious fact that one example is a visual panel while the other is a nonvisual data model component, the only logical difference is how the instances and member names are defined. In the visual panel in Example 5-1, you saw that the two member fields holding the distinct JButton instances were declared in code. In contrast, the UserService application module defines its member view object instances in its XML component definition file:

Example 5-2 Application Modules Define Member View Objects in XML

<AppModule Name="UserService">
   <ViewUsage Name="UserList" ViewObjectName="devguide.examples.Users"/>
   <ViewUsage Name="AnotherUserList" ViewObjectName="devguide.examples.Users"/>
</AppModule>

5.3.2 What Happens When You Create an Application Module

When you create an application module, JDeveloper creates the XML component definition file that represents its declarative settings and saves it in the directory that corresponds to the name of its package. In the example in Figure 5-6, the application module was named UserService in the devguide.examples package, so the XML file created will be ./devguide/examples/UserService.xml under the project's source path. This XML file contains the information needed at runtime to recreate the view object instances in the application module's data model. If you're curious to see its contents, you can see the XML file for the application module by selecting the view object in the Application Navigator and looking in the corresponding Sources folder in the Structure window. Double-clicking the UsersService.xml node will open the XML in an editor so that you can inspect it.

Note: If your IDE-level Business Components Java generation preferences so indicate, the wizard may also create an optional custom application module class UsersServiceImpl.java.

5.3.3 What You May Need to Know About Application Modules

After you've created an application module, you can edit any of its settings by using the Application Module Editor. Select the Edit menu option on the context menu in the Application Navigator to launch the application module. By opening the different panels of the editor, you can adjust the view object instances in the data model, control Java generation options, and other settings you'll learn about in later chapters.

5.3.3.1 Editing an Application Module's Runtime Configuration Properties

Since it can be convenient to define and use multiple sets of runtime configuration properties each application module supports multiple, named runtime configurations. When you create an application module, JDeveloper creates a default set of runtime configuration properties for the application module. For an application module named YourService, its default set of configuration properties will be named YourServiceLocal. These settings are stored in an XML file named bc4j.xcfg in a subdirectory named common, relative to where the application module's XML component definition resides. For example, when you created the UserService application module above in the devguide.examples package, JDeveloper creates the file bc4j.xcfg in the ./devguide/examples/common directory under the project's source path.

You can use the application module configuration manager to edit existing configurations or create new ones. To access the configuration manager, select the desired application module in the Application Navigator and choose Configurations...from the context menu. The Configuration Manager dialog appears, as shown in Figure 5-11. You can see the default UserServiceLocal configuration for the UserService application module. Any additional configurations you create, or any configuration properties you edit, are saved in the same bc4j.xcfg.

Figure 5-11 Application Module Configuration Manager

Click the Edit button in the Configuration Manager to edit a specific configuration. As shown in Figure 5-12, this editor allows you to configure the database connection information, a number of pooling and scalability settings, and a final tab of remaining properties that aren't covered by the first two tabs. All of the runtime properties and their meanings are covered in the JDeveloper online help.

Figure 5-12 Oracle Business Component Configuration Editor

Note: When building web applications, set the jbo.locking.mode property to optimistic. The default value is pessimistic, which is not the correct value for web applications. You can find this property listed alphabetically in the Properties tab of the Configuration Editor.