Customization using ADF Meta Data Services

June 2011


Oracle ADF Enterprise Application Development—Made Simple

Oracle ADF Enterprise Application Development—Made Simple

Successfully plan, develop, test and deploy enterprise applications with Oracle ADF

        Read more about this book      

(For more resources on Oracle, see here.)

Why customization?

The reason ADF has customization features built-in is because Oracle Fusion Applications need them. Oracle Fusion Applications is a suite of programs capable of handling every aspect of a large organization—personnel, finance, project management, manufacturing, logistics, and much more. Because organizations are different, Oracle has to offer a way for each customer organization to fit Oracle Fusion Applications to their requirements.

This customization functionality can also be very useful for organizations that do not use Oracle Fusion Applications. If you have two screens that work with the same data, but one of the screens must show more fields than the other, you can create one screen with all the fields and use customization to create another version of the same screen with fewer fields for other users.

For example, the destination management application might have a data entry screen showing all details of a task to a dispatcher, but only the relevant details to an airport transfer guide:

Customization using ADF Meta Data Services

Companies such as DMC Solutions that produce software for sale realize additional benefit from the customization features in ADF. DMC Solu a base application, sell it to different customers and customize each in application to that customer without changing the base application.

How does an ADF customization work?

More and more Oracle products are using something called Meta Data Services to store metadata. Metadata is data that describes other pieces of information—where it came from, what it means, or how it is intended to be used. An image captured by a digital camera might include metadata about where and when the picture was taken, which camera settings were used, and so on. In the case of an ADF application, the metadata describes how the application is intended to be used.

There are three kinds of customizations in ADF:

  • Seeded customizations:They are customizations defined in advance (before the user runs the application) by customization developers.
  • User customizations(sometimes called personalizations): They are changes to aspects of the user interface by application end users. The ADF framework offers a few user customization features, but you need additional software such as Oracle WebCenter for most user customizations. User customizations are outside the scope of this article.
  • Design time at runtime:They are advanced customization of the application by application administrators and/or properly authorized end users. This requires that application developers have prepared the possible customizations as part of application development—it is complicated to program using only ADF, but Oracle WebCenter provides advanced components that make this easier. This is outside the scope of this article.

Your customization metadata is stored in either files or a database repository. If you are only planning to use seeded customizations, a file-based repository is fine. However, if you plan to allow user customizations or design time at runtime, you should set up your production server to store customizations in a metadata database. Refer to the Fusion Middleware Administrator's Guide for information about setting up a metadata database.

Applying the customization layers

When an ADF application is customized, the ADF framework applies one or more customization layers on top of the base application. Each layer has a value, and customizations are assigned to a specific customization layer and value.

The concept of multiple layers makes it possible to apply, for example:

  • Industry customization (customizing the application for example, the travel industry: industry=travel)
  • Organization customization (customizing the application for a specific travel company: org=xyztravel)
  • Site customization (customizing the application for the Berlin office)
  • Role-based customization (customizing the application for casual, normal, and advanced users)

The XDM application that DMC Solution is building could be customized in one way for ABC Travel and in another way for XYZ Travel, and XYZ Travel might decide to further customize the application for different types of users:

Customization using ADF Meta Data Services

You can have as many layers as you need—Oracle Fusion Applications is reported to use 12 layers, but your applications are not likely to be that complex.

For each customization layer, the developer of the base application must provide a customization class that will be executed at runtime, returning a value for each customization layer. The ADF framework will then apply the customizations that the customization developer has specified for that layer/value combination. This means that the same application can look in many different ways, depending on the values returned by the customization classes and the customizations registered:

Org layer value

Role layer value




Base application, because there are no customizations defined for QRS Travel



The application customized for ABC Travel, because there are no role layer customizations for ABC Travel, the value of the role layer does not change the application



The application customized for XYZ Travel and further customized for normal users in XYZ Travel



The application customized for XYZ Travel and further customized for super users in XYZ Travel

Making an application customizable

