You may find it helpful to understand other Oracle ADF features before you start working with the ADF Business Components framework. Following are links to other functionality that may be of interest.

• For details about creating a reusable library to make your framework extension layer classes easier to package, see Reusing Application Components .

• For details about using the customization features provided by Oracle Metadata Services (MDS) to create applications that can be customized and subsequently deployed by a customer, see Customizing Applications with MDS .

• For a quick reference to the most common code that you will typically write, use, and override in your custom classes, see Most Commonly Used ADF Business Components Methods.

• For API documentation related to the oracle.jbo package, see the following Javadoc reference document:

  • Java API Reference for Oracle ADF Model

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 Fusion web applications, create a separate model project to contain the framework extension classes.

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

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

3. In the Applications window, right-click the project in which you want to create the extension class and choose New and then Java Class.
4. In the Create Java Class dialog, specify the appropriate framework base class from the oracle.jbo.server package in the Extends field.

   Figure 17-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 17-1 Creating a Framework Extension Class for an Application Module

   

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 business components on your own framework extension classes.

To make your framework extension layer classes easier to package as a reusable library, create them in a separate project from the projects that use them.

A common set of customized framework base classes in a package name of your own choosing like com.yourcompany.fwkext, each importing the oracle.jbo.server.* package, would consist of the following classes:

• public class CustomEntityImpl extends EntityImpl

• public class CustomEntityDefImpl extends EntityDefImpl

• public class CustomViewObjectImpl extends ViewObjectImpl

• public class CustomViewRowImpl extends ViewRowImpl

• public class CustomApplicationModuleImpl extends ApplicationModuleImpl

• public class CustomDBTransactionImpl extends DBTransactionImpl2

• public class CustomDatabaseTransactionFactoryImpl extends DatabaseTransactionFactory

For details about using the custom DBTransactionImpl2 and DatabaseTransactionFactory classes, see Configuring an Application Module to Use a Custom Database Transaction Class.

For completeness, you may also want to create customized framework classes for the following classes as well, note however that overriding anything in these classes would be a fairly rare requirement.

• public class CustomViewDefImpl extends ViewDefImpl

• public class CustomEntityCache extends EntityCache

• public class CustomApplicationModuleDefImpl extends ApplicationModuleDefImpl

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

1. In the Applications window, double-click the desired component.
2. In the overview editor, click the Java navigation tab and then click the Edit Java options button.
3. In the Select Java Options dialog, click Classes Extends.
4. In the Override Base Classes dialog, enter the fully qualified name of the framework base classes you wish to override. You can also use the Browse button to use the JDeveloper Class Browser to find the classes quickly.

   When you use the Class Browser 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 17-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.

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

   

1. In the Applications window, right-click the project that will contain the extension classes and choose Project Properties.
2. In the Project Properties dialog, expand ADF Business Components > Base Classes and enter the fully qualified name of the base class in the Application Module Object class name field.

   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 componentName Object class name field as shown in Figure 17-3.

   Figure 17-3 Setting Project-Level Preferences for Business Component Base Classes

   
   Description of "Figure 17-3 Setting Project-Level Preferences for Business Component Base Classes"

1. In the main menu, choose Tools and then Preferences.
2. In the Preferences dialog, expand ADF Business Components > Base Classes in the tree.
3. On the Business Components page, enter the fully qualified name of that class in componentName Object class name field.

   The page displays the same options for specifying the preferred base classes for each component type as shown in How to Define Framework Extension Classes for All New Components.

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

If you have a business component with a custom Java class and later decide to base the component on an ADF Business Components framework extension class, use the Class Extends button in the Select Java Options dialog to change the component's base class. You can open the dialog from the Java page of the component's overview editor. Doing this updates the component's XML document to reflect the new base class, and also modifies the extends clause in the component's custom Java class.

1. In the main menu, choose Tools and then Manage Libraries.
2. In the Manage Libraries dialog, select the Libraries tab and then select User and click New.
3. In the Create Library dialog that appears, name the library "Framework Extension Layer" and select the Class Path node and click Add Entry.
4. Use the Select Path Entry dialog to select the JAR file that contains the class files for the framework extension components, then click Select.
5. Select the Source Path node and click Add Entry.
6. Use the Select Path Entry dialog that appears to select the directory where the source files for the framework extension classes reside, then click Select.

   For example, select ..\FrameworkExtensions\src for the JAR file FrameworkExtensions.jar.

