Oracle JDeveloper 11g Release 2 Tutorials - Customizing and Personalizing an Application

Customizing and Personalizing an Application

You will use wizards to quickly create an application and a model project with Oracle ADF Business Components. To begin customization, you will define a customization layer with two layer values, create a customization class, and register the class in the application configuration file.

Then you will create the base application using two databound pages in a bounded task flow. To make customizations in an application, you will restart JDeveloper in the Customization Developer role and select a customization context. After making your customizations in both contexts, you will run the application twice to view the customized contents in each context.

Next you will work with user customizations and ADF Faces implicitly persisted component attributes. To persist changes permanently to a repository so that the application can be personalized, you will enable user customizations using Oracle Metadata Services (MDS) and specify the component attributes to be persisted in MDS. Then you will enable ADF Security in the application before you run and personalize the application for a specific user.

One of the pages in the customized application looks similar to this:

Browse page in browser

Purpose	Duration	Application
This tutorial shows you how to customize and personalize an application built with Oracle ADF Business Components and Oracle ADF Faces. To see the complete application you will create, click the Download button to download a zip of the final application, and then unzip it in your JDeveloper `mywork` folder.	1 hour 40 minutes

Note: If you download the complete application,

Read more... do the following before you run the application:

Follow all the instructions in Step 1: Install the Schema.
Open the application in JDeveloper. In the Application Navigator, expand the Application Resources panel. Then expand Connections > Database. Right-click FOD and choose Properties. Modify only the following properties so that they point to the database where you installed the FOD schema: Host Name, Port, SID. Then click Test Connection to confirm that you can connect. Click OK if the connection was successful.
Follow the instructions in Step 5: Define a Customization Layer, substep #1 through #3 only.
To run the application, follow the instructions in Step 13: Run and Personalize the Application.

Step 1: Install the Schema

The steps and examples in the tutorial are based on tables that are part of the Fusion Order Demo (FOD) schema. This schema is also used as the database for the sample application that ships with Oracle JDeveloper 11g, as well as other collateral in this release.

Read more...

It will be convenient to have this schema installed, and you only need to do it once. If you have already installed the FOD schema, you can skip this step and go directly to the next step. To install the schema, you will also need to have an Oracle database and access to a privileged (DBA) user which has permissions to create users. Any Oracle 10g version (or later) of the database should work for this schema. To install the schema, you will download and expand a zip file, then use Ant to perform the installation.

Download the schema.zip file from OTN.
Unzip the file to a convenient location (for example, c:\temp).
From the File menu, choose Open. Open the workspace c:\temp\Infrastructure\Infrastructure.jws.
If you are prompted to migrate the project, click Yes to confirm, then click OK.
In the Application Navigator, expand the MasterBuildScript project. Under Resources double-click build.properties to open it in the editor.

Set the appropriate values in the build.properties file (jdeveloper.home, and all the jdbc.* and db.* settings). Keep all other properties set to their default values. The demo user must be named FOD.

The relevant settings are:

Setting	Description
jdeveloper.home	The `/jdeveloper` directory where you have JDeveloper installed, for example, `c:/JDeveloper_11/jdeveloper/`
jdbc.urlBase	Base URL for your database, for example, `jdbc:oracle:thin:@localhost`
jdbc.port	Port number for your database, for example, `1521`
jdbc.sid	Database System Identifier, for example, `XE` or `ORCL`
db.adminUser	Database user with admin privileges, for example, `system`
db.demoUser.tablespace	Tablespace name where the FOD user will be installed, for example, `USERS`

In the MasterBuildScript project, select the build.xml file.
In the Structure window, right-click the refreshSchema target and choose Run Target "refreshSchema".
When prompted, enter the password for the database user with admin privileges.

After running the Ant task, you should see a build successful message in the JDeveloper Log window.

If there are errors, you should verify that your database is running (try connecting through SQL*Plus), and that the values you provided in the build.properties file are correct. Also, make sure that the DBA user you specified has the CREATE USER privilege.

Step 2: Create a New Application and Projects

From the main menu, choose File > New. In the New Gallery, expand the General category and select Applications. Then in the Items list, select Fusion Web Application (ADF) and click OK.

The JDeveloper application is the highest level in the organizational structure. While you are developing your application, it stores information about the objects you are working with.

Read more... At the same time, it keeps track of your projects and all environment settings.

Based on prebuilt templates, a JDeveloper application allows you to specify a predefined type of environment, depending on the type of application you want to create (web application, Java application, and so on). Application templates provide you with a quick way to create the project structure for standard applications with the appropriate combination of features already specified. The application template also filters the work you do in JDeveloper such that the choices available are focused only on the features you are working with.

In this tutorial, you will use the Fusion Web Application template that is configured for building a databound ADF web application. Once you have created an application using a suitable template, you can still add new projects to the application and specify what features are to be included. To do this, in the Application Navigator, right-click the application name and choose New Project. In the New Gallery, you can select any type of project in the Items list.

To follow along with the example, enter CustomizeApp as the application name, and oracle as the application package prefix.

The application template you select determines the initial project structure, that is, the named project folders within the application workspace, and the application libraries that will be added.

Read more... The project or projects in the application define the associated features.

A JDeveloper project, which is used to logically group files that are related, keeps track of the source files, packages, classes, images, and other elements that your program may need. Projects manage environment variables such as the source and output paths used for compiling and running your program. Projects also maintain compiler, runtime, and debugging options so that you can customize the behavior of those tools per project.

You can add multiple projects to your application to easily access, modify, and reuse your source code. Different projects might contain files representing different tiers of a multi-tier application, for instance, or different subsystems of a complex application. These files can reside in any directory and still be contained within a single project.

Accept the defaults and click Finish.

The Application Overview window opens by default in the editor window area when you create a new application. You can optionally close the window, since you will not be using it to create objects for this application.

All objects that you create within JDeveloper appear in the Application Overview file summary pages, arranged by object type. You can create new files and artifacts, and view them filtered by status and project.

Read more...

The Checklist steps you through the building of a Fusion Web application, according to Oracle recommended best practices. It optionally walks you through the entire process of configuring and building your application, with links to specific dialogs and wizards. Each step is also designed to teach you about the architecture, tools and resulting files using a combination of links to step-by-step instructions, relevant sections of the Developer's Guides, and descriptions of what happens in the IDE as a consequence of doing the work in a step.

The new application created from the template appears in the Application Navigator already partitioned into tiered projects, with the associated features set in each project. The Projects panel in the Application Navigator should look like this:

Projects are displayed as the top level in the hierarchy in the Application Navigator. The Fusion Web Application (ADF) template that you used for your web application partitions your application into two projects: Model and ViewController.

In the Application Navigator you can collapse and expand any panel. You adjust the size of panels by dragging the splitter between two panels. To group and sort items in the Projects panel, use the

Navigator Display Options dropdown menu. For application operations, you can click

Application Menu and choose an option from the dropdown menu.

JDeveloper has the capability of recognizing many different file types, displaying each in its appropriate viewer or editor when you double-click the file in the Application Navigator. Closing an application or project closes all open editors or viewers for files in that application or project and unloads the files from memory.

Note: Nodes in italics in the Application Navigator mean that the elements have not yet been saved. A project node is bold when a file in the project is selected.

Step 3: Create a Database Connection

You will establish a connection to the database you installed, to use the Fusion Order Demo (FOD) schema.

From the main menu, choose File > New > General > Connections > Database Connection, then click OK to open the Create Database Connection dialog.
Select Application Resources as the Create Connection In option.
Enter a name for the connection, select the connection type, and enter the username and password. To follow along with this example, use FOD for the connection name and fod for the username.
Enter the Oracle JDBC settings to point to the host, port and SID for your database. Then click Test Connection to confirm that you can connect. Click OK if the connection was successful.
In the Application Navigator, expand the Application Resources panel.
In the Application Resources panel, expand the Connections and Database nodes.

The database connection you created (for example, FOD) is included as a resource for your application under the Connections node.

Read more...

Expand the connection node you created, then click the various + icons to see the schema and database objects.

Application Resources, FOD expanded

