Series: Oracle ADF Development Essentials - Part 8

Building Customizable Applications Using Oracle Metadata Services

Get a hands-on introduction to Oracle ADF's services for personalization and customization

by John Stegeman

Published May 2010

Downloads:

• Oracle JDeveloper Studio Edition
• Sample app (HR Schema install required)
• Oracle Database XE (if needed)

Today’s application users expect that their regularly used applications will remember how they like to work, and therefore not require them to set up the application anew each time they log in. Users want their common searches and screen layouts, for example, to remain from day to day, making their use of the application easier and more intuitive. Oracle Metadata Services provides a foundation that can be leveraged by Oracle Application Development Framework (ADF) applications to provide such persistent personalization. This article shows you how to configure your Oracle ADF application to allow end user customizations.

Desktop application users are accustomed to being able to set and save their personal application preferences. For example, Oracle JDeveloper 11g users can rearrange the application windows and set other preferences, and expect that when they exit Oracle JDeveloper 11g and return the following day, their preferred layout and other options will be as they left them. Saving personal preferences in this way allows users to customize applications to their desired way of working and thus increase their productivity. Now that many applications are delivered via a Web browser, more and more users will come to expect similar customizability for Web-based applications. Building such customizability into a new application can require a lot of development time; developers need to build a framework for storing personalizations in a datastore, capturing and saving user changes to such a datastore and applying the personalizations at runtime for a specific user. For complex enterprise applications (such as Oracle E-Business Suite), the effort required to build such a framework might well be justified; for smaller applications, the effort is often not justified.

Fortunately for developers using Oracle ADF, Oracle has already created services for personalization and customization and integrated them with Oracle ADF; they're called Oracle Metadata Services (MDS). Oracle E-Business Suite Releases 11i and 12 used a precursor of Oracle MDS to allow users to personalize their self-service applications, and to allow application administrators to customize aspects of the application for specific groups of users. In Oracle JDeveloper 11g, these capabilities are available for developers to leverage in providing the same capabilities to Oracle ADF Web applications.

This article was written using Oracle JDeveloper 11g (11.1.1.2). If you use the provided sample application, you will need to change the connection information for the HR connection defined in the Application Resources panel in the Application Navigator. Also note that to run the sample application, you should follow along with any required configuration steps detailed in the article.

Metadata Services Concepts

Oracle MDS stores customization and personalization information in a repository. The repository can either be stored in a database or in a file-based store; for reasons of scalability and reliability, as well other reasons, I strongly recommend using a database for storing the MDS repository (the next article in this series will show you how to configure the repository). For the develop/test/debug cycle, the Oracle WebLogic Server integrated with Oracle JDeveloper 11g provides a local MDS repository, so you do not need to set up a separate one for development purposes.

The MDS repository can store data about various types of customization and other metadata, including

• Specific properties of Oracle ADF Faces components that have been changed by the user at runtime (for example, the ordering of columns in a table)
• Users’ saved searches (created using the af:query component)
• Customized settings developed at design time for various Oracle ADF content, including Oracle ADF Faces, Oracle ADF Business Components, and Oracle ADF Controller (page flows)
• Customizations to resource bundles
• Metadata for other Oracle products, such as Oracle B2B
• Metadata for Oracle WebCenter applications

This article will show you how to configure an Oracle ADF application to allow end user runtime customization and how to run and test the customizable application in the development environment. The next article in the series will show you how to create design time customizations and how to configure a database-based MDS repository.

Requirements for End User Customization

For an Oracle ADF Faces application to allow end users to customize the application at runtime, you must follow several steps:

• Configure the Oracle JDeveloper 11g project to allow end user customizations.
• Configure a default customization class. The Oracle JDeveloper 11g documentation is not clear that this step needs to be performed; but in practice, I found that the changes did not persist if this step was omitted, and I also observed errors like this in the log:
  
  
  

  Figure 1 Warning in log if customization class not specified

• Configure the Oracle ADF application descriptor with the Oracle ADF Faces components that should enable customization.
• For saving user queries in the af:query component, configure a metadata namespace (as documented in the Oracle JDeveloper 11g release notes – if you are using Oracle JDeveloper 11g Version 11.1.1.3, this is not required).
• For deployment, you must create and register an Oracle MDS repository (this step is covered in a subsequent article).

Additionally, your application must conform to the following:

• Your Oracle ADF Faces pages must be stored in XML format (.jspx), and the user-customizable components in the page must each have an ID specified. These requirements are due to the way in which Oracle MDS records customizations made by the user.
• Your application must have security enabled. This requirement is so that Oracle MDS has an identity against which to store user customizations.

In practice, it is easiest if you perform all of the required steps when you first create your Oracle ADF application, because Oracle JDeveloper 11g will configure some settings for you (such as automatically creating your Oracle ADF Faces pages in XML format).

Step 1: Creating a Sample Application Model Layer

