Skip Headers
Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers
10g Release 3 (10.1.3.0)
B25947-01
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

25.1 Globally Extending ADF Business Components Functionality

One of the powerful features of framework-based development is the ability to extend the base framework to change a built-in feature to behave differently or to add a new feature that can be used by all of your applications. This section describes:

25.1.1 What Are ADF Business Components Framework Extension Classes?

An ADF Business Components framework extension class is Java class you write that extends one of the framework's base classes to:

  • Augment a built-in feature works with additional, generic functionality

  • Change how a built-in feature works, or even to

  • Workaround a bug you encounter in a generic way

Once you've created a framework extension class, any new ADF components you create can be based on your customized framework class instead of the base one. Of course, you can also update the definitions of existing components to use the new framework extension class as well.

25.1.2 How To Create a Framework Extension Class

To create a framework extension class, follow these steps:

  1. Identify a project to contain the framework extension class.

    You can create it in the same project as your business service components if you believe it will only be used by components in that project. Alternatively, if you believe you might like to reuse the framework extension class across multiple ADF applications, create a separate FrameworkExtensions project (as shown in the SRDemo application) to contain the framework extension classes.

  2. Ensure the BC4J Runtime library is in the project's libraries list.

    Use the Libraries page of the Project Properties dialog to verify this and to add the library if missing.

  3. Create the new class using the Create Java Class dialog.

    This dialog is available in the New Gallery in the General category.

  4. Specify the appropriate framework base class from the oracle.jbo.server package in the Extends field.

    Figure 25-1 illustrates what it would look like to create a custom framework extension class named CustomAppModuleImpl in the com.yourcompany.fwkext package to customize the functionality of the base application module component. To quickly find the base class you're looking for, use the Browse button next to the Extends field that launches the JDeveloper Class Browser. Using its Search tab, you can type in part of the class name (including using * as a wildcard) to quickly subset the list of classes to find the one you're looking for.

    Figure 25-1 Creating a Framework Extension Class for an Application Module

    Image of Create Java Class dialog

When you click OK, JDeveloper creates the custom framework extension class for you in the directory of the project's source path corresponding to the package name you've chosen.


Note:

Some ADF Business Components component classes exist in both a server-side and a remote-client version. For example, if you use the JDeveloper Class Browser and type ApplicationModuleImpl into the Match Class Name field on the Search tab, the list will show two ApplicationModuleImpl classes: one in the oracle.jbo.server package and the other in the oracle.jbo.client.remote package. When creating framework extension classes, use the base ADF classes in the oracle.jbo.server package.

25.1.3 What Happens When You Create a Framework Extension Class

After creating a new framework extension class, it will not automatically be used by your application. You must decide which components in your project should make use of it. The following sections describe the available approaches for basing your ADF components on your own framework extension classes.

25.1.4 How to Base an ADF Component on a Framework Extension Class

You can set the base classes for any ADF component using the Java page of any ADF Business Components wizard or editor. Before doing so, review the following checklist:

  • If you have decided to create your framework extension classes in a separate project, ensure that you have visited the Dependencies page of the Project Properties dialog for the project containing your business components in order to mark the FrameworkExtension project as a project dependency.

  • If you have packaged your framework extension classes in a Java archive (JAR) file, ensure that you have created a named library definition to reference its JAR file and also listed that library in the library list of the project containing your business components. To create a library if missing, use the Manage Libraries dialog available from the Tools | Manage Libraries main menu item. To verify or adjust the project's library list, use the Libraries page of the Project Properties dialog.

After you ensure the framework classes are available to reference, Figure 25-2 shows how you would use the CustomAppModuleImpl class as the base class for a new application module. By clicking the Class Extends button of the Java page of the wizard, the Extends dialog displays to let you enter the fully-qualified name of your framework extension class (or use the Browse button to use the JDeveloper Class Browser to find it quickly).

Figure 25-2 Specifying a Custom Base Class for a New Application Module

Image of Extends dialog when specifying a custom base class

The same Class Extends button appears on the Java page of every ADF Business Components wizard and editor, so you can use this technique to choose your desired framework extension base class(es) both for new components or existing ones.


Note:

When using the JDeveloper Class Browser in the Extends dialog of an ADF Business Components wizard or editor to select a custom base class for the component, the list of available classes is automatically filtered to show only classes that are appropriate. For example, when clicking Browse in Figure 25-2 to select an application module Object base class, the list will only show classes available in the current project's library list which extend the oracle.jbo.server.ApplicationModule class either directly or indirectly. If you don't see the class you're looking for, either you extended the incorrect base class or you have chosen the wrong component class name to override.

25.1.5 What Happens When You Base a Component on a Framework Extension Class

When an ADF component you create extends a custom framework extension class, JDeveloper updates its XML component definition to reflect the custom class name you've chosen.

25.1.5.1 Basing an XML-Only Component on a Framework Extension Class