After adding the database connection to the application resources, you can optionally contract the Application Resources panel to increase the size of the Projects panel in the Application Navigator.

Step 4: Create Oracle ADF Business Components

In the Application Navigator, right-click the Model project and choose New > Business Tier > ADF Business Components > Business Components from Table, then click OK.

The Create Business Components from Tables wizard allows you to easily create a package of business domain components (entity objects, associations, and domains) from existing database objects,

Read more... and optionally to create a default package of data model components (view objects, view links, and an application module) from these newly generated business domain components.

The particular database objects that you choose in the wizard are important. Your selections will determine how the generated business components will be related. For instance, if two tables define a one-to-many relationship through their foreign key column, the business components generated by the wizard will also describe this relationship. In the business components terminology, a one-to-many relationship is also known as a master-detail relationship.

JDeveloper also provides business component wizards that let you edit any business components you create with this wizard, and add new business components later.

The Create Business Components from Tables wizard does not create a user interface (this is governed by the "view" portion of the application), nor does it determine other application logic such as control flow. It just provides a representation of, and access to, data, and implements business logic.

Specifically, Oracle ADF Business Components handles all aspects of application plumbing automatically:

It automatically handles O/R mappings and persistence for instances of its own library classes
It allows you to make complex requests for data retrieval using SQL
It automatically handles transaction management, including optimistic or pessimistic locking
It provides a framework for implementing complex business logic
It automatically implements many Java EE design patterns
It has a powerful caching and data passivation system for increasing the performance and scalability of applications

In the Initialize Business Components Project dialog, ensure that FOD is the currently selected database connection. Then click OK.
On step 1, Entity Objects, click Query to populate the list box on the left.

If your schema has many tables, you may experience a short delay.
Select three tables, ORDERS, ORDER_ITEMS, and PRODUCTS_BASE, from the Available list and click to move them to the Selected list. Then click Next.
On step 2, Entity-based View Objects, select the business components, Orders (ORDERS) and OrderItems (ORDER_ITEMS) from the Available list and shuttle them to the Selected list. Then click Next.
On step 3, Query-based View Objects, click Next to skip the step because the objects aren't needed.
On step 4, Application Module, change the application module name to FODAppModule and click Finish.
Click Save All to save your work.

After completing the Create Business Components from Tables wizard, the Model project in the Application Navigator should look similar to this:

In the Model project, the navigator displays the business components that you created: entity objects, view objects, associations, view links, and application modules.

Read more... To display the business components sorted by type, select Sort By Type in the

Navigator Display Options menu.

Your wizard selections produced these business domain components that represent features of the data source:

Entity objects, like Orders and OrderItems, which represent objects in the data source (usually tables, views, and synonyms in a database)
Associations like OrderItemsOrdersFkAssoc, which represent relationships between these objects (such as foreign key relationships)

It produced these data model components that collect data and present it to the client model:

View objects, like OrdersView and OrderItemsView, which collect data from the data source (usually by using a SQL query)
View links, like OrderItemsOrdersFkLink, which represent relationships (such as master-detail relationships) between view object result sets
Application modules, like FODAppModule, which provide a single point of access to the view objects and view links

The Model.jpx file is the Business Components Project object, which is used for properties shared by all the business components contained in the project.

In the Application Navigator, if you expand the Data Controls panel, then expand FODAppModuleDataControl, you should see the OrdersView and OrderItemsView collections.

Application Navigator, Data Controls panel

Application Navigator, Data Controls panel

The Data Controls panel is a data binding tool that lets you add databound UI controls to user interfaces by dragging and dropping.

Step 5: Define a Customization Layer

In Oracle Application Developer Framework (ADF) applications, the Oracle Metadata Services (MDS) framework allows you to create customizable applications.

Read more...

A customizable application means you can take the application and make modifications to it to suit the needs of a particular group, such as an industry or site.

You create customization classes and layers to support the customization of metadata content, and then customize the metadata within the context of a specified layer. In this step you will create a customization layer. You will create a customization class later.

From the main menu, choose File > Open to locate and open the file CustomizationLayerValues.xml, which is found in <JDEVELOPER_HOME>/jdeveloper/jdev.

To customize an application, you must specify the customization layers and their values in the CustomizationLayerValues.xml file so that they are recognized by JDeveloper.

Read more...

When you use the CustomizationLayerValues.xml file located in <JDEVELOPER_HOME>/jdeveloper/jdev, you are configuring customization layers globally for JDeveloper. This means the layers and the layer values are available across applications at design time. You can define the customization layers either globally for JDeveloper or in an application-specific file. If you use an application-specific file, it takes precedence over the global file.

To configure application-level or workspace-level customization layers, you would open the overview editor for adf-config.xml and click the Configure Design Time Customization Layer Values link on the MDS tab to create an application-specific CustomizationLayerValues.xml file.

adf-config.xml overview editor, MDS page

adf-config.xml overview editor, MDS page

JDeveloper stores the application-specific file in an application-level directory (for example, workspace-directory\.mds\dt\customizationLayerValues\CustomizationLayerValues.xml). You would then access this application-specific file from the Application Resources panel of the Application Navigator, under the MDS DT folder.

Application Resources panel, MDS DT folder

Application Resources panel, MDS DT folder

Unlike the global CustomizationLayerValues.xml file, the application-specific CustomizationLayerValues.xml file can be modified when you switch to the Customization Developer role in JDeveloper. The Customization Developer role, which you will use later in the tutorial, is used to customize the metadata in a project. Customization features are available only in this role.

In the XML editor, modify values in the site customization layer to add two configurable layer values. You can use the sample code provided.

For example, replace both lines of code for the customization layer values site1 and site2:

<cust-layer-value value="site1" display-name="Site One" id-prefix="1"/>
<cust-layer-value value="site2" display-name="Site Two" id-prefix="2"/>

With the following lines:

<cust-layer-value value="headquarters" display-name="Headquarters" id-prefix="1"/>
<cust-layer-value value="remoteoffices" display-name="Remote Offices" id-prefix="2"/>

A customizable application can have multiple customization layers to suit the needs of particular groups, such as industries or sites.

Read more... Each customization layer can have multiple customization layer values. For example, the industry layer for a customizable application can contain values for healthcare and financial industries. Each customization layer corresponds to a customization document that contains a set of instructions that change the underlying metadata. The layered changes are stored and managed separately from the base metadata of the application in the repository.

The CustomizationLayerValues.xml file in <JDEVELOPER_HOME>/jdeveloper/jdev contains all the defined customization layer values and their display names to be used in an instance of JDeveloper. The layers and the layer values are available across applications at design time.

In the example, first you will define a site customization layer with two configurable layer values: headquarters and remoteoffices.

Before you implement customizations in an application in JDeveloper, you select a customization layer and one layer value. The customizations you make are then applied to that layer and layer value only.

When the application is run, MDS applies the different customization layers to the base definition of the application. The customization context of a customized application is defined by the set of customization layers applied to it. For example, a customized application can contain customizations in the financial layer value of the industry layer and the headquarters layer value of the site layer. The multiple customization layers are applied in the order of precedence as specified by the order of customization classes in adf-config.xml.

Click Save.
In the Application Navigator, right-click the Model project and choose New > General > File, then click OK.
In the Create File dialog, enter customization.properties as the file name. In the Directory field, append \src after Model (for example, <JDEVELOPER_HOME>\jdeveloper\mywork\CustomizeApp\Model\src). Then click OK.
In the text editor, add the layer values defined for the site customization layer. You can copy and paste the sample code provided.

#Configured values for the default layer values
#site=remoteoffices
site=headquarters

The runtime customization.properties file contains the configurable layer values defined for one or more customization layers in an application.

Read more...

For example, a properties file could contain the following configurable customization layer values defined for a site layer and an industry layer:

#Configured values for the default layer values

industry=financial

#industry=healthcare

#site=remoteoffices
 
site=headquarters

The values without the prefix # are the active layer values in that layer at runtime. When an application with customized metadata is run, the customization classes read the active values from customization.properties, and use those values to determine the customization context. The applicable customizations that belong to the active layer values only are loaded from the corresponding repository and layered over the base metadata of the application to produce the desired customized contents for viewing.