7. Click OK.

When finished, you will see your new "Framework Extension Layer" user-defined library, as shown in Figure 17-6. You can then add this library to the library list of any project where you will be building business services, and your custom framework extension classes will be available to reference as the preferred component base classes.

Figure 17-6 New User-Defined Library for Your Framework Extensions Layer

Description of "Figure 17-6 New User-Defined Library for Your Framework Extensions Layer"

Figure 17-7 illustrates the three primary interfaces ADF Business Components provides for accessing runtime metadata about view objects and entity objects. The ViewObject interface extends the StructureDef interface. The class representing the entity definition (EntityDefImpl) also implements this interface. As its name implies, the StructureDef defines the structure and the component and provides access to a collection of AttributeDef objects that offer runtime metadata about each attribute in the view object row or entity row. Using an AttributeDef, you can access its companion AttributeHints object to reference hints like the display label, format mask, tooltip, etc.

Figure 17-7 Runtime Metadata Available for View Objects and Entity Objects

In ViewObject Interface Methods for Working with the View Object's Default RowSet you learned that for read-only view objects the findByKey() method and the setCurrentRowWithKey builtin operation only work if you override the create() method on the view object to call setManageRowsByKey(true). This can be a tedious detail to remember if you create a lot of read-only view objects, so it is a great candidate for automating in a framework extension class for view objects.

Assume a FrameworkExtensions project contains a SummitViewObjectImpl class that is the base class for all view objects in the application. This framework extension class for view objects extends the base ViewObjectImpl class and overrides the create() method as shown in the following example to automate this task. After calling the super.create() to perform the default framework functionality when a view object instance is created at runtime, the code tests whether the view object is a read-only view object with at least one attribute marked as a key attribute. If this is the case, it invokes setManageRowsByKey(true).

The isReadOnlyNonEntitySQLViewWithAtLeastOneKeyAttribute() helper method determines whether the view object is read-only by testing the combination of the following conditions:

• isFullSql() is true

  This method returns true if the view object's SQL query is completely specified by the developer, as opposed to having the select list derived automatically based on the participating entity usages.

• getEntityDefs() is null

  This method returns an array of EntityDefImpl objects representing the view object's entity usages. If it returns null, then the view object has no entity usages.

It goes on to determine whether the view object has any key attributes by looping over the AttributeDef array returned by the getAttributeDefs() method. If the isPrimaryKey() method returns true for any attribute definition in the list, then you know the view object has a key.

public class SummitViewObjectImpl extends ViewObjectImpl {
  protected void create() {
    super.create();
    if (isReadOnlyNonEntitySQLViewWithAtLeastOneKeyAttribute()) {
      setManageRowsByKey(true);
    }
  }
  boolean isReadOnlyNonEntitySQLViewWithAtLeastOneKeyAttribute() {
    if (getViewDef().isFullSql() && getEntityDefs() == null) {
      for (AttributeDef attrDef : getAttributeDefs()) {
        if (attrDef.isPrimaryKey()) {
          return true;
        }
      }
    }
    return false;
  }
  // etc.
}

In addition to providing information about an attribute's name, Java type, SQL type, and many other useful pieces of information, the AttributeDef interface contains the getAttributeKind() method that you can use to determine the kind of attribute it represents. This method returns a byte value corresponding to one of the public constants in the AttributeDef interface listed in Table 17-1.

You may find it handy to programmatically set custom property values at runtime. While the setProperty() API to perform this function is by design not available to clients on the ViewObject, ApplicationModule, or AttributeDef interfaces in the oracle.jbo package, code that you write inside custom Java classes of your business components can use it.

1. Creates a JDBC PreparedStatement for the statement passed in, wrapping it in a PL/SQL begin...end block.
2. Loops over values for the bind variables passed in, if any.
3. Sets the value of each bind variable in the statement.

   Notice that since JDBC bind variable API's use one-based numbering, the code adds one to the zero-based for loop index variable to account for this.

4. Executes the statement.
5. Closes the statement.