For example, assume you've created the YourService application module above in the com.yourcompany.yourapp package, with a custom application module base class of CustomAppModuleImpl. If you have opted to leave the component as an XML-only component with no custom Java file, its XML component definition (YourService.xml) will look like what you see in Example 25-1. The value of the ComponentClass attribute of the AppModule tag is read at runtime to identify the Java class to use to represent the component.

Example 25-1 Custom Base Class Names Are Recorded in XML Component Definition

<AppModule
   Name="YourService"
   ComponentClass="com.yourcompany.fwkext.CustomAppModuleImpl" >
  <!-- etc. -->
</AppModule>

Figure 25-3 illustrates how the XML-only YourService application module relates to your custom extension class. At runtime, it uses the CustomAppModuleImpl class which inherits its base behavior from the ApplicationModuleImpl class.

Figure 25-3 XML-Only Component Reference an Extended Framework Base Class

Image shows flow of extended framework base class

25.1.5.2 Basing a Component with a Custom Java Class on a Framework Extension Class

If your component requires a custom Java class, as you've seen in previous chapters you open the Java page of the component editor and check the appropriate checkbox to enable it. For example, when you enable a custom application module class for the YourServer application module, JDeveloper creates the appropriate YourServiceImpl.java class. As shown in Example 25-2, it also updates the component's XML component definition to reflect the name of the custom component class.

Example 25-2 Custom Component Class Recorded in XML Component Definition

<AppModule
   Name="YourService"
   ComponentClass="com.yourcompany.yourapp.YourServiceImpl" >
  <!-- etc. -->
</AppModule>

JDeveloper also updates the component's custom Java class to modify its extends clause to reflect the new custom framework base class, as shown in Example 25-3.

Example 25-3 Component's Custom Java Class Updates to Reflect New Base Class

package com.yourcompany.yourapp;
import com.yourcompany.fwkext.CustomAppModuleImpl;
// ---------------------------------------------------------------------
// ---    File generated by Oracle ADF Business Components Design Time.
// ---    Custom code may be added to this class.
// ---    Warning: Do not modify method signatures of generated methods.
// ---------------------------------------------------------------------
public class YourServiceImpl extends CustomAppModuleImpl {
  /**This is the default constructor (do not remove)   */
  public YourServiceImpl() {}
  // etc.
}

Figure 25-4 illustrates how the YourService application module with its custom YourServiceImpl class is related to your framework extension class. At runtime, it uses the YourServiceImpl class which inherits its base behavior from the CustomAppModuleImpl framework extension class which, in turn, extends the base ApplicationModuleImpl class.

Figure 25-4 Component with Custom Java Extending Customized Framework Base Class

Image of flow of extended customized framework class

25.1.6 What You May Need to Know

{para}?>

25.1.6.1 Don't Update the Extends Clause in Custom Component Java Files By Hand

If you have an ADF component with a custom Java class and later decide to base the component on a framework extension class, use the Class Extends button on the Java page of the component editor to change the component's base class. Doing this updates the component's XML component definition to reflect the new base class, and also modifies the extends clause in the component's custom Java class. If you manually update the extends clause without using the component editor, the component's XML component definition will not reflect the new inheritance and the next time you open the editor, your manually modified extends clause will be overwritten with what the component editor believes is the correct component base class.

25.1.6.2 You Can Have Multiple Levels of Framework Extension Classes

In the examples above, you've seen a single CustomAppModuleImpl class that extends the base ApplicationModuleImpl class. However, there is no fixed limit on how many levels of framework extension classes you create. After creating a company-level CustomAppModuleImpl to use for all application modules in all ADF applications your company creates, some later project team might encounter the need to further customize that framework extension class. That team could create a SomeProjectCustomAppModuleImpl class that extends the CustomAppModuleImpl and then include the project-specific custom application module code in there:

public class SomeProjectCustomAppModuleImpl
       extends CustomAppModuleImpl {
  /*
   * Custom application module code specific to the
   * "SomeProject" project goes here.
   */
}

Then, any application modules created as part of the implementation of this specific project can use the SomeProjectCustomAppModuleImpl as their base class instead of the CustomAppModuleImpl.

25.1.6.3 Setting up Project-Level Preferences for Framework Extension Classes

If you decide to use a specific set of framework extension classes as a standard for a given project, you can open the Business Components > Base Classes page in the Project Properties dialog, as shown in Figure 25-5, to define your preferred base classes for each component type. For example, to indicate that any new application modules created in the project should use the CustomAppModuleImpl class by default, enter the fully-qualified name of that class in the Application Module Object class name field as shown. Setting these preferences for base classes does not affect any existing components in the project, but the component wizards will use the preferences for any new components created.

Figure 25-5 Setting Project-Level Preferences for ADF Component Base Classes

Image of Business Components Base Classes dialog

25.1.6.4 Setting Up Framework Extension Class Preferences at the IDE Level

By choosing the Tools | Preferences main menu item in JDeveloper, you can open the Business Components > Base Classes page to set framework base classes preferences at a global level. This setting does not affect any existing projects containing ADF components, but JDeveloper will use these as the default values for the project-level business components base classes preferences for any new projects created.