Series: Oracle ADF Development Essentials - Part 10

Building Customizable Applications Using Oracle Metadata Services (III)

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

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 (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 11.1.1.2. 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.

Deployment Concepts

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.

Creating a Database-Based Metadata Services Repository

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:

1. Run the RCU by running either rcu.bat (Microsoft Windows) or rcu (Linux) in the BIN subdirectory of the rcuHome you unzipped.
2. Acknowledge the welcome page and click Next:
   
   
   

   Figure 1 RCU welcome page

3. Ensure the Create option is selected and click Next:
   
   
   

   Figure 2 Selecting Create

4. Provide the appropriate information for your Oracle database that will contain the MDS repository and click Next:
   
   
   

   Figure 3 RCU database connection details

5. The RCU will connect to your database and ensure that the requirements are met for the repository; if any of the requirements are not met, correct the issue and start again from step 1. In my case, the first time I ran the RCU, my database did not have the recommended character set; I created a new database with the proper character set to hold my repository and started again:
   
   
   

   Figure 4 RCU successful prerequisite checks

6. Provide a prefix for the deployment (I left the default DEV). Expand the AS Common Schemas node and select Metadata Services. Finally, click Next:
   
   
   

   Figure 5 RCU selecting the MDS repository

7. After the prerequisite checks complete, click OK. On the following page, provide and confirm a password for the MDS schema and click Next:
   
   
   

   Figure 6 RCU providing a password for the MDS schema

8. Accept the suggested default and temporary tablespaces, or modify them by either changing the selected tablespace in the list or by clicking the Manage Tablespaces button to change the details. In my case, I changed the default temporary tablespace to TEMP. Click Next when done:
   
   
   

   Figure 7 RCU map tablespaces

9. If prompted, click OK to confirm tablespace creation. Again, if prompted, click OK to close the tablespace creation dialog box. Finally, review the summary page and click Create to create the repository:
   
   
   

   Figure 8 RCU summary page

10. Review the completion summary page (and review the logs if necessary). Click Close to close the RCU:
    
    
    

    Figure 9 RCU completion summary

Registering Your Repository with the Oracle WebLogic Domain

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:

1. Ensure that the domain you are using has been extended with the OEM 11g Fusion Middleware Control. You can do this with the Configuration Wizard and ensuring that Oracle Enterprise Manager is selected in the list of products supported (note that configuring OEM will also automatically configure Oracle Java Required Files [JRF], which is required for deploying Oracle ADF 11g applications):
   
   
   

   Figure 10 Configuration Wizard

2. Use a Web browser to navigate to the OEM console; the URL will be http://<your server>:<your port>/em, the default port being 7001. Log in to the Fusion Middleware Control using an appropriate username and password (the one which you specified when creating the domain as the admin user should be fine).
3. Expand the Weblogic Domain folder on the left side and locate the domain for which you will register the repository. Right-click the domain and choose Metadata Repositories from the context menu:
   
   
4. 

5. Figure 11 Navigating to the Metadata Repositories page

6. Click the Register button in the Database-Based Repositories section to begin the registration process.
7. Complete the Database Connection Information section and click the Query button. For the username and password, you can use either the owner of the MDS repository you created in the previous section or a user with SYSDBA privilege. Select the Metadata Repository in the list and provide a descriptive name and the schema password for the selected repository, and then click OK:
   
   
   

   Figure 12 Registering the repository

8. The newly registered repository should now be displayed in the list of Database-Based Metadata Repositories:
   
   
   

   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:

1. On a computer with Oracle JDeveloper 11g installed, open a command prompt/shell and change to the <jdeveloper home>/oracle_common/common/bin directory.
2. Invoke the WLST by either running “wlst” (Microsoft Windows) or “wlst.sh” (UNIX/Linux-based platforms).
3. Connect to the Oracle WebLogic Server by executing the connect() command and providing the requested information:
   
   
   

   Figure 14 Connecting to Oracle WebLogic Server using the WLST

4. Execute the registerMetadataDBRepository() command, passing the seven required arguments, in order:
   
   
   • Descriptive name for the MDS repository registration
   • Database vendor (ORACLE or MSSQL)
   • Host name for the database server hosting the MDS repository
   • Port used by the database
   • Service name of the database
   • The database username that owns the MDS repository
   • The password for the database user
   
   
   

   Figure 15 Registering the MDS repository using the WLST

Deploying the Sample Application

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:

• Using Oracle Enterprise Manager 11g Fusion Middleware Control
• Deploying directly from Oracle JDeveloper 11g
• Using the WLST to record the MDS repository configuration in your application’s EAR file, and then deploying the resulting EAR file with the WLST

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

• Create JDBC datasources on Oracle WebLogic Server and configure your Oracle ADF application modules to use those datasources
• Configure the deployment options in Oracle JDeveloper 11g for your application to include/not include the weblogic-jdbc.xml file as appropriate by checking or unchecking  Auto Generate and Synchronize  weblogic-jdbc.xml  Descriptors During Deployment
• Deploy secured applications to Oracle WebLogic Server (for my testing, I used the Djps.app.credential.overwrite.allowed=true option to allow the users I configured in Oracle JDeveloper 11g to overwrite the security configuration on the server)
• Configure an Oracle WebLogic Server appropriately so that you can deploy Oracle ADF applications
• Perform basic deployment tasks using your selected option; this article will focus on the differences when deploying customizable applications

Deploying Using Oracle JDeveloper 11g

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:

1. Create and test a connection to the target Oracle WebLogic Server in the IDE Connections (mine is called local_wls):
   
   
   

   Figure 16 Local IDE connection to Oracle WebLogic Server

2. Start the application deployment wizard by using the Deploy option in the application menu:
   
   
   

   Figure 17 Starting the Oracle JDeveloper 11g deployment wizard

3. Select Deploy to Application Server in the wizard and click Next:
   
   
   

   Figure 18 Deploy to Application Server option

4. Select the desired application server and options and click Finish:
   
   
   

   Figure 19 Selecting the application server and options

5. The deployment wizard will (after a short time) prompt you for the MDS repository information. Select the appropriate repository from the list (from among the repositories registered on the server) and provide a partition name (or select an existing partition). For this example, I used testing_partition as my partition name:
   
   
   

   Figure 20 MDS repository configuration

You can now proceed to test your application.

Deploying Using Oracle Enterprise Manager 11g Fusion Middleware Control

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:

1. Create an EAR file for your application using Oracle JDeveloper 11g’s deployment wizard (refer to steps 2 and 3 in the previous section, but select Deploy to EAR in step 3):
   
   
   

   Figure 21 Deploying to an EAR file

2. Initiate the application deployment using your preferred procedure (I like to right-click the WebLogic Domain and choose Deploy from the Application Deployment context menu):
   
   
   

   Figure 22 Initiating deployment from OEM 11g Fusion Middleware Control

3. Use the appropriate option to locate the EAR file and click Next:
   
   
   

   Figure 23 Selecting the EAR file

4. Select the appropriate target(s) and click Next.
5. Review and provide the Application Name and Context Root. In the Target Metadata Repository section, click the Edit icon to select an MDS metadata repository and provide a partition name. Finally, click Next:
   
   
   

   Figure 24 Configuring the application attributes

6. Review (and change, if desired) the deployment settings and click Deploy. If you plan to use this approach to deploy the application on a regular basis, you might want to save the deployment plan to reduce the amount of work you have to do next time:
   
   
   

   Figure 25 Deployment settings

You can now proceed to test your application.

Deploying Using WebLogic Scripting Tool

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:

1. Create an EAR file for your application deployment (see step 1 in the previous section).
2. On a computer with Oracle JDeveloper 11g installed, open a command prompt/shell and change to the <jdeveloper home>/oracle_common/common/bin directory.
3. Invoke the WLST by either running “wlst” (Microsoft Windows) or “wlst.sh” (UNIX/Linux-based platforms).
4. Use the getMDSArchiveConfig command to assign a variable (called “archive” in this example) to the MDS configuration for the EAR file you generated. getMDSArchiveConfig takes a single parameter, fromLocation, that points to the EAR file. Use a single forward slash (“/”) on both Windows and UNIX/Linux platforms as the path separator in the fromLocation argument:
   
   
   

   Figure 26 getMDSArchiveConfig() wlst command

5. Use the setAppMetadataRepository command to set the MDS information (MDS repository name, MDS repository partition name, repository type, and Java Naming and Directory Interface location of the connection) as in the example here:
   
   
   

   Figure 27 setAppMetadataRepository() wlst command

6. Use the save command to save the MDS information:
   
   
   

   Figure 28 save() wlst command

7. Use the connect command to connect to the Oracle WebLogic Server to which you will deploy the application:
   
   
   

   Figure 29 Connecting to Oracle WebLogic Server

8. Use the deploy command to deploy the application. The minimum arguments required are appName and path. If you like, you can assign a progress variable to track the deployment progress using printStatus():
   
   
   

   Figure 30 Deploying the application and checking the status of the deployment

Testing the Deployed Application

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.)