protected void callStoredProcedure(String stmt, Object[] bindVars) {
  PreparedStatement st = null;
  try {
    // 1. Create a JDBC PreparedStatement for 
    st = getDBTransaction().createPreparedStatement("begin "+stmt+";end;",0);
    if (bindVars != null) {
      // 2. Loop over values for the bind variables passed in, if any
      for (int z = 0; z < bindVars.length; z++) {
        // 3. Set the value of each bind variable in the statement
        st.setObject(z + 1, bindVars[z]);
      }
    }
    // 4. Execute the statement
    st.executeUpdate();
  }
  catch (SQLException e) {
    throw new JboException(e);
  }
  finally {
    if (st != null) {
      try {
        // 5. Close the statement
        st.close();
      }
      catch (SQLException e) {}
    }
  }
}

// In StoredProcTestModuleImpl.java
public void callProcWithThreeArgs(Number n, Date d, String v) {
  callStoredProcedure("callStoredProcedure.proc_with_three_args(?,?,?)",
                      new Object[]{n,d,v});
}

1. Creates a JDBC CallableStatement for the statement passed in, wrapping it in a PL/SQL begin...end block.
2. Registers the first bind variable for the function return value.
3. Loops over values for the bind variables passed in, if any.
4. Sets the value of each user-supplied bind variable in the statement.

   Notice that since JDBC bind variable API's use one-based numbering, and since the function return value is already the first bind variable in the statement, the code adds two to the zero-based for loop index variable to account for these.

5. Executes the statement.
6. Returns the value of the first bind variable.
7. Closes the statement.

// Some constants
public static int NUMBER = Types.NUMERIC;
public static int DATE = Types.DATE;
public static int VARCHAR2 = Types.VARCHAR;

protected Object callStoredFunction(int sqlReturnType, String stmt,
                                    Object[] bindVars) {
  CallableStatement st = null;
  try {
    // 1. Create a JDBC CallabledStatement  
    st = getDBTransaction().createCallableStatement(
           "begin ? := "+stmt+";end;",0);
    // 2. Register the first bind variable for the return value
    st.registerOutParameter(1, sqlReturnType);
    if (bindVars != null) {
      // 3. Loop over values for the bind variables passed in, if any
      for (int z = 0; z < bindVars.length; z++) {
        // 4. Set the value of user-supplied bind vars in the stmt
        st.setObject(z + 2, bindVars[z]);
      }
    }
    // 5. Set the value of user-supplied bind vars in the stmt
    st.executeUpdate();
    // 6. Return the value of the first bind variable
    return st.getObject(1);
  }
  catch (SQLException e) {
    throw new JboException(e);
  }
  finally {
    if (st != null) {
      try {
        // 7. Close the statement
        st.close();
      }
      catch (SQLException e) {}
    }
  }
}

// In InvokingStoredProcAppModuleImpl.java
public String callFuncWithThreeArgs(Number n, Date d, String v) {
  return (String)callStoredFunction(VARCHAR2,
                            "invokestoredprocpkg.func_with_three_args(?,?,?)",
                            new Object[]{n,d,v});
}

1. Defines a PL/SQL block for the statement to invoke.
2. Creates the CallableStatement for the PL/SQL block.
3. Registers the positions and types of the OUT parameters.
4. Sets the bind values of the IN parameters.
5. Executes the statement.
6. Creates a JavaBean to hold the multiple return values

   The DateAndStringBean class contains bean properties named dateVal and stringVal.

7. Sets the value of its dateVal property using the first OUT param.
8. Sets value of its stringVal property using second OUT param.
9. Returns the result.
10. Closes the JDBC CallableStatement.

public DateAndStringBean callProcWithOutArgs(Number n, String v) {
  CallableStatement st = null;
  try  {
    // 1. Define the PL/SQL block for the statement to invoke
    String stmt = "begin invokestoredprocpkg.proc_with_out_args(?,?,?); end;";
    // 2. Create the CallableStatement for the PL/SQL block
    st = getDBTransaction().createCallableStatement(stmt,0);
    // 3. Register the positions and types of the OUT parameters
    st.registerOutParameter(2,Types.DATE);
    st.registerOutParameter(3,Types.VARCHAR);
    // 4. Set the bind values of the IN parameters
    st.setObject(1,n);
    st.setObject(3,v);
    // 5. Execute the statement
    st.executeUpdate();
    // 6. Create a bean to hold the multiple return values
    DateAndStringBean result = new DateAndStringBean();
    // 7. Set value of dateValue property using first OUT param
    result.setDateVal(new Date(st.getDate(2)));
    // 8. Set value of stringValue property using 2nd OUT param
    result.setStringVal(st.getString(3));
    // 9. Return the result
    return result;
  } catch (SQLException e)  {
    throw new JboException(e);
  } finally  {
    if (st != null) {
      try {
        // 10. Close the JDBC CallableStatement
        st.close();
      }
      catch (SQLException e) {}
    }    
  }
}   

