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
 

8.6 Overriding Built-in Framework Methods

The ApplicationModuleImpl base class provides a number of built-in methods that implement its functionality. While Appendix D, "Most Commonly Used ADF Business Components Methods" provides a quick reference to the most common code that you will typically write, use, and override in your custom application module classes, this section focuses on helping you understand the basic steps to override one of these built-in framework methods to augment the default behavior.

8.6.1 How to Override a Built-in Framework Method

To override a built-in framework method for an application module, go to the application module Java class and then choose Source | Override Methods... from the JDeveloper main menu. As shown in Figure 8-9, the Override Methods dialog appears. You can scroll the list of methods using the scrollbar, but if you know the method you want to override, begin typing the first few letters of its name to perform an incremental search to find it more quickly in the list.

Assume that you want to override the application module's prepareSession() method to augment the default functionality when a new user session begins working with an application module service component for the first time. Check the checkbox next to the prepareSession(oracle.jbo.Session) method, and click OK.


Note:

Here you've only selected one method, but the Override Methods dialog allows you to select any number of methods to override simultaneously.

Figure 8-9 Overriding a Built-in Framework Method

Image of Override Methods dialog

8.6.2 What Happens When You Override a Built-in Framework Method

When you dismiss the Override Methods dialog, you return to the code editor with the cursor focus in the overridden method, as shown in Figure 8-10. Notice that the method appears with a single line that calls super.prepareSession(). This is the syntax in Java for invoking the default behavior the base class would have normally performed for this method. By adding code before or after this line in the custom application module class, you can augment the default behavior before or after the default functionality.

Also notice that when you override a method in a base class, the code editor's left margin displays a small "up arrow" icon. This is a clue that this method is related to an interface or a base class. Hovering the mouse over the icon as shown in the figure gives positive feedback that this method has the correct signature to override a method in the base class.

While this method was generated by the Override Methods dialog, if you begin typing overridden method names from memory, it's important to have the signature exactly the same as the base class method you want to override. If you make a spelling mistake in what you think is an overridden method, or if you have the wrong number or types of arguments or return value, then you won't get any compile errors but neither will you be overriding the base class method you anticipated. The positive feedback makes it clear you got the method name exactly right. To quickly navigate to the base class to double-check what it's doing when you call the superclass, choose Go to Overridden Method in the right-mouse context menu menu on the override icon in the margin.

Figure 8-10 Code Editor Margin Gives Visual Feedback About Overridden Methods

Image of Code Editor margin

Note:

In addition to the design time visual method override confirmation described above, you can consider adding the JDK 5.0 @Override annotation just before any method in your class whose intent it is to override its superclass. This causes the compiler to generate a compile-time error if it does not match the signature of any method in the superclass.

8.6.3 How to Override prepareSession() to Set Up an Application Module for a New User Session

Since the prepareSession() method gets invoked by the application module when it is used for the first time by a new user session, it's a nice method to override in your custom application module class to perform setup tasks that are specific to each new user that uses your application module. Example 8-13 illustrates an overridden prepareSession() method in the devguide.model.SRServiceImpl class that invokes a findLoggedInUserByEmailInStaffList() helper method to initialize the StaffList view object instance to display the row corresponding to the currently logged-in user.

The helper method does the following:

  1. Calls super.prepareSession() to perform the default processing

  2. Accesses the StaffList view object instance using the generated getStaffList() getter method

  3. Calls the getUserPrincipalName() method to get name of the currently authenticated user


    Note:

    Until you learn about enabling J2EE security in your application in Section 30.4, "Configuring the ADF Business Components Application to Use Container-Managed Security", the getUserPrincipalName() API in the sample below will return null instead of the authenticated user's name. So, the example contains the fallback code that assigns a fixed email ID of sking for testing purposes.

  4. Defines a CurrentUser named bind variable, with the currentUserName member variable as its default value

  5. Sets an additional WHERE clause to find the current user's row by email

  6. Executes the query to retrieve the StaffList row for the current user

After overriding the prepareSession() method in this way, if you test the SRService application module using the Business Components Browser, you'll see that the StaffList view object instance has the single row corresponding to Steven King (email = 'sking').

Example 8-13 Initializing the StaffList View Object Instance to Display a Current User's Information

// In devguide.model.SRServiceImpl class
protected void prepareSession(Session session) {
  // 1. Call the superclass to perform the default processing
  super.prepareSession(session);
  findLoggedInUserByEmailInStaffList();
}
private void findLoggedInUserByEmailInStaffList() {
  // 2. Access the StaffList vo instance using the generated getter method
  ViewObject staffList = getStaffList();
  // 3. Get the name of the currently authenticated user
  String currentUserName = getUserPrincipalName();
  /*
   * Until later when we learn how to integrate J2EE security,
   * this API will return null. For testing, we can default it
   * to the email of one of the staff members like "sking".
   */
  if (currentUserName == null) {
    currentUserName = "sking";
  }
 /*
  * We can't use a simple findByKey since the key for the
  * StaffList view object is the numerical userid of the staff member
  * and we want to find the user by their email address. We could build
  * an "EMAIL = :CurrentUser" where clause directly into the view object
  * at design time, but here let's illustrate doing it dynamically to
  * see this alternative.
  */
  // 4. Define named bind variable, with currentUserName as default value
 staffList.defineNamedWhereClauseParam("CurrentUser",    // bindvar name
                                        currentUserName, // default value
                                        null);
 // 5. Set an additional WHERE clause to find the current user's row by email
 staffList.setWhereClause("EMAIL = :CurrentUser");
 // 6. Execute the query to retrieve the StaffList row for the current user
 staffList.executeQuery();
 /*
  * If the view object needs to be also used during this session 
  * without the additional where clause, you would use
  * setWhereClause(null) and removeNamedWhereClauseParam("CurrentUser") to
  * leave the view object instance back in it's original state.
  */
}