Get a hands-on introduction to Oracle ADF's services for personalization and customization
by John Stegeman
Published May 2010
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 (220.127.116.11). 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.
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
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.
For an Oracle ADF Faces application to allow end users to customize the application at runtime, you must follow several steps:
Figure 1 Warning in log if customization class not specified
Additionally, your application must conform to the following:
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).
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):
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.
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.
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:
Figure 3 Enabling user customizations in the ViewController project
Figure 4 Locating the adf-config.xml file
oracle.adf.share.config.UserCCas 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
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.
Figure 8 adf-mds-config section of adf-config.xml file after manual change
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:
Figure 9 Creating a new JSF page
Figure 10 Naming the JSF page
Figure 11 Creating the ADF Query Panel
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
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:
Figure 13 Invoking the ADF Security wizard
Figure 14 Selecting ADF Authentication only
Figure 15 Security infrastructure created
Figure 16 Opening the jazn-data.xml editor
Figure 17 Creating the users
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.
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
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.
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.