package oracle.summit.model.invokingstoredprocedure;

import java.io.Serializable;
import oracle.jbo.domain.Date;

public class DateAndStringBean implements Serializable {
  Date dateVal;
  String stringVal;
  public void setDateVal(Date dateVal) {this.dateVal=dateVal;}
  public Date getDateVal() {return dateVal;}
  public void setStringVal(String stringVal) {this.stringVal=stringVal;}
  public String getStringVal() {return stringVal;}
}

JBO-27014: Attribute OrderFilled in SOrd is required

public class CSMessageBundle extends CheckedListResourceBundle {
  // etc.
  public static final String EXC_VAL_ATTR_MANDATORY = "27014";
  // etc. 
  private static final Object[][] sMessageStrings = {
    // etc.
    {EXC_VAL_ATTR_MANDATORY, "Attribute {2} in {1} is required"},
    // etc.
  }
}

1. In the Applications window, right-click the project that you want to add the message bundle file to and choose Project Properties.
2. In the Project Properties dialog, select Business Components > Options and click New.
3. In the Create MessageBundle Class dialog, enter a name and package for the custom message bundle and click OK.

   Note:

   If the fully qualified name of your custom message bundle file does not appear in the Custom Message Bundles to use in this Project list, click the Remove button, then click the Add button to add the new message bundle file created. When the custom message bundle file is correctly registered, its fully qualified class name should appear in the list, as shown in Figure 17-8.

   Figure 17-8 Project Properties Displays Message Resource Bundles

   
4. In the Project Properties dialog, click OK to dismiss the Project Properties dialog and open the new custom message bundle class in the source editor.
5. Edit the two-dimensional String array in the custom message bundle class to contain any customized messages you'd like to use.

   The followig sample llustrates a custom message bundle class that overrides the error message string for the JBO-27014 error to inform the user that a value must be provided for the named attribute. A second custom error message displays when a database constraint with the name ORD_ORDER_FILLED_CK is violated to inform the user of the expected Order Filled value. For more details about customizing error messages for constraints, see How to Customize Error Messages for Database Constraint Violations.

   package oracle.summit.model.custommessages;
   
   import java.util.ListResourceBundle;
   
   public class CustomMessageBundle extends ListResourceBundle {
     private static final Object[][] sMessageStrings 
       = new String[][] {
          {"27014","You must provide a value for {2}"},
          {"S_ORD_ORDER_FILLED_CK", "The order filled value must be Y or N"}
        };
   
   
     /* Return String Identifiers and corresponding Messages in a 
      * two-dimensional array.
      */
     protected Object[][] getContents() {
       return sMessageStrings;
     }
   }

After adding this message to your custom message bundle file, if you test the application using the Oracle ADF Model Tester and try to blank out the value of a mandatory attribute, you'll now see your custom error message instead of the default one:

JBO-27014: You must provide a value for Order Filled

You can add as many messages to the message bundle as you want. Any message whose error code key matches one of the built-in error message codes will be used at runtime instead of the default one in the oracle.jbo.CSMessageBundle message bundle.

1. Create an error handler class that extends the default error handler DCErrorHandlerImpl interface provided by the ADF Model data binding layer.
2. In the error handler class, override the default error handler behavior for the DCErrorHandlerImpl::skipException(Exception ex) method, as shown in the following example.

   This overridden method is necessary to display each item in a nested exception, such as the ones returned for database-level error messages. You must implement logic to check for specifics exception types and, based on the business scenario, determine whether to display it in the list.

3. You can then register the custom error handler in your project's DataBindings.cpx file, as described in Customizing Error Handling.

package view;

import java.sql.SQLIntegrityConstraintViolationException;

import oracle.adf.model.BindingContext;
import oracle.adf.model.RegionBinding;
import oracle.adf.model.binding.DCBindingContainer;
import oracle.adf.model.binding.DCErrorHandlerImpl;

import oracle.adf.model.binding.DCErrorMessage;

