Series: Oracle ADF Development Essentials - Part 9

Building Customizable Applications Using Oracle Metadata Services (II)

by John Stegeman

A hands-on introduction to Oracle ADF's services for personalization and customization (continued) - in this installment, creating seeded customizations.

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 configure your application for design time customizations and how to design customizations for different user communities.

In the previous installment, you learned how to enable runtime end user customization of your Oracle ADF Faces applications. Oracle MDS supports another type of application customization, known as seeded customization, which allows application developers to design customizations to the application at development time. The seeded customizations are then applied to the application at runtime depending upon either static or dynamic criteria. Your application can support both types of customization at the same time, so you can have your application be customized at design time for different user communities, while at the same time supporting individual user customization at runtime. Usage of seeded customizations has two general use cases:

• Customization of an application for a specific installation. For example, a software vendor could create a base application that all of its customers use and enable seeded customizations so that each customer can customize an installation of the application without changing the base application. This approach has a couple of key benefits. First, the base application does not need to be changed in order for each company to customize the application. Second, because the base application doesn’t need to be changed, customizations designed in this way are more “upgrade safe”; this means that when a new version of the base application is delivered, the seeded customizations are not lost, but can be reapplied to the new version of the base application (of course, the customizations might need to be changed, but that is easier than trying to reapply customizations to the base application).
•  
• Customization of the application for different user communities. This is an approach that has been used by Oracle in its Oracle E-Business Suite; the self-service applications can be customized such that users from different departments (for example) see the application screens in a different way.

This article will show you how to develop seeded customizations using the sample application developed in the previous article in this series, which you can download here.

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.

Seeded Customization Concepts

When designing seeded customizations for your application, you will be specifying one or more customization layers. A customization layer is used to hold a set of customizations; a customization layer supports one or more customization layer values, which specify which set of customizations to apply at runtime. The layer concept is easier to understand with an example; let us take the example of an application that is designed to be used for expense reporting for an entire company. Each department within the company might have different requirements for certain fields to be displayed or not displayed, ordering of columns within tables, and so forth. In this example, the customization layer would be the department, and the customization layer values would be the various departments (human resources, finance, for instance). An application can support multiple customization layers that are applied in a specified order on top of the base application; for example, an application could have both company and department customization layers. In this article, the terms customization layer and layer are used interchangeably, as are the terms customization layer value and layer value.

A customization class is a Java class for a specific customization layer that, among other things, specifies which customization layer value applies at runtime. The customization class can use any method desired to determine which customization layer value applies at runtime; common approaches for this might include a properties file (if customizations apply for a specific installation, for example), looking up information in a database for the logged on user, or other application-specific logic. Note that although the common use case is for a specific customization layer value to apply at a specific time, a customization class can return multiple customization layer values at runtime.

Oracle JDeveloper 11g includes a special role for designing customizations for each customization layer and layer value called the Customization Developer role. When you start Oracle JDeveloper 11g in the Customization Developer role, you will see a MDS - Customization Context window that allows you to select which customization layer and layer value you want to edit; this combination of layer and layer value that you are editing is called the tip layer.

Steps for Implementing Seeded Customizations

To implement seeded customizations for your application, you will follow these steps:

• Create one or more customization classes.
• Configure the Oracle JDeveloper 11g project to enable seeded customizations.
• Configure the customization class(es) for your application.
• Optionally, edit the extended metadata properties.
• Configure Oracle JDeveloper 11g to see your customization class(es) and layers and layer values at design time.
• Edit the metadata for each tip layer.

An additional requirement (just as for end user customizations at runtime) is that all of your JavaServer Faces (JSF) pages must be stored in XML format (.jspx), and all JSF components that you will customize must have an ID value set.

Creating the Customization Class

For our sample application, we will create a very simple customization class. I’ve chosen “gender” as my customization layer and “Male” and “Female“ as my customization layer values. The sample application is already secured and has two users, john and josephine; so instead of doing any type of complicated logic in the customization class, we’ll simply use the logic that John is a male and Josephine is a female when the class determines the layer value at runtime. Of course, a real application would likely have more-complex logic such as perhaps reading configuration from a database, but we’ll keep things simple for now. In our customization class, we need to implement three methods:

• getCacheHint(). This method will return information about whether the customization for this layer applies to all users, a set of users, a specific HTTP request, or a single user.
• getName(). This method will return the name of the customization layer.
• getValue(). This method will return the customization layer value at runtime.