To make an application customizable, you need to do three things:

  1. Develop a customization class for each layer of customization.
  2. Enable seeded customization in the application.
  3. Link the customization class to the application.

The customization developer, who will be developing the customizations, will additionally have to set up JDeveloper correctly so that all customization levels can be accessed. This setup is described later in the article.

Developing the customization classes

For each layer of customization, you need to develop a customization class with a specific format—technically, it has to extend the Oracle-supplied abstract class oracle.mds.cust.CustomizationClass.

A customization class has a name (returned by the getName() method) and a value (returned by the getValue() method). At runtime, the ADF framework will execute the customization classes for all layers to determine the customization value at each level. Additionally, the customization class has to return a short unique prefix to use for all customized items, and a cache hint telling ADF if this is a static or dynamic customization.

Building the classes

Your customization classes should go in your Common Code workspace. A customization class is a normal Java class, that is, it is created with File | New | General | Java Class. In the Create Java Class dialog, give your class a name (OrgLayerCC) and place it into a customization package (for example, com.dmcsol. xdm.customization). Choose to extend oracle.mds.cust.CustomizationClass and check the Implement Abstract Methods checkbox:

Customization using ADF Meta Data Services

Create a similar class called RoleLayerCC.

Implementing the methods

Because you asked the JDeveloper to implement the abstract methods, your classes already contain three methods:

  • getCacheHint()
  • getName()
  • getValue(RestrictedSession, MetadataObject)

The getCacheHint() method must return an oracle.mds.cust.CacheHint constant that tells ADF if the value of this layer is static (common for all users) or dynamic (depending on the user). The normal values here are ALL_USERS for static customizations or MULTI_USER for customizations that apply to multiple users. In the XDM application, you will use:

  • ALL_USERS for OrgLevelCC, because this customization layer will apply to all users in the organization
  • MULTI_USER for RoleLevelCC, because the role-based customization will apply to multiple users, but not necessarily to all

Refer to the chapter on customization with MDS in Fusion Developer's Guide for Oracle Application Development Framework for information on other possible values.

The getName() method simply returns the the name of the customization layer.

The getValue() method must return an array of String objects. It will normally make most sense to return just one value—the application is running for exactly one organization, you are either a normal user or a super user. For advanced scenarios, it is possible to return multiple values, in such a case multiple customizations will be applied at the same layer. Each customization that a customization developer defines will be tied to a specific layer and value—there might be a customization that happens when org has the value xyztravel.

For the OrgLayerCC class, the value is static and is defined when DMC Solutions installs the application for XYZ Travel—for example, in a property file. For the RoleLayerCC class , the value is dynamic, depending on the current user, and can be retrieved from the ADF security context. The OrgLayerCC class could look like the following:

package com.dmcsol.xdm.customization;

import ...

