Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers
10g Release 3 (10.1.3.0) B25947-01 |
|
Previous |
Next |
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:
What framework extension classes are
How to create an extension class and base ADF components you create on it
How to adopt the best practice of using a whole custom layer of framework extension classes for your component or specific project
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.
To create a framework extension class, follow these steps:
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.
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.
Create the new class using the Create Java Class dialog.
This dialog is available in the New Gallery in the General category.
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.
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 typeApplicationModuleImpl 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.
|
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.
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).
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 theoracle.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.
|
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.
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.
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.
{para}?>
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.
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
.
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.
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.