A hands-on introduction to Oracle ADF's services for personalization and customization (continued) - in this installment, installing and configuring a repository for persistent storage of customizations.
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 (MDS) 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 build Oracle ADF applications that can be customized at design time and how to install and configure an MDS repository for persistently storing both design time and runtime customizations.
In earlier articles in this series, you learned how to enable runtime end user customization of your Oracle ADF Faces applications and how to develop seeded customizations. Up to this point, you have been running and testing your applications using the Oracle WebLogic Server integrated with the Oracle JDeveloper 11g integrated development environment (IDE), which uses a simulated file-based MDS repository. This configuration is fine for testing, but how do you go about implementing this in a production environment? This article will show you how to create and configure a database-based MDS repository, how to register that MDS repository with Oracle WebLogic Server, and how to deploy and manage your customizable Oracle ADF 11g applications.
This article was written using Oracle JDeveloper 11g Version 22.214.171.124. If you use the sample application provided, 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.
To deploy a customizable application, whether the application supports end user customizations, seeded customizations, or both types, you will need to create a repository to hold the MDS information and register it with the Oracle WebLogic Server to which the application will be deployed. When you are ready to deploy the application, Oracle JDeveloper 11g will package the metadata information for the application in a special file known as a Metadata Archive, or MAR, and include the MAR file in your application’s Enterprise Archive (EAR) file for you to deploy to the server. You can also create a standalone MAR file and deploy it against an already-deployed application; you might want to do this if, for example, you want to update the seeded customization metadata for an application without redeploying the entire application.
MDS repositories can either be file based or database based; however for deployment, I (and Oracle) recommend a database-based repository for performance reasons. To create a database-based repository, you use a utility called the Repository Creation Utility (RCU), which you can get from the Oracle Fusion Middleware 11g Download Page on Oracle Technology Network. The RCU is used to create all types of repositories for Oracle Fusion Middleware 11g, but we will be using it to create just the MDS repository. If you have already used the RCU to create a repository (for example, you would have done so if you installed Oracle SOA Suite 11g), you do not need to run the RCU again, unless you want to create a separate MDS repository. To get started, download the RCU and unzip it to a location on your hard drive. After doing this, you will find a directory called “rcuHome.” You will (obviously) need a database for creating the database-based MDS repository; I will demonstrate how to use the RCU to create the MDS repository in an Oracle database (you can also use Microsoft SQL Server). To create the MDS repository, follow these steps:
Figure 1 RCU welcome page
Figure 2 Selecting Create
Figure 3 RCU database connection details
Figure 4 RCU successful prerequisite checks
Figure 5 RCU selecting the MDS repository
Figure 6 RCU providing a password for the MDS schema
Figure 7 RCU map tablespaces
Figure 8 RCU summary page
Figure 9 RCU completion summary
For the MDS repository to be available for your Oracle ADF applications, you will need to register the repository with the Oracle WebLogic Server Domain to which you deploy the applications. There are two ways of registering the MDS repository. The first is to use the Oracle Enterprise Manager 11g Fusion Middleware Control to register it using a graphical user interface. If you prefer, or if you have not installed Oracle Enterprise Manager 11g Fusion Middleware Control in your Oracle WebLogic Server Domain, you can use the WebLogic Scripting Tool (WLST) command-line utility to perform the registration. This article will demonstrate both options, starting with using the Oracle Enterprise Manager (OEM) 11g Fusion Middleware Control:
Figure 10 Configuration Wizard
Figure 11 Navigating to the Metadata Repositories page
Figure 12 Registering the repository
Figure 13 Successful registration
If you do not want to use OEM to register the MDS repository, or if you have not configured OEM in the Oracle WebLogic Server domain, you can use the WLST to register the repository. The WLST that comes with the base Oracle WebLogic Server installation is not configured with the commands needed to manage MDS repositories. Oracle documentation is not altogether clear about which Oracle product installations do have the appropriate WLST configuration; fortunately, Oracle JDeveloper 11g includes a properly configured WLST in the <jdeveloper home>/oracle_common/common/bin directory. To register the MDS repository using the WLST, follow these steps:
Figure 14 Connecting to Oracle WebLogic Server using the WLST
Figure 15 Registering the MDS repository using the WLST
If you have been following along with this series, you can use the sample application that you’ve built; you can also download a copy of the application from here. (See "Step 5" file.) Deploying a customizable Oracle ADF application that uses MDS is similar to the normal process of deploying a “normal” Oracle ADF application with one major exception: when deploying a customizable application, you must provide additional information about which MDS repository and repository partition to use. An MDS repository partition is a container for storing a logical grouping of metadata in the repository. Many of the metadata management commands (such as importing/exporting metadata) operate on MDS repository partitions.
The Oracle WebLogic Server console does not expose the MDS configuration information, and thus cannot be used to deploy customizable applications. There are three options that you can use to deploy your customizable application:
A fourth possible option would be to manually update your application’s adf-config.xml configuration file with the MDS repository information; although I have successfully tested this approach, I do not recommend this option, because I was not able to find any official documentation for the proper configuration. Which option you do choose depends on the procedures that you are most comfortable with. This article will briefly demonstrate all three options. Because the article is focused specifically on MDS, I will focus on the MDS-specific parts of the deployment, and assume that you already understand how to
The Oracle JDeveloper 11g application deployment wizard will automatically prompt you to supply the MDS information that is required, as indicated by the presence of a MAR in the application’s EAR file. To deploy the sample application to a properly configured Oracle WebLogic Server using Oracle JDeveloper 11g, follow these steps:
Figure 16 Local IDE connection to Oracle WebLogic Server
Figure 17 Starting the Oracle JDeveloper 11g deployment wizard
Figure 18 Deploy to Application Server option
Figure 19 Selecting the application server and options
Figure 20 MDS repository configuration
You can now proceed to test your application.
Like the Oracle JDeveloper 11g deployment wizard, the OEM 11g Fusion Middleware Control deployment wizard will prompt you for the MDS repository information when deploying a customizable application. To deploy the application using OEM 11g Fusion Middleware Control, follow these steps:
Figure 21 Deploying to an EAR file
Figure 22 Initiating deployment from OEM 11g Fusion Middleware Control
Figure 23 Selecting the EAR file
Figure 24 Configuring the application attributes
Figure 25 Deployment settings
You can now proceed to test your application.
Deploying customizable Oracle ADF applications using the WLST command-line tool is a two-step process. First, you must use the WLST to add the MDS repository configuration information to the application’s EAR file; then, you can use the WLST to deploy the application to the Oracle WebLogic Server. As described earlier in this series, the WLST is available with any Oracle WebLogic Server 11g installation; however, not every installation of WLST has support for the MDS-specific commands. Oracle product documentation mentions this, but does not give a definitive list of which product installs will have a WLST that can be used to configure MDS; for the purpose of this article, I will show you how to do the configuration with a WLST that I am sure works, namely, the one included with the Oracle JDeveloper 11g installation. To deploy the sample application using the WLST, follow these steps:
Figure 26 getMDSArchiveConfig() wlst command
Figure 27 setAppMetadataRepository() wlst command
Figure 28 save() wlst command
Figure 29 Connecting to Oracle WebLogic Server
Figure 30 Deploying the application and checking the status of the deployment
After deploying the application using one of the techniques, you can now test your application using the appropriate URL to ensure that the users john and josephine are both able to customize the application at runtime and that the seeded customizations display properly. (See installments 8 and 9 respectively.)
Once you have customizable applications running in production, you can use either OEM 11g Fusion Middleware Control or the WLST to manage the information stored in the MDS metadata repository. Both tools can do the following:
Rather than demonstrate each of the above activities, this article will demonstrate how to create, list, and promote labels, which are a way of saving and restoring specific point-in-time versions of the application’s metadata. You can perform the other operations in the same way; refer to the WLST command reference (see the “Resources” section) for the WLST syntax or to the OEM 11g Fusion Middleware Control application to browse the commands.
Let’s start by using OEM 11g Fusion Middleware Control (OEM, for short) to list any labels that already exist for the sample application. You might think that there would be no labels yet since you haven’t created any explicitly; however, the various deployment tools automatically create a label after each deployment. To list the labels using OEM, follow these steps:
Figure 31 Starting the MBean Browser
Figure 32 Selecting the MDSAppRuntime MBean
Figure 33 The listMetadataLabels operation
Figure 34 List of application metadata labels
You can invoke other operations using OEM in the same fashion. Let’s use OEM to create a version of the application metadata called test. We can do that by clicking the createMetadataLabel operation, providing the name test as the label, and clicking Invoke:
Figure 35 Creating the test label
If you like, you can invoke the listMetadataLabels operation again to confirm that the label was created.
Let’s now assume that the application has been running in production for a number of weeks, and our end users, john and josephine have been personalizing the application at runtime; however, for whatever reason, they both want to return the personalizations to the state it was just after the last deployment. We can do this by promoting the appropriate label. I will demonstrate the process of promoting one of my prior labels, postDeployLabel_MDS_2594457265. Because you have already seen how to use OEM for managing MDS, let’s do the promotion using the WLST. To promote the label with the WLST, follow these steps:
Figure 36 Promoting a label using WLST
You should now be able to create, deploy, and manage Oracle ADF 11g applications that allow users to customize the application to their own preference and applications that can be customized for different user communities at design time.
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.