public class RoleLayerCC extends CustomizationClass {
public CacheHint getCacheHint() {
return CacheHint.MULTI_USER;
public String getName() {
return "role";

public String[] getValue(RestrictedSession restrictedSession,
MetadataObject metadataObject) {
String[] roleValue = new String[1];
SecurityContext sec = ADFContext.getCurrent().
if (sec.isUserInRole("superuser")) {
roleValue[0] = "superuser";
} else {
roleValue[0] = "normal";
return roleValue;

The GetCacheHint() method returns MULTI_USER because this is a dynamic customization—it will return different values for different users.

The GetName() method simply returns the name of the layer.

The GetValue() method uses to look up if the user has the super user role and returns the value superuser or normal.

Deploying the customization classes

Because you place your customization class in the Common Code project, you need to deploy the Common Code project to an ADF library and have the build/ configuration manager copy it to your common library directory.

        Read more about this book      

(For more resources on Oracle, see here.)

Enabling seeded customization

In order to be able to customize pages, you need to tell JDeveloper to prepare for customization as you add components to the page flows and pages in your ViewController project.

In this article, we will customize the UC008 subsystem. Open the XdmUC008 workspace and choose the Project Properties dialog for the View project (UC008View) in the workspace for each task flow you want to customize. Choose ADF View and then check the checkbox Enable Seeded Customizations:

Customization using ADF Meta Data Services

Linking the customization class to the application

The last step in preparing an application for customization is to define which customization levels you will use, and in which order they will be applied. This is done in the adf-config.xml file that is found under the Application Resources panel in the Application Navigator. Expand the Descriptors node and then ADF META-INF to find the adf-config.xml file:

Customization using ADF Meta Data Services

Open this file and choose the MDS Configuration sub-tab. On this tab, you can add all of your customization classes and define the order in which they are applied (the top-most class in this dialog is applied first):

Customization using ADF Meta Data Services

Your customization classes defined in the Common Code workspace are not available until you have deployed the Common Code workspace to an ADF library and have made this library available to the project where you want to perform customization.

Configuring the customization layers

When developing customizations, the customization developer must choose a layer and a value to work in—for example, developing customizations for org = xyztravel. But as the layer values are returned by code at runtime, there is no way for JDeveloper to figure out which layer values are available. That is why you need to define the available customization layers and the possible values in a CustomizationLayerValues.xml file.

When you are developing customizations, JDeveloper will read the adfconfig. xml file to determine which customization classes to use, and the CustomizationLayerValues.xml file to determine which layer values should be made available for the developer to select from. The static CustomizationLayerValues.xml file must contain all the layers defined in adf-config.xml, and should contain all the possible values your customization class can return.

Match the XML file with the customization class
The CustomizationLayerValues.xml values are used at design time, and the customization class is called at run time. If you leave out a value from the XML file, you will not be able to define customizations for that value. If you add a value to the XML file that will never be returned by the customization class, you might accidentally define a customization that will never be applied at run time.

To edit the CustomizationLayerValues.xml file, click on the Configure Design Time Customization Layer Values link at the bottom of the MDS Configuration tab in the adf-config.xml file. The first time you edit the file, you get a warning about overriding the global CustomizationLayerValues.xml file. Simply acknowledge this warning and continue to your file.

You are presented with an example file containing some customization layer values and descriptive comments. For the XDM application using two customization layers of org and role, change the file to look like the following:

<cust-layers xmlns="">
<cust-layer name="org" id-prefix="o" value-set-size="small">
<cust-layer-value value="abctravel" display-name="ABC Travel"
<cust-layer-value value="xyztravel" display-name="XYZ Travel"
<cust-layer name="role" id-prefix="r" value-set-size="small">
<cust-layer-value value="normal" display-name="Normal user"
<cust-layer-value value="superuser" display-name="Superuser"

The name attribute of the cust-layer element must match the values returned from the getName() methods in your customization class. Similarly, the value attribute of the cust-layer-value element must match the values returned by the getValue() method in the corresponding customization class.

The id-prefix values for both layer and layer value are used to ensure that each component is given a globally unique name. All components in an ADF Faces application are given a component ID—for example, an inputText element might get an ID such as it3 in the base application. With customization, however, that same element might exists in many different variations—customized in one way for one organization and in another way for another organization. To ensure that ADF can tell all of these components apart, it adds prefixes for all layers to the ID of the component as specified in this file, for example:

  • The input component in the base application would be it3
  • The same component customized in the org layer for the value abctravel would be oait3 (the o from the org ID-prefix and the a from the abctravel ID-prefix)
  • The same component customized in the org layer for the value xyztravel and in the role layer for the value superuser would be oxrsit3 (o from org layer, x from xyztravel value, r from role layer, s from superuser value)

The display-name is shown to the customization developer to help select the right layer, and the value-set-size parameter should normally be set to small (this causes JDeveloper to show a drop-down box for selecting layer value).

Setting up JDeveloper for customization

To perform the actual customization of an application, you need to set up JDeveloper to understand the available customization layers and classes, and you need to run JDeveloper in the special Customization Developer role.

Making the customization class available to JDeveloper

First, the customization class must be placed so that JDeveloper can always find it (technically, the customization class has to be on JDeveloper's classpath) . This is necessary because while you are developing, your application is not necessarily running. This means that there might not be an instance of the customization class available for JDeveloper to call.

To make your customization class available to JDeveloper at all times, you need to copy the JAR file containing it to a directory that is on the JDeveloper classpath. For the XDM project, copy the adflibCommonCode.jar file from C:\JDeveloper\ XdmLib to the …\jdeveloper\jdev\lib\patches directory.

Selecting the customization role

The first time you started JDeveloper, you were greeted with a role selection dialog. You have probably deselected it by now, but you can re-enable it by choosing Tools | Preferences | Roles and check the checkbox Always prompt for role selection on startup:

Customization using ADF Meta Data Services

The next time you start JDeveloper, you will be prompted for role selection again.

Performing the customization

With your application prepared for customization and JDeveloper set up correctly, you are ready to perform the actual customization. Because you cannot change developer role while JDeveloper is running, you need to exit JDeveloper and start it again. You will be prompted to select a role—choose Customization Developer:

Customization using ADF Meta Data Services

When JDeveloper is running in customization mode, you will notice the new Customization Context panel shown at the bottom of the screen, next to the usual Log window:

Customization using ADF Meta Data Services

The values shown in this window come from the CustomizationLayerValues.xml file you created—the values in the Name column corresponds to the cust-layer elements and the values in the Value column correspond to the cust-layer-value elements.

When developing customizations, you are always working on a specific layer, called the tip layer . You select the tip layer with the radio buttons in the Tip layer column in the Customization Context panel as shown previously. In the preceding illustration, the org layer is selected as the tip layer and the Value is XYZ Travel. This means that the customizations you make will be registered to the customization context org/xyztravel.

You see that the role layer value is grayed out when org is the tip layer. Because the org layer is below the role layer, it does not matter what the value of role is when you are customizing for the organization. When you select role as tip layer, the Value column becomes active:

Customization using ADF Meta Data Services

Any customizations that you register with the preceding settings will be registered in the role layer in the customization context org/xyztravel, role/normal.

If you want to see the base application, select View without Customizations.

Customizing business components

You can customize some aspects of business components—for example, it is possible to add or change validation rules on entity objects. This can be useful for example if XYZ Travel wants to change a validation rule in the base application, but ABC Travel is happy with the base application functionality.

In this case, you select org as the tip layer and select XYZ Travel as Value, and change the validation rule as XYZ Travel requires. The base application remains unchanged, but JDeveloper has now stored a customization in the context org/ xyztravel. When XYZ Travel is running the application, the GetValue() method in the OrgLayerCC class will return xyztravel, the customization is applied and the modified business rule applies. When ABC Travel is running the application, the GetValue() method will return abctravel, and the unmodified validation rule from the base application is applied.

You can also customize UI hints (for example, default labels) by assigning new resource strings to them as described in a later section in this article.

Customizing the pages

You can customize your pages and page fragments in many ways:

  • You can add new fields, buttons, and layout components
  • You can remove fields
  • You can reorder existing items—reorder fields, move fields to other layout components, and so on
  • You can assign new resource strings to components

In order to make a change, you have to work in the Design view and the Property Palette. You can change to the Source view of your page, but the source is read-only when running JDeveloper in the Customization Developer mode.

As a simple example, imagine that ABC Travel does not require the Flight No. column and want the StartWhere column before the Text column. Additionally, normal users should not be shown the Comment column.

To perform this customization, first choose org as the Tip layer and ABC Travel as the Value. Then open the taskOverviewEdit.jsff page fragment and delete the FlightNo column and move the StartWhere column. Then you choose role as the Tip layer, leave ABC Travel selected as Value for org and select Normal user as Value for role. The JDeveloper will show a message that it has to close customizable files. Click on OK, re-open the taskOverviewEdit.jsff page fragment and delete the Comment column.

While you were performing this customization, JDeveloper was storing your customizations as XML files with the same name as the base object. After the preceding customization, your application navigator will now show a couple of new files:

Customization using ADF Meta Data Services

The taskOverviewEditPage.jsff.xml file shown under mdssys/cust/org/abctravel contains the customizations that you defined for ABC Travel, and file under mdssys/ cust/role/normal contains the the customizations that you defined for normal users. These files record the changes you have made in a compact XML format, as follows:

<mds:customization version=""
<mds:replace node="c8"/>
<mds:move node="c4" after="c2"/>

If you want to see your unmodified base application, you can select View without Customizations in the Customization Context panel.

Customizing strings

When customizing an application, you will find that the attributes defining the text displayed to the users are grayed out—you cannot change the Text property of a button or the Label property of a field. What you can do, however, is to assign new resource strings to items.

Instead of just setting the Text property for a button to a literal value like Cancel, you can click on the little down triangle to the right of the property field and choose Select Text Resource to bring up the Select Text Resource dialog:


Customization using ADF Meta Data Services

Alternatively, you can invoke the Select Text Resource dialog by right-clicking on a field and choosing Select Text Resource for | Label:

Customization using ADF Meta Data Services

In this dialog, you can write a new text in the Display Value field or select an existing UI string from the Matching Text Resources box.

If you add a new string while in Customization Developer mode, JDveloper will ask you to confirm that you want to add a new key to the override bundle. Your base application already has a resource bundle, but the changes you make while customizing is stored in a separate resource bundle that the JDeveloper automatically creates.

Your customizations are stored just like other customizations. If you are customizing for ABC Travel and change the Search button Text attribute on the the taskOverviewEditPage.jsff page fragment, the taskOverviewEditPage.jsff.xml file under mdssys/cust/org/abctravel will be updated to include something like the following:

<mds:modify element="cb1">
<mds:attribute name="text" value="#{uc008viewBundle.FIND}"/>

The actual override bundle containing your custom strings and their keys is not displayed in the JDeveloper. You can find it in the file system in the subdirectory resourcebundles\xliffBundles under the root directory of your application. For example, the override bundle for XdmUC008 might be found in C:\JDeveloper\ mywork\XdmUC008\resourcebundles\xliffBundles\XdmUC008OverrideBundle. xlf.

This file is a normal XLIFF file like you might be using in your base application. If you only defined one new string Find, it would look like the following:

<?xml version="1.0" encoding="windows-1252" ?>
<xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
<file source-language="en" original="this" datatype="x-oracle-adf">
<trans-unit id="FIND">
<note>Button to execute search</note>

What cannot be customized?

The ADF customization works by registering changes to the XML files in other XML files.

This means that you cannot customize Java code—you have to develop all your Java code in the base application. But as you can customize the attributes, it is possible to customize your application to select among different methods from the base application. For example, a button has an ActionListener property that can point to a method binding. If you have implemented two different methods in the base application and have created action bindings for them, you can use customization to choose one or the other.

You also cannot customize certain configuration files, resource bundles or securityrelated files. When you are running JDeveloper in the Customization Developer mode, the Application Navigator will show all of these with a small padlock icon in the top-left corner of the item icon. In the following example, you can see that the faces-config.xml, trinidad-config.xml , and web.xml files cannot be customized:

Customization using ADF Meta Data Services


The ADF customization features are just what an independent software vendor such as DMC Solutions need. The development team can build one base application, and implementation teams can customize the application for different customers in a controlled manner without affecting the base application. You have seen how to prepare an application for customization and how to perform customization. You have also seen that your customizations are stored separately from the application so they can be re-used even if you provide a new version of the base application. Even if your enterprise application is not intended to be implemented for different customers, you can still use customization features to offer different versions of screens to different users.

Further resources on this subject:

You've been reading an excerpt of:

Oracle ADF Enterprise Application Development - Made Simple

Explore Title