There are several possible strategies for developing the customization class. One strategy is to create a separate project for the customization class and package the class as a JAR file, which can then be used by other applications. If you follow this approach, it’s best to create the customization class project in a separate application to avoid class loader issues (as documented in the Oracle Fusion Middleware Fusion Developer’s Guide for Oracle Application Development Framework 11g Release 1 (11.1.1), section 34.2.1.3). Another approach that is useful in cases where you do not intend to reuse the customization class across multiple applications is to create the class in the lowest-level project (in our case, the Model project) of your Oracle ADF application. For this article, you will follow the latter approach.

To create the customization class, ensure you are starting with the "Step 4" file in the sample application and follow these steps:

1. Right-click the Model project in the Application Navigator and invoke the New... wizard:
   
   
   

   Figure 1 Invoking the New wizard

2. Select the General category, then select the Java Class in the Items list and click OK:
   
   
   

   Figure 2 Creating a new Java class

3. Provide class and package names appropriate to your application. Ensure that your class extends oracle.mds.cust.CustomizationClass. Finally, ensure that the Implement Abstract Methods checkbox is checked and click OK:
   
   
   

   Figure 3 Creating the customization class

4. Write the code for the getCacheHint() method. This customization layer is specific to the user’s gender; therefore, we can use MULTI_USER as the cache hint (because the layer values can be used for multiple users, assuming we have multiple males and females using the application). The getCacheHint() method should look like this:
   
   

   public CacheHint getCacheHint()
     {
        return CacheHint.MULTI_USER;
     }
   

5. Write the code for the getName() method. I’ve chosen “gender” as the value for the name, so the getName() method should look like this:
   
   

   public String getName()
     {
        return “gender”;
     }
   

6. Write the code for the getValue() method. As described in the overview, we will return “m” for the layer value if the logged on user is John, and “f” if the logged on user is Josephine. If the user is neither of those two, we’ll return no layer value. In a customization class, you can use the ADFContext to obtain the security context, and therefore the username. The code for getValue() should look something like this (allow Oracle JDeveloper to import oracle.adf.share.ADFContext when prompted):
   

    
   public String{} getValue(RestrictedSession restrictedSession, MetadataObject metadataObject)
     {
       String user = ADFContext.getCurrent().getSecurityContext().getUserName();
       if (“John”.equalsIgnoreCase(user))  return new String[]  {“m”};
       if  (“Josephine”.equalsIgnoreCase(user)) return new String[]  {“f”};
       return new String[0];
     }
   

That’s all there is to writing a customization class!

Configuring the Application to Support Seeded Customizations

Now that you have created the customization class, the next step is to configure your ViewController project to support seeded customizations. You can do this by following these two steps:

1. Double-click the ViewController project in the Application Navigator to display the project properties.
2. Select the ADF View node in the Project Properties dialog box and ensure the Enable Seeded Customizations checkbox is selected, and click OK. If you’ve been following along with the sample application up to this point, the Enable User Customizations checkbox will already be selected, but it is not required for seeded customizations:
   
   
   

   Figure 4 Enabling seeded customizations in the ViewController project

You also need to register the customization class for the application. To do this, expand the Application Resources section of the Application Navigator; locate and double-click the adf-config.xml file (it will be in the ADF META-INF subfolder of the Descriptors folder) to open the editor. Click the Add icon and type the fully qualified class name of the customization class:

Figure 5 Registering the customization class

You can also click the oracle.adf.share.config.UserCC customization class in the overview editor and click the Delete icon  to remove that customization class from the MDS configuration, because that class was used in a previous article as a default customization class to enable persistence of users’ runtime customizations. When you have done this, the MDS Configuration section should look like this:

Figure 6 MDS configuration

Configuring Oracle JDeveloper 11g for Your Seeded Customizations

To create the actual seeded customizations for the application, you will need to configure Oracle JDeveloper 11g so that it has access to your customization class on the classpath and is aware of the customization layers and layer values that you want to customize.

The Oracle JDeveloper 11g documentation briefly mentions creating an extension as a way of making your customization class available on Oracle JDeveloper 11g’s classpath. However, this involves a bit of work and would require us to learn how to create an extension-creating an extension is not difficult, but would distract from the main thread of this article. Let us take a simpler approach by creating a JAR file containing our customization class and putting it in Oracle JDeveloper 11g’s classpath. To create the JAR file, follow these steps:

1. Ensure the customization class has been generated by right-clicking the Model project in the Application Navigator and choosing Rebuild Model.jpr from the context menu.
2. Double-click the Model project in the Application Navigator to display the project properties.
3. Select the Deployment node to display the available deployment profiles.
4. Click New to create a new deployment profile. Ensure that the archive type JAR File is selected, and provide a meaningful name. Then, click OK:
   
   
   

   Figure 7 Creating a new deployment profile

5. To be able to customize the application at design time, the customization class will need to be available on the Oracle JDeveloper 11g classpath; a simple way to do this is to put the JAR file containing the customization class in the jdev/lib/patches directory of the Oracle JDeveloper 11g installation. Change the JAR File location in the dialog box to be in <JDEV_HOME>/jdeveloper/jdev/lib/patches so that the customization class will be in Oracle JDeveloper’s classpath when you restart:
   
   
   

   Figure 8 Changing the JAR file location

6. In the Edit JAR Deployment Profile Properties dialog box that appears, we will configure the deployment profile to only include our customization class. Select the Filters node. Unselect everything except for the GenderCustomizationClass.class node to ensure that the other items are not included in the JAR file (the Merged Contents of this File Group’s Contributors and model checkboxes will be shown in a partially selected state because one or more, but not all, of their children are selected):
   
   
   

   Figure 9 Filtering the project output

You can now create the JAR file by right-clicking the Model project in the Application Navigator and choosing GenderCC (the name of the deployment profile you just created) from the Deploy menu:

Figure 10 Deploying the JAR file

In the Deploy customization_class_jar dialog box that appears, click Finish to complete the deployment. You can now view the Deployment - Log window in Oracle JDeveloper 11g to ensure that the deployment was successful:

Figure 11 Deployment Log

Before you can use Oracle JDeveloper 11g to edit the seeded customizations for your application, you need to tell Oracle JDeveloper about the customization layer and layer values to display in the design environment. You do this by editing the CustomizationLayerValues.xml file, which is located in the jdeveloper/jdev directory of your Oracle JDeveloper 11g installation. You can edit this file using a text editor of your choice; I will show you how to edit it using Oracle JDeveloper 11g. First, click the Model project in the Application Navigator; then choose Open from Oracle JDeveloper 11g’s File menu. Finally, find and open the CustomizationLayerValues.xml file in the aforementioned location:

Figure 12 Opening the CustomizationLayerValues.xml file

The CustomizationLayerValues.xml file has an extensive comments section at the beginning that describes how to edit the file. For our application, we simply need to add a single cust-layer tag for our “gender” customization layer and two cust-layer-value tags for our “Male” and “Female” layer values. You should note that if you use seeded customizations extensively, with multiple customization layers, you must ensure that the id-prefixes in the tags will generate unique IDs across all of your tip layers. In our case, we are using a single customization layer, so we do not have to worry about uniqueness. To add the tags for our customization layer to the file, place the following text anywhere inside the <cust-layers> tag of the CustomizationLayerValues.xml file:

 
<cust-layer  name=”gender” id-prefix=”g”>
   <cust-layer-value value=”m”  display-name=”Male” id-prefix=”1”/>
      <cust-layer-value value=”f”  display-name=”Female” id-prefix=”2”/>

</cust-layer>

Note that the name of  the cust-layer tag corresponds with  the return value for our getName() method in the customization class, and the  value of each of the cust-layer-value  tags corresponds with a possible return value for the getValue() method in our  customization class. Save all of your changes by clicking the Save All icon  in the toolbar.

Using the Customization Developer Role to Edit the Seeded Customizations

As previously mentioned, Oracle JDeveloper 11g includes a specific role that is used for editing seeded customizations called the Customization Developer role. To edit the customizations for your sample application, you will need to switch to that role. You can switch to this role by using Oracle JDeveloper 11g’s Preferences dialog box; open the Preferences dialog box now by choosing Preferences from the Tools menu. Next, click Roles in the list of preferences on the left side. You can switch to the Customization Developer role by selecting it in the list; if you will be changing roles often, it is useful to check the Always prompt for role selection on startup checkbox so that Oracle JDeveloper 11g will ask you what role to use each time you start:

Figure 13 Selecting the Customization Developer role

Click OK and allow Oracle JDeveloper 11g to restart using the Customization Developer role. If you requested, you will also be prompted to select your role when Oracle JDeveloper 11g restarts; if this is the case, be sure that the Customization Developer role is selected:

Figure 14 Selecting a role on startup

Once Oracle JDeveloper 11g has restarted, ensure that the sample application is selected in the Application Navigator and have a look around the integrated development environment you will notice a few changes from the Default role. The first change you might notice is that files (such as Java classes) that are not customizable are now read only. The Customization Developer role can only be used for editing seeded customizations, so anything that is not related to seeded customizations will be disabled. The second major difference you might notice is the MDS - Customization Context window that is displayed:

Figure 15 MDS - Customization Context window

This window is used for selecting the tip layer that you will be editing. For our sample application, let’s do a simple seeded customization to the SampleControls.jspx JSF page in the ViewController project; this page has three panel boxes with a table underneath:

Figure 16 SampleControls.jspx JSF page

You can change nearly any of the visual makeup of the page via seeded customizations; for this sample, let us make the following changes:

• Male users will see the panel boxes with dark backgrounds and in reverse order.
• Female users will see the panel boxes with light backgrounds.

To edit the seeded customizations for the male tip layer, follow these steps:

1. Ensure the male tip layer is selected in the MDS - Customization Context window:
   
   
   

   Figure 17 Selecting the male tip layer

2. Double-click the SampleControls.jspx file in the Application Navigator to open it for editing.
3. Use the SampleControls.jspx - Structure window to rearrange the panel boxes in reverse order by dragging and dropping them. When you’re done with this step, the SampleControls.jspx - Structure window will look something like this:
4. 
   

   Figure 18 The rearranged panel boxes

5. Select the panel box labeled Number 3 in the SampleControls.jspx - Structure window. Use the property inspector to change the Background property to Dark:
   
   
   

   Figure 19 Changing the background property

   Repeat this process for the other two panel boxes. When you have finished, the page should look something like this:

   
   

   Figure 20 All panel boxes using a dark background

6. Save your changes and close the SampleControls.jspx page. Change the tip layer to be the female layer and double-click the SampleControls.jspx page in the Application Navigator to open it. You should notice that the changes you made to the male tip layer are not reflected. Select the panel box labeled Panel Box Number 1 in the SampleControls.jspx - Structure window and use the Property Inspector to change the Background property to light. Repeat this process for each of the other panel boxes and save your changes. When you are finished, the page should look something like this:
   
   
   

   Figure 21 All panel boxes using a light background

If you now have a look in the Application Navigator, you will see that Oracle JDeveloper 11g has created two new files in the ViewController project to reflect the customizations for the male and female customization layer values:

Figure 22 MDS file for seeded customizations

These new files will be stored in the Oracle MDS repository, and are retrieved and used at runtime to apply the appropriate seeded customizations by modifying the base JSF page. This ensures that the user sees the page as the Customization Developer intended. If you would like to download a copy of the sample application with all of the changes described to this point, you can get it here. (See Step 5.)

Testing the Seeded Customizations in the Integrated Oracle WebLogic Server

You are now ready to test the seeded customizations using the integrated Oracle WebLogic Server. You do not need to install a database-based MDS repository, because the integrated server will use a file-based local MDS repository for testing. You can test the application using the Customization Developer role as well as the Default role. As usual, just right-click the SampleControls.jspx file in the Application Navigator and choose Run to start the application:

Figure 23 Running the SampleControls page

When the application starts, the browser will prompt you for your login credentials. Our sample application has two users, john and josephine, and each of their passwords is “weblogic1” (without the quotes). You should try logging in as john to observe the dark panel boxes in reverse order, as specified for the male seeded customization layer:

Figure 24 SampleControls page with male seeded customization layer

Next, close all open browser windows and rerun the application by clicking the Target URL in the Oracle JDeveloper 11g Log window; this time, log on as josephine and observe the light panel boxes in the original order:

Figure 25 SampleControls page with female seeded customization layer

Conclusion

You now know how to enable seeded customizations for your applications, create a customization class, and design and test the seeded customizations in Oracle JDeveloper 11g. The next article in this series will show you how to create and register an MDS repository and deploy your customizable applications to an Oracle WebLogic Server.

Go to Part 10 | 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.