To demonstrate how to configure and test end user customizations, I’ll be using a simple application. In order to develop and run the sample application, you’ll need access to an Oracle Database with the HR sample schema installed. (You can download Oracle Database Express Edition (XE), a free version of the Oracle Database, here. ) First, you’ll create the application and create some default Oracle ADF Business Components. Then, before you create any Oracle ADF Faces pages, you’ll configure the application to support customization. Finally, you’ll create and test some customizable pages. You can either follow the summary steps below to create the application, or you can download the sample app. If you’d like to create the application on your own, follow these steps (I assume you have had some basic Oracle JDeveloper 11g experience, and as such, I will show you the abbreviated steps):

1. Create a new Fusion Web Application (ADF) by selecting New from Oracle JDeveloper 11g’s
   File menu and selecting the appropriate option in the New Gallery:
   
   
   

   Figure 2 Creating a new Fusion Web Application

   Specify a name for the application and accept all of the defaults to complete the application creation.

2. Right-click the Model project, select New, and invoke the Business Components from Tables wizard. Create a database connection to the HR sample schema and create the following Oracle ADF Business Components:
   1. An entity object for the EMPLOYEES table
   2. An updatable view object based upon the EMPLOYEES entity object
   3. No read-only view objects (just click Next in that step of the wizard)
   4. A default application module (you can click Finish once you reach this step of the wizard)

If you like, you can test the Oracle ADF Business Components you’ve created by right-clicking the application module and choosing Run. You should be able to double-click the EmployeesView1 view object instance and scroll through the employees in the database.

Step 2: Configuring the Application to Support User Customization

As mentioned previously in this article, ideally you should configure your application to support end user customization before you start to create any Oracle ADF Faces pages. To configure the application, follow these steps:

1. Double-click the ViewController project in the Application Navigator to display the project properties. Select the ADF View node and enable user customizations across sessions using MDS by selecting the appropriate options and clicking OK:
   
   
   

   Figure 3 Enabling user customizations in the ViewController project

2. Using the Application Navigator, expand the Application Resources section, and double-click the adf-config.xml file (it will be in the ADF META-INF subfolder of the Descriptors folder):
   
   
   

   Figure 4 Locating the adf-config.xml file

3. For the runtime changes to persist properly, at least one customization class must be registered. Click the Add icon to add a customization class. In the Edit Customization Class dialog box, specify oracle.adf.share.config.UserCC as the name of the customization class (this is a default customization class provided by Oracle ADF; you will not be using the capability of the UserCC customization class, but a customization class must be specified for personalization to work) and click OK:
   
   
   

   Figure 5 Specifying the customization class

4. Specify which of the Oracle ADF Faces 11g components should allow end user customization. You do this by selecting the View section of the adf-config.xml editor and using the Add button  to add the specific components. For our sample application, we’ll allow the user to customize the columns’ order/size/etc. in a table (by enabling customization of the column component) and allowing the user to customize whether specific panel boxes are disclosed (by enabling customization of the panelBox component):
   
   
   

   Figure 6 Adding panelBox to the list of customizable components

   When you have finished adding both the column and panelBox components to the list of customizable tags, the editor should look like this:

   
   

   Figure 7 adf-config.xml editor showing column and panelBox as customizable tags

   If you like, you can also add other components and specify which specific properties of the components will be persisted. The list of Oracle ADF Faces components and their properties that can be persisted by default can be found in the documentation.

5. As documented in the Oracle JDeveloper 11g release notes , you must make a manual configuration change to the adf-config.xml file to enable persistence of users’ saved queries (for the af:query component); this is not required if you are using Oracle JDeveloper 11g Version 11.1.1.3. To make the change, click the Source tab of the adf-config.xml editor to display the XML source for the file. Locate the cust-config element and paste the code from the release notes (I also like to add an XML comment so that I remember why the code was added). When you have completed this step, the adf-mds-config element of your adf-config.xml file should look something like this:
   
   
   

   Figure 8 adf-mds-config section of adf-config.xml file after manual change

Step 3: Creating the Sample Application View Layer

For the view layer of the sample application, you can create any Oracle ADF Faces page you like. For my sample, I chose to create two pages: one with an af:query component on it, so I could test saving users’ queries, and one with an af:table component and some af:panelBoxes, so I could test reordering the table columns and disclosing/undisclosing the panel boxes. The key points to remember to do (as previously mentioned) are to ensure that your JavaServer Faces (JSF) pages are saved in XML format (.jspx) and that the components that you want the users to customize have their ID property set. Both of these items should be done for you automatically if you have followed the configuration steps up to this point. Let’s walk through the steps for creating the query page:

1. Right-click the ViewController project and invoke the New wizard to create a new JSF page.
   
   
   

   Figure 9 Creating a new JSF page

2. Provide a name for the new page and ensure the Create as XML Document (*.jspx) option is selected before clicking OK:
   
   
   

   Figure 10 Naming the JSF page

3. Expand the Data Controls section of the Application Navigator. Expand the EmployeesView1 view object instance and locate the All Queriable Attributes item inside the Named Criteria folder. Drag the All Queriable Attributes item to the JSF page and drop it as an ADF Query Panel with Table:
   
   
   

   Figure 11 Creating the ADF Query Panel

4. Leave the default options selected in the Edit Table Columns dialog box and click OK.