Managing the MDS Metadata Repository Data

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:

• Import and export metadata from the repository. This could be useful for such activities as copying customization information from one environment to another (such as from production to test), migrating from one server to another, and saving an external backup of an application’s metadata.
• Marking a version of the metadata with a label and restoring labelled versions as to the current version. This could be useful to save and restore different versions of metadata. You can also purge old versions of the metadata from the repository without affecting the current version.
• Deploying a new Metadata Archive. This could be useful to deploy new or updated seeded customizations for the application without redeploying the entire application.
• Other administrative activities.

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:

1. From the OEM console, right-click the WebLogic Domain and choose System MBean Browser from the context menu:
   
   
   

   Figure 31 Starting the MBean Browser

2. Expand the oracle.mds.lcm folder, which is in the Application Defined MBeans section. Then, consecutively expand the Server: <your server name>, Application: <your application name, I used MDS>, and MDSAppRuntime folders and click the MDSAppRuntime management bean (MBean):
   
   
   

   Figure 32 Selecting the MDSAppRuntime MBean

3. In the right pane, click the Operations tab to review the operations available for the MDSAppRuntime MBean. Click the listMetadataLabels operation to display the parameters for the operation (there are none for listMetadataLabels):
   
   
   

   Figure 33 The listMetadataLabels operation

4. Execute the operation by clicking Invoke. OEM will display (in the Return Value section) a list of labels for the application metadata. In my case, because I deployed the application three times (to demonstrate each of the three methods), I had three labels. When you are finished, click Return to return to the list of operations:
   
   
   

   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:

1. On a computer with Oracle JDeveloper 11g installed, open a command prompt/shell and change to the <jdeveloper home>/oracle_common/common/bin directory.
2. Invoke the WLST by either running “wlst” (Windows) or “wlst.sh” (UNIX/Linux-based platforms).
3. Use the connect() command as demonstrated earlier in this article to connect to the Oracle WebLogic Server.
4. Use the promoteMetadataLabel() wlst command, passing it the name of the application, name of the server, and name of the label to promote.
   
   
   

   Figure 36 Promoting a label using WLST

5. If you now test the application, you should notice that any customizations have been reverted to their state as of the original label. For information on the other commands available with the WLST, you can review the WLST command reference (see the “Resources” section).

Conclusion

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.

Back to TOC

 

Resources

• 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.