Customization using ADF Meta Data Services

Oracle ADF Enterprise Application Development—Made Simple

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

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:

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:

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

Result

qrstravel

any

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

abctravel

any

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

xyztravel

normal

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

xyztravel

superuser

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:

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().
getSecurityContext();
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 oracle.adf.share.security.SecurityContext 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.