import oracle.jbo.DMLConstraintException;
import oracle.jbo.JboException;

public class CustomErrorHandler extends DCErrorHandlerImpl {

    public CustomErrorHandler() {
        super();
    }


    /**
     * If an exception is a RowValException or a TxnValException
     * and they have nested exceptions, then do not display
     * it.
     */
    @Override
    protected boolean skipException(Exception ex) {

        if (ex instanceof DMLConstraintException) {
            return false;
        } else if (ex instanceof SQLIntegrityConstraintViolationException) {
            return true;
        }
        return super.skipException(ex);
    }
)

If the default facility for assigning a custom message to a database constraint violation does not meet your needs, you can implement your own custom constraint error handling routine. Doing this requires creating a custom framework extension class for the ADF Business Components transaction class, which you then configure your application module to use at runtime.

After you define an extended component, JDeveloper lets you change the parent component from which an extended component inherits. You can use the overview editor for the component to accomplish this.

To change the parent component after creation:

1. In the Applications window, double-click the component.

2. In the overview editor, click the General navigation tab and then click the Refactor object extends button next to the Extends field.

3. In the Select Parent dialog, choose the desired component to extend from the package list and click OK.

To change the extended component to not inherit from any parent, select the None checkbox in the Select Parent dialog. This has the same effect as if you deleted the component and re-created to accomplish this.

Business components that you create in an ADF Business Component data model project are comprised of an XML document and an optional Java class. When you create a component that extends another, JDeveloper reflects this component inheritance in both the XML document and in any generated Java code for the extended component.

1. In the Applications window, right-click the project that you want to add the extended component to and choose Project Properties.
2. In the Project Properties dialog, select ADF Business Components > Substitutions and select the base application's component in the Available list.
3. In the Substitute list, select the customized, extended component to substitute .
4. Click Add.

   For example, assume that you have created the view object CustomizedProduct in a package that extends the base view object Products. To substitute the CustomizedProducts view object for the legacy Products view object, you would select these view objects as shown in Figure 17-10 to define the component substitution.

   Figure 17-10 Defining Business Component Substitutions

   
   Description of "Figure 17-10 Defining Business Component Substitutions"

When you define a list of global component substitutions in a project named ExtendedProject, the substitution list is saved in the ExtendedProject.jpx in the root directory of the source path.

The file will contain Substitute elements as shown in the following example, one for each component to be substituted.

<JboProject
   Name="ExtendedProject"
   SeparateXMLFiles="true"
   PackageName="oracle.summit.model.extended" >
   <Containee
      Name="custompackage"
      FullName="oracle.summit.model.custompackage"
      ObjectType="JboPackage" >
   </Containee>
   <Containee
      Name="extended"
      FullName="oracle.summit.model.extended"
      ObjectType="JboPackage" >
   </Containee>
   <AppContainee
      Name="Model"
      FullName="oracle.summit.model.Model"
      ObjectType="JboProject">
   <Substitutes>
      <Substitute
        OldName="oracle.summit.model.extended.ProductEx"
        NewName="oracle.summit.model.custompackage.CustomProduct" />
   </Substitutes>
</JboProject>

To have the original application use the set of substituted components, define the Java system property Factory-Substitution-List and set its value to the name of the project whose *.jpx file contains the substitution list. The value should be just the project name without any *.jpr or *.jpx extension.

For example, consider a simple example that customizes the Product entity object and the ProductView view object described in Parent Classes and Interfaces for Extended Components. To perform the customization, assume you create new project named ExtendedProject that:

• Defines a library for the JAR file containing the base components

• Imports the package containing Product and ProductView

• Creates new extended components in a distinct package name called CustomizeProduct and CustomizeProductView

• Defines a component substitution list to use the extended components.

When creating the extended components, assume that you:

• Added an extra view attribute named SomeExtraAttribute to the ProductViewEx view object.

• Added a new validation rule to the CustomizedProduct entity object to enforce that the product name cannot be the letter "Q".

• Overrode the getChecksum() method in the CustomizedProduct.java class to return "I am the CustomizedProduct Class".

If you define the Factory-Substitution-List Java system property set to the value ExtendsAndSubstitutes, then when you run the exact same test client class described in Parent Classes and Interfaces for Extended Components the output of the sample will change to reflect the use of the substituted components.