Click Save All to save your work.

The file customization.properties is created in the Application Sources folder in the Model project.

You can optionally close the files in the editor window because you won't be editing them later.

Read more...

Editor window, layer values XML and properties file

Step 6: Create a Customization Class

In the Application Navigator, right-click the Model project and choose New > General > Java Class, then click OK.

In the Create Java Class dialog, enter the following values:

Field	Value
Name	`SiteCC`
Package	`oracle.model.mycompany`
Extends	`oracle.mds.cust.CustomizationClass`

Accept the default values and click OK.
In the SiteCC.java source editor, add code to build the customization layer. You can delete the generated code, then copy and paste the sample code provided.

package oracle.model.mycompany;
import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;
import oracle.mds.core.MetadataObject;
import oracle.mds.core.RestrictedSession;
import oracle.mds.cust.CacheHint;
import oracle.mds.cust.CustomizationClass;

public class SiteCC extends CustomizationClass {
  private static final String DEFAULT_LAYER_NAME = "site";
  private String mLayerName = DEFAULT_LAYER_NAME;
  public SiteCC() {
  }
  public SiteCC(String layerName) {
    mLayerName = layerName;
  }
  public CacheHint getCacheHint() {
    return CacheHint.ALL_USERS;
  }
  public String getName() {
    return mLayerName;
  }
  public String[] getValue(RestrictedSession sess, MetadataObject mo) {
    // This needs to return the site value at runtime.
    // For now, it's always null.
    Properties properties = new Properties();
    String configuredValue = null;
    Class clazz = SiteCC.class;
    InputStream is = clazz.getResourceAsStream("/customization.properties");
    if (is != null){
      try {
        properties.load(is);
        String propValue = properties.getProperty(mLayerName);
        if (propValue != null){
          configuredValue = propValue;
        }
      } catch (IOException e) {
        e.printStackTrace();
      }
    }
    return new String[] {configuredValue};
  }
}

A customization class is the interface that the Oracle Metadata Services (MDS) framework uses to define which customization layer should be applied to the application's base definition metadata.

Read more... Each customization class corresponds to a customization layer. The customization class evaluates the current context and returns a String result. This String result is used to locate the customization layer.

In a customization class, the following have to be provided:

A name
An array of values after evaluating the customization class. Typically, each layer returns a single value. In the sample code, the array corresponds to the customization layers returned from the runtime properties file, customization.properties. Note that in a real-world application reading a properties file on every invocation might impact performance.
A cache scope for customization layers defined by the customization class

Multiple customization layers can be applied on top of the application's base metadata. Layered customization is applied in the order of precedence as defined by the order of customization classes specified the configuration file adf-config.xml.

In the Application Navigator, select the Model project, then click Rebuild.

You should see a Successful compilation message in the Messages Log window.
In the Application Navigator, expand the Application Resources panel. Under Descriptors | ADF META-INF, double-click adf-config.xml to open the file in the overview editor.

Customization classes must be registered in the application configuration file, adf-config.xml.

Read more...

If you have multiple customization classes, the classes must be added in the order you want the customization layers to be applied. Recall that multiple customization layers can be applied on top of the application's base metadata. The layered customization is applied in the order of precedence as defined by the order of customization classes specified the configuration file.

Click MDS on the left, then click .
In the Edit Customization Class dialog, enter sitecc, then select the class SiteCC (oracle.model.mycompany) and click OK.

The customization class oracle.model.mycompany.SiteCC.java should be listed on the MDS page of the overview editor.

Read more...

Overview editor for adf-config.xml

Click Source in the adf-config.xml overview editor to view the code JDeveloper added for you. You should see the following code:

<adf-mds-config xmlns="http://xmlns.oracle.com/adf/mds/config">
  <mds-config xmlns="http://xmlns.oracle.com/mds/config" version="11.1.1.000">
    <cust-config>
      <match path="/">
        <customization-class name="oracle.model.mycompany.SiteCC"/> 
      </match>
    </cust-config>
  </mds-config>
</adf-mds-config>

The <cust-config> element in <mds-config> specifies the customization classes and their order of precedence for a customized application.

For example, the following code shows that customizations at the industry layer are applied to the base application, and then customizations at the site layer are applied:

<adf-mds-config xmlns="http://xmlns.oracle.com/adf/mds/config">
  <mds-config xmlns="http://xmlns.oracle.com/mds/config" version="11.1.1.000">
    <cust-config>
      <match path="/">
        <customization-class name="oracle.model.mycompany.IndustryCC"/>
        <customization-class name="oracle.model.mycompany.SiteCC"/>
      </match>
    </cust-config>
  </mds-config>
</adf-mds-config>

Click Save All to save your work.

When you complete the steps for creating a customization class, the Application Navigator should look similar to this:

Read more...

Application Navigator, Application Resources panel

The customization class SiteCC.java is created in the package oracle.model.mycompany under the Application Sources folder in the Model project.

You can optionally close all the files in the editor window, since you will not be editing them again in the application.

Step 7: Create Customizable JSF Pages

You will prepare the base application for accepting customizations and create two base pages that can be customized later.

In the Application Navigator, double-click the ViewController project to open the Project Properties dialog.
Select ADF View, then select Enable Seeded Customizations and click OK.

Seeded customization of an application is the process of taking a generalized application and making modifications to suit the needs of a particular group, such as a specific industry or site.

Read more...

When Seeded Customizations is enabled in a project's properties, JDeveloper uses the Oracle Metadata Services (MDS) framework to store customized metadata objects in a metadata repository and retrieve them at runtime to reveal the customized application.

When you click OK, JDeveloper updates web.xml with the necessary configuration elements for using MDS customizations:

<context-param>
  <param-name>oracle.adf.jsp.provider.0</param-name>
  <param-value>oracle.mds.jsp.MDSJSPProviderHelper</param-value>
</context-param>
<filter>
  <filter-name>ADFLibraryFilter</filter-name>
  <filter-class>oracle.adf.library.webapp.LibraryFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>ADFLibraryFilter</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>FORWARD</dispatcher>
  <dispatcher>REQUEST</dispatcher>
