8.2 Creating an Application Module

In a large application, you typically create one application module to support each coarse-grained end-user task. In a smaller-sized application like the SRDemo application, you may decide that creating a single application module is adequate to handle the needs of the complete set of application functionality. Section 8.9, "Deciding on the Granularity of Application Modules" provides additional guidance on this subject.

8.2.1 Creating an Application Module

To create an application module:

Open Create Application Module Wizard. The wizard is available from the New Gallery in the Business Tier > ADF Business Components category.
In step 1 on the Name pane, provide a package name and an application module name.
In step 2 on the Data Model page, include instances of view object you have previously defined and adjust the view object instance names to be exactly what you want clients to see. Then click Finish.

For more step by step details, see Section 5.3, "Using a View Object in an Application Module's Data Model".

8.2.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. For example, given an application module named SRService in the devguide.model package, the XML file created will be ./devguide/model/SRService.xml under the project's source path. This XML file contains the information needed at runtime to re-create 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 on the SRService.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 SRServiceImpl.java.

8.2.3 Editing an Existing Application Module

After you've created a new application module, you can edit any of its settings by using the Application Module Editor. Choose the Edit menu option on the right-mouse context menu in the Application Navigator, or double-click on the application module, to launch the editor. By visiting the different panels of the editor, you can adjust the data model, Java generation settings, remote deployment options, client interface methods, and custom properties.

8.2.4 Configuring Your Application Module Database Connection

You configure your application module to use a database connection by identifying either a Java Database Connectivity (JDBC) URL or a JDBC Datasource name in the Connection Type section of the Configuration editor (see Figure 5-12).

8.2.4.1 Using a JDBC URL Connection Type

The default YouAppModuleLocal configuration uses a JDBC URL connection. It is based on the named connection definition set on the Business Components page of the Project Properties dialog for the project containing your application module. Figure 8-2 shows what this section would look like in a configuration using a JDBC URL connection based on the SRDemo connection name. When you use a JDBC URL connection type as the SRServiceLocalTesting configuration does in the SRDemo application, you can use the application module in any context where Java can run. In other words, it is not restricted to running inside a J2EE application server with this connection type.

Figure 8-2 Connection Type Setting in Configuration Editor

Image of connection type setting in Configuration editor

Note:

See Section 29.5.2, "Database Connection Pools" and Section 29.7, "Database Connection Pool Parameters" for more information on how database connection pools are used and how you can tune them.

8.2.4.2 Using a JDBC Datasource Connection Type

The other type of connection you can use is a JDBC datasource. You define a JDBC datasource as part of your application server configuration information, and then the application module looks up the resource at runtime using a logical name. You define the datasource connection details in two parts:

a logical part that uses standard J2EE deployment descriptors to define the datasource name the application will use at runtime,
a physical part that is application-server specific which maps the logical datasource name to the physical connection details.

For example, Example 8-1 shows the resource-ref tags in the web.xml file of the SRDemo application. These define two logical datasources named jdbc/SRDemoDS and jdbc/SRDemoCoreDS. When you use a JDBC datasource connection for your application module, you reference this logical connection name after the prefix java:comp/env. Accordingly, if you inspect the SRServiceLocal configuration for the SRService application module in the SRDemo application, you'll see that the value of its JDBC Datasource Name field is java:comp/env/jdbc/SRDemoDS.

Example 8-1 Logical Datasource Resource Names Defined in web.xml

  <!-- In web.xml -->
  <resource-ref>
    <res-ref-name>jdbc/SRDemoDS</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>
  <resource-ref>
    <res-ref-name>jdbc/SRDemoCoreDS</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>

Once you've defined the logical datasource names in web.xml and referenced them in a configuration, you then need to include additional, server-specific configuration files to map the logical datasource names to physical connection definitions in the target application server. Example 8-2 shows the contents of the SRDemo application's data-sources.xml file. This file is specific to the Oracle Containers for J2EE (OC4J) and defines the physical details of the datasource connection pools and connection names. You would need to provide a similar file for different J2EE application servers, and the file would have a vendor-specific format.

Example 8-2 Datasource Connection Details Defined External to Application

<data-sources ... >
    <connection-pool name="jdev-connection-pool-SRDemo">
        <connection-factory
            factory-class="oracle.jdbc.pool.OracleDataSource"
            password="->DataBase_User_8PQ34e6j3MDg3UcQD-BZktUAK-QpepGp"
            user="srdemo" url="jdbc:oracle:thin:@localhost:1521:XE"/>
    </connection-pool>
    <managed-data-source name="jdev-connection-managed-SRDemo"
                        jndi-name="jdbc/SRDemoDS" 
                        connection-pool-name="jdev-connection-pool-SRDemo"/>
    <native-data-source name="jdev-connection-native-SRDemo"
                        jndi-name="jdbc/SRDemoCoreDS" ... />
</data-sources>

The last step in the process involves mapping the physical connection details to the logical resource references for the datasource. In the OC4J server, you accomplish this step using the orion-web.xml file shown in Example 8-3.

Example 8-3 Server-Specific File Maps Logical Datasource to Physical Datasource

<orion-web-app ... >
  <resource-ref-mapping location="jdbc/SRDemoDS" name="jdbc/SRDemoDS"/>
  <resource-ref-mapping location="jdbc/SRDemoCoreDS" name="jdbc/SRDemoCoreDS"/>
</orion-web-app>

Once these datasource configuration details are in place, you can successfully use your application module in a J2EE application server as part of a web application.

8.2.5 Managing Your Application Module's Runtime Configurations

In addition to creating the application module XML component definition, JDeveloper also adds a default configuration named SRServiceLocal to the bc4j.xcfg file in the subdirectory named common relative to directory containing the SRService.xml file. To manage your application module's configurations, select it in the Application Navigator and choose Configurations... from the right-mouse context menu.

8.2.6 What You Might Need to Know About Application Module Connections

When testing your application module with the Business Component Browser, you should be aware of the connection configuration.

8.2.6.1 The Business Components Browser Requires a JDBC URL Connection

In previous chapters you've learned how valuable the Business Components Browser tool can be for testing your application module's data model interactively. Since it runs outside the context of a J2EE application server, it cannot test application modules using a configuration that depends on a JDBC datasource. The solution is simply to test the application module by selecting a configuration that uses a JDBC URL connection. You do this by choosing it from the Business Component Configuration Name dropdown list on the Connect dialog of the Business Components Browser.

8.2.6.2 Testing the SRService Application Module in the Business Components Browser

To test the SRDemo application's SRService application module using the Business Components Browser, choose the SRServiceLocalTesting configuration. Incidentally, this is the same configuration used by the JUnit tests in the UnitTests project in the workspace. The tests also run outside of a J2EE application server so for the same reason as the Business Components Browser cannot use a configuration with a JDBC datasource connection type.