You can follow a similar procedure to create another sample page with af:table and af:panelBox components (as well as any other components you’d like to test). I created a page and placed a panel group layout from the component palette on the page; I then added some panel boxes inside the panel group layout and put some output text components inside the panel boxes. Finally, I dragged the EmployeesView1 view object instance from the data control palette and dropped it on my page as an ADF table. My resulting page looked like this:

Figure 12 Second sample Oracle ADF Faces page

Step 4: Enabling Oracle Application Development Framework Security for the Application

Finally, before you can test persistence of end user customizations, you need to enable security for your application so that MDS can identify the user making the customizations; at a minimum, your application needs to have authentication configured. The  ADF Code Corner section of OTN has a number of tutorials on setting up ADF security (see “ADF Code Corner Internet TV”) . However, for the purpose of demonstration, we will do just a very simple security setup for our sample application. Fortunately, Oracle JDeveloper 11g includes security wizards that make this simple setup quite easy. To configure security in the sample application, follow these steps:

1. Invoke the ADF Security wizard from the application menu  of the Application Navigator:
   
   
   

   Figure 13 Invoking the ADF Security wizard

2. For our simple testing, select ADF Authentication and click Next:
   
   
   

   Figure 14 Selecting ADF Authentication only

3. At this point, you can simply click Finish to complete the wizard, or if you like, you can click through each step separately to see the options available to you.
4. When you finish the wizard, Oracle JDeveloper 11g will display a message telling you that the security infrastructure has been created and providing a link for some more information:
   
   
   

   Figure 15 Security infrastructure created

5. To test the application with security enabled, you should create a few users using Oracle JDeveloper 11g’s jazn-data.xml editor. You can access the editor from the Application Navigator menu like this:
   
   
   

   Figure 16 Opening the jazn-data.xml editor

6. Now, you can use the Add button  to add users to the configuration. For my testing, I added users named “john” and “josephine,” each with passwords of “weblogic1.” Because our test application only has authentication (and not authorization), you do not need to assign any roles to the users:
   
   
   

   Figure 17 Creating the users

Step 5: Testing Metadata Services in the Integrated Oracle WebLogic Server

You are now ready to test persistence of end user customizations and saved queries using the Oracle WebLogic Server that is integrated in Oracle JDeveloper 11g. You do not need to set up and register an MDS repository, because the integrated Oracle WebLogic Server uses a local MDS repository for testing. You can configure this simulated repository to either preserve or delete end user customization information across runs of the application (by default, the end user customizations will be preserved). You can configure this setting by selecting Application Properties from the Application Navigator menu:

Figure 18 Configuring application properties

The MDS repository configuration information is in the MDS section under the Run node:

Figure 19 MDS repository configuration information

Let’s start by testing the SampleControls page (with the panel boxes and table). Based on the configuration we’ve done to this point, we should expect that any changes the user makes to the disclosed/undisclosed state of the panel boxes or the column ordering in the table should be preserved, even when the user logs out and logs back in to the application. To test this, let’s run the sample page by right-clicking it and selecting Run. Once the application starts, you should be prompted to log in to the application; first let’s try logging in as john. Because you have not run the application before as john the page displays with the default settings (all panel boxes are disclosed and the columns in the table are in the default order):

Figure 20 SampleControls page with default settings

Make some changes to the page, such as closing the second panel box, shrinking the EmployeeId column, and dragging the LastName column to be the first column in the table:

Figure 21 SampleControls page after some user customization

Once you are satisfied with your customizations, log out of the application by closing the browser (be sure to close any open instances of your browser so that the credentials are not cached). Run the application again by clicking the Target URL in the Oracle JDeveloper 11g Log window:

Figure 22 Finding the Target URL in the Log window

This time, log on to the application as josephine. You should see the page with all the panel boxes disclosed and the columns at their default size and position, because John’s changes are for him and him alone. You can repeat this process (close the browser and run the application again), logging on as John to verify that his changes were persisted.

Testing the Query Page

You can follow the same process to test persistence of users’ saved queries by running the QueryTest.jspx page (right-click it and Run). Let’s try creating and saving a query that looks for all employees whose last name is “Smith.” You can do this by typing Smith into the LastName section of the query panel and clicking the Search button to verify that the search works:

Figure 23 Creating the Smith search

Next, let’s save the search by clicking the Save button and providing a name for the query:

Figure 24 Saving the Smith search

You can now verify that the search was saved by closing the browser window and logging back in as either john or josephine to ensure that the search was saved for the desired person. The appropriate user should see the saved search in the Saved Search list:

Figure 25 Viewing the saved searches

Conclusion

You now know how to enable and configure end-user customization persistence for Oracle ADF Faces applications and how to test such applications in the integrated Oracle WebLogic Server. The next article in this series will show you how to implement seeded customizations to design a different application experience for different groups of users.

Go to Part 10 | Back to TOC

More Good Stuff

• Application customization using MDS documentation (see chapters 34 and 35)

John Stegeman ( stegemanoracle.wordpress.com) is an Oracle ACE Director (Oracle Fusion Middleware) and an architect for Xchanging, a global business process outsourcing and IT services firm. He has been working with Oracle products since 1990 and with Oracle JDeveloper since version 3.