</filter-mapping>
<servlet>
  <servlet-name>adflibResources</servlet-name>
  <servlet-class>oracle.adf.library.webapp.ResourceServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>adflibResources</servlet-name>
  <url-pattern>/adflib/*</url-pattern>
</servlet-mapping>

In the Application Navigator, right-click the ViewController project and choose New > Web Tier > JSF/Facelets > ADF Task Flow, then click OK.

An ADF task flow is a reusable unit for defining control flow between activities in an application.

Read more... Each task flow in the application contains a portion of the application's navigational graph, enabling users to complete a task. For example the following illustration shows a simple task flow with two activities, Create and Confirm. The arrows between the activities are known as control flow cases. Activities could be view pages, method calls, or operations calling other task flows.

In the Create ADF Task Flow dialog enter, select, or deselect the following values:

Field or Option	Value
File Name	`orders-task-flow-definition.xml`
Create as Bounded Task Flow	selected
Create with Page Fragments	not selected

Create Task Flow dialog, bounded task flow

An ADF bounded task flow is a specialized form of reusable task flow that always specifies a default activity, which is the single point of entry that must execute immediately upon entry of the bounded task flow.

Read more... A bounded task flow allows input parameters, return values, and reentry.

The Create Task Flow dialog also lets you create unbounded task flows. An unbounded task flow consists of all activities and control flows in an application that are not included within any bounded task flow.

Accept the default values and click OK.

By default JDeveloper opens the bounded task flow in the task flow diagrammer.

Initially the diagram is a blank canvas. If the diagrammer is not the current editor, click the Diagram tab at the bottom of the editor window.

Read more...

The primary type of task flow activity is a View, which represents a JSF page. In the example, you will use the Component Palette to create View activities and control flow cases on the task flow diagram for navigating between a Browse page and a More page.

In the Component Palette, ADF Task Flow page, Components panel, Activities section, drag and drop View on the diagram, then rename the view activity. Do this two times, using the following view activity names for the pages:

Browse
More
In the Component Palette, Components panel, Control Flow section, click Control Flow Case. On the diagram, click the Browse page icon, then click the More page icon. Rename the control flow case element to goMore.
In the Component Palette, click Control Flow Case again. On the diagram, click the More page icon, then click the Browse page icon. Rename the control flow case element to goBrowse.

The default activity is Browse, which is indicated by a green background on the Browse page icon.

Read more... The Browse activity will display an abbreviated Orders form with navigation buttons for browsing all order records. The More activity will display the full Orders form for the current order shown on the abbreviated Orders form.

Initially both page icons on the task flow diagram have yellow warning symbols, which indicate that the View activities are not yet associated with any physical page files (for example, Browse.jsf). Once the page files are created, the yellow warning symbols on the page icons will be removed.

To see the metadata JDeveloper adds for you when you create the task flow diagram using the diagrammer, click Source in the editor window to switch to the XML editor.

In a task flow definition, the top-level element is <adfc-config>, which is the element that appears first in all ADF Controller XML source files. Activities and control flows in a bounded task flow are defined inside <adfc-config>, within the <task-flow-definition> metadata element.

The bounded task flow is identified by the id attribute of <task-flow-definition>. The <control-flow-rule> and <control-flow-case> elements specify the control flow rules for each view activity. The <view> elements correspond to the view activities in the task flow, which do not yet have metadata that identify the physical JSF page files.

On the diagram, double-click the Browse page icon to open the Create JSF Page dialog.
Select Facelets as the document type and accept the default file name of Browse.jsf.
On the Page Layout page, select Blank Page. On the Managed Bean page, select Do Not Automatically Expose UI Components in a Managed Bean.

In the Create JSF Page dialog, you can optionally define some aspects of the look and feel for the new page (PageLayout tab), and you can specify whether or not components on the page are exposed in a managed bean (Managed Bean tab).

Read more...

By default components are not exposed to managed beans. If you wish to bind components to managed beans, select one of the automatic binding options on the Managed Bean page in the dialog. When you use an automatic binding option, JDeveloper automatically creates a backing bean for any new JSF page that you create, and associates every UI component in the page to a corresponding property in the backing bean for eventual programmatic manipulation.

But if you intend to add ADF bindings to a page, do not use the automatic binding feature. If you use the automatic binding feature, you will have to remove the managed bean bindings later, after you have added the ADF bindings.

Create JSF Page dialog, Managed Bean tab

Create JSF Page dialog, Managed Bean tab

Click OK.

By default JDeveloper displays the new JSF page in the visual editor.

The following two configuration elements have also been added to web.xml:

<context-param>
  <param-name>com.sun.faces.faceletCache</param-name>
  <param-value>
   oracle.adfinternal.view.faces.facelets.rich.MDSFaceletCache
  </param-value>
</context-param>
<context-param>
  <param-name>javax.faces.FACELETS_RESOURCE_RESOLVER</param-name>
  <param-value>
   oracle.adfinternal.view.faces.facelets.rich.MDSFaceletsResourceResolver
  </param-value>
</context-param>

These elements are required for MDS customizations on JSF Facelets pages.

In the Component Palette, ADF Faces page, Layout panel, Interactive Containers and Headers section, drag and drop Panel Splitter on the blank page in the visual editor.
In the Property Inspector, Common section, change the Orientation attribute value to vertical.
In the Component Palette, Layout panel, drag and drop Panel Group Layout into the first facet of the panel splitter component you just added.

When you drag the component to the visual editor, you should see a target rectangle with the name Facet first on the page; this means the component you are dragging will be inserted inside that target component.
In the Property Inspector, change the Layout attribute value to scroll.
In the Application Navigator, expand the Data Controls panel, then expand FODAppModuleDataControl.

The Data Controls panel is a JDeveloper data binding tool that is part of the Application Navigator.

Read more... The Data Controls panel shows the structure of your business components data model in a hierarchical display of available business objects, methods, and data control operations.

The Data Controls panel reflects the master-detail hierarchies in your application module data model by displaying detail data collections nested under their master data collection. For example, the OrderItemsView2 collection is shown as a child node under the OrdersView1 collection, indicating the master-detail relationship between orders and order items.

With the aid of the Data Controls panel, UI design is a series of drag-and-drop steps. The list of available UI controls appears when you drop a data object selection (collection or attribute) from the panel into the page. Only the UI controls that are appropriate to display the chosen data object will appear in the list. For example, when you drag a collection from the Data Controls panel, your UI choices include table and form controls, but do not include text input and output controls.

When you drag the OrdersView1 collection from the Data Controls panel onto the page and choose Form > ADF Read-only Form from the Create context menu, you are creating a read-only form to display data from the OrdersView view object.

Drag and drop OrdersView1 into the panel group layout component you just added. From the Create context menu, choose Form > ADF Read-only Form.
In the Edit Form Fields dialog, select all the fields except OrderId, OrderDate, OrderShippedDate, OrderStatusCode, and OrderTotal. Then click to delete the selected fields.
Select both Include Navigation Controls and Include Submit Button, then click OK.
In the visual editor, select the Submit button.
In the Property Inspector, Common section, change the Text value to More Details. In the Action field, select goMore from the dropdown list.
In the editor window, select the document tab orders-task-flow-definition.xml to bring the diagram forward. Double-click the More page icon to open the Create JSF Page dialog.
Select Facelets as the document type. Accept the default file name of More.jsf. On the Page Layout page, select Blank Page. On the Managed Bean page, select Do Not Automatically Expose UI Components in a Managed Bean. Then click OK.
From the Data Controls panel, drag and drop OrdersView1 on the blank page in the visual editor. Choose Form > ADF Read-only Form from the Create context menu. In the Edit Form Fields dialog, accept all defaults and click OK.
In the Component Palette, General Controls panel, drag and drop Button into af:form in the Structure window.
In the Property Inspector, Common section, change the Text value to Return. In the Action field, select goBrowse from the dropdown list.

The More page in the visual editor should look like this:

In both pages, the components are bound to attributes in the ADF data controls, and include ADF data binding expression language (EL) expressions that reference binding objects for displaying data from the data model.

Read more...

In the ViewController project in the Application Navigator, the required application object definition files (for rendering and processing pages that contain ADF databound UI components) are created for you by JDeveloper in the Application Sources folder.

In the editor window, select the document tab orders-task-flow-definition.xml to bring the diagram forward. Right-click the Browse page icon and choose Run.

If the Create Default Domain dialog displays, enter the default password, for example weblogic1, in the Password and Confirm Password fields, then click OK.

The Browse page in your browser should look similar to this:

By default, JDeveloper automatically configures an integrated server named Integrated WebLogic Server that references a user-specific instance of Oracle WebLogic Server bundled with the IDE.

Read more...

Integrated WebLogic Server is a Java EE runtime service for packaged archive deployment. Based on zero-copy deployment, Integrated WebLogic Server lets you run and test an application and its projects as a Java EE application in a Java EE container. No special connection setup is required to use Integrated WebLogic Server. You can run the entire application, a project, or individual JSF pages.

When you run a JSF application in the IDE, JDeveloper automatically:

Starts Integrated WebLogic Server, if not already running.
Compiles and deploys the application to Integrated WebLogic Server.
Launches the application in your default browser using the following default address: http://<your_machine_IP_address>:<http_port>/<your_application_name>-<your_project_name>-context-root>/faces/<path_to_the_page>

To stop the application, click

Terminate in JDeveloper and choose the application bound instance CustomizeApp from the dropdown menu.

Note: Terminating the application stops and undeploys the application from Integrated WebLogic Server but it does not terminate Integrated WebLogic Server.

In the running application, Browse page, try browsing the order records on the abbreviated form, then navigate to the More page to see the full details of the current order.

The More page should show the full details for the currently displayed Orders row in the Browse page.

Read more...

When you click Return on the More page, the application should navigate back to the Browse page.

At this point, you have prepared the base application to accept MDS customizations and created two view pages that can be customized. In the next step, you will customize the application by modifying the view pages and adding an object in the data model.

In JDeveloper, click Terminate and choose Integrated WebLogic Server from the dropdown menu. Then close all files in the editor window.

Step 8: Customize the JSF Pages and a View Object

From the main menu, choose Tools > Switch Roles > Customization Developer. When prompted to restart JDeveloper, click Yes.

You make metadata customizations in an application only when you are working in the Customization Developer role.

Read more... In that role, customization features are enabled in the IDE (for example, the Customization Context window), while some other features are disabled (for example, you cannot create new customizable objects and you cannot edit non-customizable objects).

A customized application contains a base application and one or more layers of customized metadata content. MDS stores the customized metadata objects in a metadata repository and retrieves them at runtime to reveal the customized application. When a customized application is launched, the customized content is applied over the base application.

If necessary, select CustomizeApp from the dropdown list in the Application Navigator to open your customizable application. If not already open, from the main menu choose View > Customization Context to open the Customization Context window.

In the Application Navigator, notice that the icon next to a customizable application name is different from one that is not customizable.

Read more... Also, artifacts in a project that cannot be customized have a lock symbol on the icon next to the object name.

Application Navigator in Customization Developer role

Application Navigator in Customization Developer role

The types of metadata customizations that can be made are:

User interface or view layer customizations
Model layer customizations
Controller layer customizations

Customizations can also be static or dynamic. Static customizations are customization contents that remain the same for the life of the deployment of the application. Dynamic customizations are customizations implemented in layers that allow the layer value to be determined at runtime (for example, customized contents at runtime could depend on the role of the user logged in).

In this step, you will implement static view layer customizations and model layer customizations:

In the site/headquarters layer value, add a Table component to the Browse page to display order items.
In the site/remoteoffices layer value, add an attribute to the OrderItemsView object in the model layer. Then add a Table component to the Browse page to display order items. On the More page, add a Show Detail Header component around the components that make up the order form.

In the Customization Context window, select Headquarters (headquarters) from the Value dropdown list of the site layer.

A customizable application can have multiple customization layers (for example, industry and site.)

Read more... Each layer can have multiple customization layer values (for example, health and financial for industry), but only one layer value from each layer is applied at run time.

When you open a customizable application in the Customization Developer role, JDeveloper reads the adf-config.xml file to determine the customization classes to use and their order of precedence. JDeveloper also reads the CustomizationLayerValues.xml file to determine the layer values to make available in the Customization Context window.

Before your make customizations, you select a customization layer value from the site layer in the Customization Context window. You are allowed to select one customization layer and one layer value at a time. The selected layer shown in the window is called the tip layer.

The customizations you make after selecting a customization layer value will apply to the current layer value or tip layer only. To implement customizations to another layer value, you select a new value in the Customization Context window and then make the customizations.

If you have more than one customization layer, the order of layers presented in the Customization Context window is the same as the order of the customization classes specified in adf-config.xml. For example, suppose you have the following in adf-config.xml:

<adf-config xmlns="http://xmlns.oracle.com/adf/config" ...>
  <adf-mds-config xmlns="http://xmlns.oracle.com/adf/mds/config">
    <mds-config xmlns="http://xmlns.oracle.com/mds/config" ...>
      <cust-config>
        <match path="/">
          <customization-class name="oracle.model.mycompany.SiteCC"/>
          <customization-class name="oracle.model.mycompany.IndustryCC"/>
        </match>
      </cust-config>
    </mds-config>
  </adf-mds-config>
</adf-config>

Upon launching JDeveloper in the Customization Developer role, the last customization class listed within the <cust-config> element will act as the tip layer, as shown in the following illustration of the Customization Context window:

Customization Context window with 2 layers, site is tip

Customization Context window with 2 layers, site is tip

When you select another customization layer, the selected layer then becomes the new tip layer for which you want customizations to be implemented:

Customization Context window

Layer values from multiple customization layers can be applied, in a specified order of precedence, on top of the base application metadata. The metadata displayed in JDeveloper editors is a combination of the base application metadata and the customization layers up to and including the tip layer (according to the precedence set in adf-config.xml), with the values specified in the Customization Context window for each layer.

For example, the following Customization Context window illustration shows that customizations in the remoteoffices layer value of the site layer are applied to the base application, and then customizations in the financial layer value of the industry layer are applied:

The customization context of a customized application is defined by the set of customization layers applied to the base definition of the application. At the bottom of the Customization Context window, the customization context changes to reflect your selection.

In the Application Navigator, ViewController project, double-click Browse.jsf to open the page in the visual editor.
In the Data Controls panel, expand FODAppModuleDataControl, then expand OrdersView1.
Drag and drop OrderItemsView2 into the second facet on the page. From the Create context menu, choose Table > ADF Read-only Table.
In the Edit Table Columns dialog, select Enable Sorting. Select the columns ObjectVersionId, LastUpdateDate, LastUpdatedBy, CreationDate, and CreatedBy.
Click to delete the selected columns, then click OK.

The page in the visual editor should look similar to this:

In the site/headquarters context, you customized the Browse page by adding a databound Table component to display data from the OrderItemsView view object.

Read more...

A customization layer corresponds to a customization document that contains a set of instructions that change the underlying metadata. When you make customizations to the view layer in an application, JDeveloper creates an XML source file using the file name of the view page you are editing. For example, the file name of the Browse page is Browse.jsf; the customization XML document is Browse.jsf.xml.

JDeveloper stores view layer customization documents in the mdssys/cust folder in the ViewController project. Each document is created in its own customization layer value folder. For example, when you are implementing customizations in the site/headquarters context, Browse.jsf.xml is created in the mdssys/cust/site/headquarters folder, as shown in the following Application Navigator illustration:

Application Navigator, mdssys cust folder

Application Navigator, mdssys cust folder

To see the contents of a customization document, double-click the XML file. For example in Browse.jsf.xml, you see metadata elements such as <mds:customization> and <mds:insert> that contain the instructions for modifying the underlying view layer. Note that the <mds:insert> element references the Id value of the parent component Panel Splitter, which specifies where you inserted the Table component on the Browse page.

When customizations to a page include adding or modifying ADF databound UI components, JDeveloper also creates the page definition customization metadata document. For example, when implementing customizations for the Browse page in the site/headquarters context, the page definition customization document BrowsePageDef.xml.xml is created in the subpackage mdssys/cust/site/headquarters in the oracle.view.pageDefs package where all other page definitions are stored. If you open BrowsePageDef.xml.xml, you also see metadata elements such as <mds:customization> and <mds:insert>.

In the Customization Context window, select Remote Offices (remoteoffices) from the Value dropdown list. When prompted, click OK twice to close open files and to save customizations.
In the Application Navigator, Model project, expand Application Sources | oracle.model, then double-click OrderItemsView.
In the overview editor, select Entity Objects on the left. In the Available list, select ProductsBase. Then shuttle it to the Selected list.
Select Attributes on the left. From the dropdown menu, choose Add Attribute From Entity.
In the Attributes dialog, under ProductsBase in the Available list, select ProductName. Then shuttle it to the Selected list.
Click OK, then click Save All.

The overview editor for OrderItemsView should look like this:

In the site/remoteoffices context, you customized the model view object OrderItemsView by adding the ProductName attribute from the ProductsBase entity object.

Read more...

The OrdersItemsView view object now contains attributes from both the OrderItems entity object and the ProductsBase entity object. Notice that OrderItemsView now contains two ProductId attributes: ProductId from the OrderItems entity object and ProductId1 from the ProductsBase entity object; this is necessary to specify the join between the two entity objects.

When you make customizations to the model layer in an application, JDeveloper creates an XML source file using the file name of the model object you are editing. For example, the file name of OrderItemsView is OrderItemsView.xml; the customization XML document is OrderItemsView.xml.xml.

JDeveloper stores model layer customization documents in the mdssys/cust package in the Model project. If the model objects are in a package, then the mdssys package name is prefixed with the same package name as the model objects, for example, oracle.model.mdssys. Each customization document is created in its own customization layer value package. For example, when you are implementing customizations in the site/remoteoffices context, OrderItemsView.xml.xml is created in the oracle.model.mdssys/cust/site/remoteoffices package, as shown in the following Application Navigator illustration:

Application Navigator, Model project

To see the contents of a customization document, double-click the XML file. For example in OrderItemsView.xml.xml, you see metadata elements such as <mds:customization>, <mds:insert> and <mds:modify>.

In the Application Navigator, ViewController project, double-click Browse.jsf to open the page in the visual editor.

Notice that the page does not have the order items table below the orders form, which was added in the site/headquarters customization context.
In the Component Palette, ADF Faces page, Layout panel, drag and drop Panel Collection into the second facet on the page.
In the Data Controls panel, click Refresh. Expand FODAppModuleDataControl, then expand OrdersView1. Drag and drop OrderItemsView2 into the panel collection component you just added. From the Create context menu, choose Table > ADF Read-only Table.
In the Edit Table Columns dialog, select Enable Sorting. Select the columns ProductId1, ObjectVersionId, LastUpdateDate, LastUpdatedBy, CreationDate, and CreatedBy. Then click to delete the selected columns.
Click OK.

The page in the visual editor should look similar to this:

In the site/remoteoffices context, you customized the same Browse page by adding a Panel Collection component, then adding a databound Table component to display data from the OrderItemsView view object.

Read more...

The Table now includes the ProductName column because earlier you customized the model view object OrderItemsView by adding the ProductName attribute from the ProductsBase entity object.

In the Application Navigator, ViewController project, double-click More.jsf to open the page in the visual editor. In the Structure window, expand f:view | af:document | af:form. Collapse af:panelFormLayout, if it's expanded.
In the Component Palette, Layout panel, Interactive Containers and Headers section, drag Show Detail Header and drop it into af:form in the Structure window.
In the Structure window, drag af:panelFormLayout and drop it into af:showDetailHeader.
Then drag af:showDetailHeader to reposition it before af:commandButton - Return.
Click Save All to save your work.

The More page in the visual editor should look similar to this:

In the site/remoteoffices context, you customized the More page by surrounding the form with a Show Detail Header.

Read more...

In the Property Inspector, tip layer modifications are indicated by a orange icon (non-tip layer changes are indicated by an green icon). For example:

In the Application Navigator, ViewController project, you should now see:

The mdssys/cust/site/remoteoffices folder under Web Content, which contains the customization metadata documents More.jsf.xml and Browse.jsf.xml that were created when you customized the pages by adding and moving UI components
The subpackage mdssys/cust/site/remoteoffices (in the oracle.view.pageDefs package under Application Sources), which contains the page definition customization metadata document BrowsePageDef.xml.xml that was created when you customized the Browse page by adding a databound Table component

The customization metadata files contain the instructions for implementing customizations in an application. At runtime, the application applies the customization metadata files over the base application, in the order of precedence as defined in the cust-config section of the adf-config.xml file.

Step 9: Run the Application in the Customization Layer

In the Application Navigator, ViewController project, under Web Content | Page Flows, right-click orders-task-flow-definition and choose Run.

The Browse page should have the order items table below the orders form; the table should have five columns.

When an application with customized metadata is run, the applicable customizations that belong to the active layer values in customization.properties are loaded from the corresponding repository and layered over the base metadata of the application to produce the desired customized contents for viewing.

Read more...

Recall that site=headquarters is the active layer value in customization.properties:

#Configured values for the default layer values
#site=remoteoffices 
site=headquarters

The layer value without the prefix # is the active layer value in the site layer. So when the application is run, the applicable customizations that belong to the active layer value (headquarters) is loaded from the corresponding repository and layered over the base metadata of the application to produce the desired customized contents for viewing.

The customization.properties file can contain configurable layer values defined for one or more customization layers. For example, the properties file could contain the following configurable customization layer values defined for a site layer and an industry layer:

#Configured values for the default layer values
industry=financial
#industry=healthcare
#site=remoteoffices 
site=headquarters

When the application is run, the customized contents would include the base application contents plus custom contents in the industry=financial layer and the site=headquarters layer.

Click More Details to navigate to the complete orders form.

There should not be a show detail header above the orders form.
Click Terminate in JDeveloper and choose CustomizeApp from the dropdown menu to stop the application.
In your file system, open the file customization.properties, which is located in the /Model/src folder of your application folder (for example, C:/JDeveloper/mywork/CustomizeApp/Model/src). In the text editor, add # in front of site=headquarters. Then remove # from site=remoteoffices. Save the file.

To see customized contents belonging to remoteoffices, you restart the application after editing the customization.properties file.

#Configured values for the default layer values
site=remoteoffices 
#site=headquarters

In the Application Navigator, right-click orders-task-flow-definition and choose Run again.

On the Browse page, there should be a View menu and Detach toolbar item above the order items table, and the table should have six columns. The sixth column is ProductName because you customized the OrderItemsView object in the model layer by adding the ProductName attribute from the ProductsBase entity object.
Click More Details to navigate to the complete orders form.

On the More page, you should be able to hide or show the orders form by clicking the icon next to the header.
In JDeveloper click Terminate and choose Integrated WebLogic Server from the dropdown menu.
Close all files in the editor window.

Step 10: Enable User Customizations for the Duration of a Session

User customizations in an application allow end users to make changes to certain UI components at runtime and have those changes persist (for example, hide the contents in a particular panel box), as long the end user does not leave the application.

From the main menu, choose Tools > Switch Roles > Studio Developer. When prompted to restart JDeveloper, click Yes.
In the Application Navigator, double-click the ViewController project to open the Project Properties dialog.
Select ADF View. Then select Enable User Customizations and For Duration of Session. Click OK.

User customizations or change persistence in an application allow end users to make changes to certain UI components at runtime to suit individual preferences (for example, the user can decide which columns are visible in a table), and have those changes "remembered" during the user's session or every time the user opens the application.

Read more...

There are two types of user customizations:

Those that stay in place through the length of the user's session until the user exits the application
Those that are permanently stored in a repository and are restored whenever the user reenters the application

In this step you are enabling user customizations for the length or duration of a session.

When you enable session user customizations, JDeveloper adds the following context initialization parameter into web.xml:

<context-param>
  <param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
  <param-value>session</param-value>
</context-param>

The value of CHANGE_PERSISTENCE is set to session for session change persistence.

In the Application Navigator, ViewController project, under Web Content | Page Flows, right-click orders-task-flow-definition and choose Run.

Note: If you have been following along with the example so far, you would have also enabled seeded customizations in the application. So when you run the application, you will still see the seeded customizations you have made, based on the active customization layer value previously set in customization.properties.
In your browser, increase the width of a table column on the Browse page. Click More Details to navigate to the More page. On the More page, click Return to go back to the Browse page.

The width of the column you changed should remain at the new width.

Many ADF Faces components allow users to change the display of the component at runtime.

Read more... For example, a user can change the position of the splitter in the Panel Splitter component or change whether or not a Show Detail or Show Detail Header component displays the children contents. By default, these changes live only as long as the page request. If the user leaves the page and then returns, the component displays in the manner it is configured by default.

When change persistence is enabled for the duration of a session (also known as session user customizations), the changes end users make are persisted through the length of the user's session until the user leaves the application.

Some of the component attribute value changes persisted by an ADF Faces application, after you configure the application to allow user customizations, are listed below. For the complete list of implicitly persisted attributes and components, see the ADF Faces documentation on OTN.

Component	Attribute	Remarks
Show Detail and Show Detail Header	disclosed	Children contents will display or be hidden, depending on the user's last action.
Panel Splitter	splitterPosition	Position of splitter will remain at the location where it was last moved by the user.
Column	width	Width of column will remain at the size the user last set it.
Column	displayIndex	By default the columns in a table will display in the same order as the data source. At runtime the user can move any column. The new column position will remain at the position where it was last moved by the user.

To make use of ADF Faces implicitly persisted attributes and components in a user session, you don't have to write any code or handle any event, but the following prerequisites must be met:

Session change persistence is enabled in the application (through the CHANGE_PERSISTENCE context parameter in web.xml).
The component that will persist a change must have a unique Id attribute value.

Try moving a table column on the Browse page. Try hiding and showing the form on the More page. Navigate back and forth between the pages each time you make a change.

All changes you make should persist during the session.
Click Terminate in JDeveloper and choose the application bound instance CustomizeApp from the dropdown menu.
Rerun the application. You should not see any of the changes you made previously.
In JDeveloper click Terminate and choose Integrated WebLogic Server from the dropdown menu.

Step 11: Enable User Customizations Across Sessions

User customizations in an application (for example, hide the contents in a particular panel box) can be permanently persisted and made available every time the end user enters the application.

If necessary, from the main menu, choose Tools > Switch Roles > Studio Developer. When prompted to restart JDeveloper, click Yes.
In the Application Navigator, double-click the ViewController project to open the Project Properties dialog.
Select ADF View. Then select Enable User Customizations and Across Sessions Using MDS. Click OK.

You must be in the Studio Developer role to work with user customizations.

Read more...

Previously, you enabled user customizations for the length or duration of a session. In this step, you are enabling user customizations across sessions using MDS as the repository. This means user customizations are permanently stored in a repository, and are restored whenever the end user reenters the application.

When you enable MDS user customizations, JDeveloper adds the following context initialization parameter into web.xml, if not already added:

<context-param>
  <param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
  <param-value>
   oracle.adf.view.rich.change.FilteredPersistenceChangeManager
  </param-value>
</context-param>

The value of CHANGE_PERSISTENCE is set to oracle.adf.view.rich.change.FilteredPersistenceChangeManager for MDS change persistence or user customizations.

The following is also required in adf-config.xml for working with MDS change persistence (which JDeveloper has done for you):

<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/config">
  <persistent-change-manager>
    <persistent-change-manager-class>
      oracle.adf.view.rich.change.MDSDocumentChangeManager
    </persistent-change-manager-class>
  </persistent-change-manager>
</adf-faces-config>

In addition to the elements JDeveloper added for you, to use MDS change persistence, the ADF Faces components that you want to persist changes must have unique Id attribute values.

In the Application Navigator, expand the Application Resources panel. Expand Descriptors | ADF META-INF, then double-click adf-config.xml to open the file in the overview editor.

You will edit the adf-config.xml file to include the following:

The customization class for MDS user customizations
The components and associated attribute values or operations that you want to be persisted in the MDS repository

In the overview editor click MDS, then click .
In the Edit Customization Class dialog, enter usercc. Select the class UserCC (oracle.adf.share.config), then click OK.
In the overview editor, click View. In the Tag Configuration section, select http://xmlns.oracle.com/adf/faces/rich from the Tag Library URI dropdown list.

The View page, Tag Configuration section of the adf-config.xml overview editor lets you declare the components and associated attribute values that you want to be persisted in the repository without writing any code.

Read more...

Certain ADF Faces components have built-in support for session change persistence, that is, they provide persistence through implicitly persisted attributes, without any coding or event handling on your part. Examples of implicitly persisted attributes include the splitterPosition attribute of Panel Splitter, width attribute of Column, and disclosed attribute of Show Detail Header and Show Detail. For a complete list of implicitly persisted attributes and components, see the ADF Faces documentation on OTN.

When you elect to persist changes to an MDS repository, by default, all implicitly persisted attribute changes are persisted to the session, and the change persistence framework then consults the configuration in the application's adf-config.xml file and on the individual JSF pages to determine whether or not the changes should be persisted to the MDS repository. So when you want to persist changes to an MDS repository, you must decide which component attribute values that are implicitly persisted will be persisted for your application, and specify them in adf-config.xml.

When you use the adf-config.xml overview editor to declare the component attribute values that are to be persisted in MDS, JDeveloper adds the necessary code for you. For example, the following code shows that only the width attribute of column and the splitterPosition attribute of panelSplitter will be persisted to an MDS repository; other implicitly persisted component attribute values (such as the collapsed attribute of panelSplitter) will not be persisted to the repository because they are not listed in the application's adf-config.xml:

<taglib-config>
  <taglib uri="http://xmlns.oracle.com/adf/faces/rich">
    <tag name="column">
      <attribute name="width">
        <persist-changes>true</persist-changes>
      </attribute>
    </tag>
    <tag name="panelSplitter">
      <attribute name="splitterPosition">
        <persist-changes>true</persist-changes>
      </attribute>
    </tag>
  <taglib>
</taglib-config>

Note: If you edit the code yourself, make sure you use the correct names as the names of the attributes and components are case-sensitive, and the spellings must be accurate.

Persisting to the repository will negatively affect performance. For this reason, you should configure your application to persist only those values you want to be retained across sessions.

In the Tags section, click and choose column from the context menu.
Click again and choose showDetailHeader.
Click again and choose panelSplitter.

The View page in the overview editor should look like this:
Click Save All to save your work. Then close the adf-config.xml file.

By default all implicitly persisted attribute values of the selected components will be persisted to an MDS repository. Use the checkboxes in the Persist Changes column to change the selections.

Read more...

Implicitly persisted component attribute values declared in adf-config.xml apply globally to all such components used in the application pages. If you do not want an implicitly persisted component attribute value on a certain page to persist, define that attribute value on the specific component's dontPersist attribute directly on the page. Similarly if you want a component with an implicitly persisted component attribute value that is not globally declared in adf-config.xml to persist to the repository, define that attribute value on the specific component's persist attribute directly on the page. The dontPersist and persist attributes accept a list of persisted attribute names that are restricted from persisting to, or allowed to persist to an MDS repository, respectively.

In addition to implicit changes provided by the ADF Faces framework, you can use ADF Faces change persistence APIs to create and handle persisting any explicit attribute value changes to components. If you have such explicitly persisted component attribute value changes and you want them to persist to an MDS repository, you must also declare them in the application's adf-config.xml file (in addition to the implicit changes that you want persisted).

Step 12: Configure ADF Security and Create a User

Before you can persist user customizations across sessions using MDS as the repository, you must configure ADF Security and create users for the application.

From the main menu, choose Application > Secure > Configure ADF Security.

The Oracle ADF Security framework, which is is built on top of the Oracle Platform Security Services (OPSS) architecture, is the preferred technology to provide authentication and authorization services to a Fusion web application.

Read more...

ADF Security implements a Java Authentication and Authorization Service (JAAS) security model. The JAAS model is policy-based since JAAS is built on the existing Java security model and integrates with any JAAS implementation. You enable ADF Security for Fusion web applications when you run the Configure ADF Security wizard. The wizard configures ADF Security for the entire Fusion web application, so that any web page associated with an ADF security-aware resource (for example, bounded task flows) is protected by default. When ADF Security is enabled, the application requires an explicit call to the ADF Security framework to authorize access to resources based on security policies.

After you enable ADF Security, you grant users access rights so that they may view the web pages of the Fusion web application. Access rights that you grant users are known as a security policy that you specify for the page's corresponding ADF security-aware resource. It is the security policy on the ADF resource that controls the user's ability to enter a task flow or view a web page. Because ADF Security is based on JAAS, security policies identify the principal (the user or application role), the ADF resource (for example, bounded task flows), and the permission (an operation defined by the resource's ADF permission class).

On step 1 of the wizard, ADF Security, accept the default selection of ADF Authentication and Authorization. Click Next.

Oracle ADF Security delegates authentication to the web container. The most commonly used types of authentication methods are HTTP Basic Authentication and Form-Based Authentication.

Read more...

Basic authentication uses the browser login dialog for the user to enter a user name and password. Note that with basic authentication, the browser caches credentials from the user, thus preventing logout. Basic authentication is useful when you want to test the application without requiring a custom login page.

On step 2, Authentication Type, accept ViewController.jpr as the Web Project. Make sure HTTP Basic Authentication is selected. Click Next.
On step 3, Automatic Policy Grants, make sure No Automatic Grants is selected. Click Next.
On step 4, Authenticated Welcome, do not select Redirect Upon Successful Authentication. Click Finish.
In the Security Infrastructure Created dialog, click OK.

After you run the Configure ADF Security wizard with the default ADF Authentication and Authorization option and all other default values, the wizard has:

Enabled ADF authentication to prompt the user to log in
Enabled ADF authorization to enforce permission checking so that only authorized users will have access to ADF resources
Created the jazn-data.xml file in the src/META-INF folder relative to the application workspace
Created the weblogic.xml in the public_html/WEB-INF folder relative to the application workspace
Updated all security-related configuration files such as jps-config.xml, web.xml, and adf-config.xml.

As ADF authorization enforces permission checking against security policies that you define for ADF security-aware resources (such as bounded task flows), this means you have to define application roles and assign explicit grants to those roles to manage access to the ADF resources.

From the main menu, choose Application > Secure > Application Roles to open the overview editor for jazn-data.xml.

The jazn-data.xml file is a development environment file.

Read more...

When you develop secure Fusion Web applications in JDeveloper, the jazn-data.xml file is created automatically when you run the Configure ADF Security wizard, and the application security policy (for example, CustomizeApp) is also automatically added for you. You use the overview editor for jazn-data.xml to define security policies for ADF resources associated with web pages for the entire application. You can also use the overview editor to sort ADF resources and easily view those that have no security policy yet defined.

When you use the overview editor to add or edit a configuration, JDeveloper updates the jazn-data.xml file for you. The jazn-data.xml file supports easy testing in JDeveloper yet remains compatible with deployment to your production environment. When you finish configuring the jazn-data.xml file using the editor, you can run the application in Integrated WebLogic Server and the contents of the policy will be added to the domain-level store, the system-jazn-data.xml file.

From the Roles dropdown menu, choose Add New Role.
In the Name field, enter BasicUserRole and press Tab.
Click the Users tab on the left.

At the top right corner of the editor, the Realm dropdown should show jazn.com.

A realm is a collection of authenticated users and roles. The default realm in Oracle ADF Security is jazn.com, which is defined in jazn-data.xml.

Read more...

A user is an authorized end user accessing a service; it could be an individual or a software component. An application role represents the security policy requirements and defines groups of users with the same view permission rights.

In the Users section, click New User. In the Name field, enter user1 and press Tab. Enter welcome1 in the Password field, then press Tab. Renter the password in the Confirm Password field and press Tab.
Click the Application Roles tab and select the role you created earlier, BasicUserRole. In the Mappings section, from the Mapped Users and Roles dropdown menu, choose Add User.
In the Select Users dialog, select user1 and click OK.

You should see user1 in the Mappings section of the overview editor.
In the overview editor, click the Resource Grants tab on the left.
In the Resource Type dropdown list, select Task Flow.

The Source Project field should now be populated with ViewController. (If not, click next to the field and use the dialog to move ViewController into the selected list.)
Select the application bounded task flow orders-task-flow-definition in the Resources column. From the Granted To dropdown menu, choose Add Application Role.
In the Select Application Roles dialog, select BasicUserRole and click OK.
In the overview editor, Actions column, make sure view is selected. Then select customize, grant, and personalize.
Click Save All to save your work.

You have defined a security policy for the ADF resource orders-task-flow-definition, granted an application role to the task flow, and selected task flow specific permissions to grant to users of the selected application role.

Read more...

Note that you do not need to define resource grants for individual web pages of a bounded task flow. When the user accesses the bounded task flow, security for all pages will be managed by the permissions you grant to the task flow. And, because the contained web pages (with associated page definitions) are inaccessible by default, ADF Security prevents users from directly accessing the pages of the task flow.

Step 13: Run and Personalize the Application

After you have enabled user customizations across sessions, defined which component attribute value changes should be persisted to MDS, and configured ADF security, you are ready to personalize the application for a user.

In the Application Navigator, ViewController project, under Web Content | Page Flows, right-click orders-task-flow-definition and choose Run.

If you have been following along with the example so far, you would have enabled user customizations across sessions and seeded customizations in the application,

Read more... both of which use the MDS repository. So when you run the application, you will see the seeded customizations you made, based on the active customization layer value previously set in customization.properties.

When the Authentication Required dialog displays, enter the username and password as user1 and welcome1, respectively. Then click OK.
On the Browse page, increase the width of the ProductName column. Then move the ProductId column to place it before the ProductName column. Move the splitter bar down. Click More Details to navigate to the More page. Hide the form contents. Then click Return to go back to the Browse page.

You personalize the application by making changes to persistent component attributes such a table column's width and the order of columns displayed in the table.

Read more...

When you make a persistent component attribute change on the Browse or More page, JDeveloper creates an XML metadata change persistence file using the page's file name, and stores the XML file in a subfolder in the mdssys/cust/user folder. For example, the XML change persistence file created for the Browse page is Browse.jsf.xml.

By default JDeveloper creates the mdssys/cust/user folder in the system11.1.2.0.x.x.x/o.mds.ide.deploy.base/adrs/<application_name>/AutoGeneratedMar/mds_adrs_writedir directory where you have JDeveloper installed. For example,

C:/JDeveloper_Home/jdeveloper/system11.1.2.0.x.x.x/o.mds.ide.deploy.base/adrs/CustomizeApp/AutoGeneratedMar/mds_adrs_writedir

.

In the mdssys/cust/user folder, the XML metadata change persistence files are stored in different subfolders sorted by user id. For example, mdssys/cust/user/user1 where user1 is the user id.

By default JDeveloper also preserves customizations across applications runs. This means when you stop the application and then rerun it, you should see all the changes you made during the previous run. You can change the default setting in the Application Properties dialog.

Application Properties, Run page

If you choose not to preserve customizations across application runs, the metadata change persistence files and the entire mdssys/cust/user folder are deleted each time you run the application from within JDeveloper. Be sure to make a copy of the entire mdssys/cust/user folder and its contents if you want to save the metadata change persistence files.

When a real-world application configured to use MDS is being deployed, the administrator will be prompted to select an MDS repository. In a typical application that is deployed to a standalone server, the metadata change persistence files created when you personalize the application are stored in the selected MDS repository.

Stop the application, then right-click orders-task-flow-definition and choose Run again.

On the Browse page, you should see all of the changes you made previously. When you navigate to the More page, the form contents should be hidden.

If you open a metadata change persistence file, you should see the elements JDeveloper created when you personalized the page at runtime.

Read more... For example, if you open Browse.jsf.xml, you should see code similar to the following:

<mds:customization ...>
  <mds:modify element="s2c1">
    <mds:attribute name="displayIndex" value="0"/>
  </mds:modify>
  <mds:modify element="s2c4">
    <mds:attribute name="displayIndex" value="1"/>
  </mds:modify>
  <mds:modify element="s2c3">
    <mds:attribute name="displayIndex" value="2"/>
  </mds:modify>
  <mds:modify element="s2c5">
    <mds:attribute name="displayIndex" value="3"/>
    <mds:attribute name="width" value="302"/>
  </mds:modify>
  <mds:modify element="s2c6">
    <mds:attribute name="displayIndex" value="5"/>
  </mds:modify>
  <mds:modify element="s2c2">
    <mds:attribute name="displayIndex" value="4"/>
  </mds:modify>
  <mds:modify element="ps1">
    <mds:attribute name="splitterPosition" value="412"/>
  </mds:modify>
</mds:customization>

MDS records persistent changes against the unique value of the component's Id attribute.

Summary

In this tutorial you created a customizable Fusion web application and personalized the application. You learned how to:

Use JDeveloper wizards and dialogs to create applications and projects, task flows, and starter pages
Create a data model with ADF Business Components
Create a customization layer file and a customization class
Configure customization classes in adf-config.xml
Prepare the base application to accept MDS customizations
Use the Data Controls panel to create databound UI components without writing any code
Switch roles in JDeveloper
Customize an application in the Customization Developer role
Implement view layer and model layer customizations
Use Integrated WebLogic Server to run a Fusion web application
Run a customizable application and switch active customization layer values
Enable user customizations in an application so the application can be personalized for a user
Configure components and attributes that users want persisted in the MDS repository
Configure ADF Security and enable ADF authentication and authorization for user login and permission checking
Define a security policy to secure an ADF resource and grant access rights to a group of users in an application role

To learn more about developing customizable applications, refer to:

Expand all | Hide all