10 Performing Oracle Composer-Specific MDS Configurations

This chapter describes how to create customization layers for saving changes made to the page at runtime. It also describes how to enable Oracle Composer sandbox creation to provide users the option to preview their changes before saving them to the back end. It contains the following sections:

10.1 Introduction to MDS

Most industries customize their enterprise applications to serve different audiences and domains. Problems can arise when an application is modified at the site level. For example, upgrading an application with site-level customizations may lead to data loss or data-merge errors. Consequently, a new version of the application cannot be deployed until all merge conflicts are reconciled.

In the metadata domain, MDS provides the customization feature to address such problems. The customization feature allows for the creation of nonintrusive customization layers that are applied on top of the base application definitions. Customization layers, or layered changes, are described in their own documents and are stored separately from the base application definition. At runtime, applicable customizations are loaded from the metadata store and layered over the base metadata definition to produce the desired effect. Product upgrades and patches affect only the base metadata definition, so customizations continue to function properly.

Customization Layers

MDS enables clients to specify multiple customization types. For example, you can add customizations to runtime modes, application or user roles, application states, or any client specified criteria. Each such customization type is called a customization layer and is depicted using a CustomizationClass. A CustomizationClass is the interface MDS uses to identify the customization layer to be overlaid on the base definition. For example, you can configure your application to save customizations based on the departments to which users belong. You can create a customization layer called DepartmentCC in which customizations made by users in different departments are stored in different folders within the layer. Another example would be to configure MDS to save View mode changes as personalizations in one layer and Edit mode changes as customizations in another layer or vice versa.

Customization layers are applied in order of precedence, that is, if the same change is made in two different layers that apply to the given user and session, the change defined in the higher precedence layer is applied first.

When you implement a CustomizationClass, you must register it with the MDS. The MDS provides a means of associating a list of CustomizationClass types with a single MetadataObject. This is called the fine-grained association. The MDS also provides the means of associating a list of CustomizationClass types with a set of MetadataObjects. This is called the coarse-grained association. For information about the CustomizationClass and about creating a customization layer, see Section 10.3, "Adding Customization Layers to View and Edit Modes: Example."

Oracle Composer Sandbox

Typically, in a custom WebCenter application, runtime customizations are saved immediately in the JDEV_HOME/jdev/system_directory/o.mds.dt/adrs/application_name/AutoGeneratedMar/mds_adrs_writedir directory. Changes made in both View and Edit modes are saved in this way. However, in certain circumstances, users might first want to apply customizations in their own view and evaluate whether to keep or cancel the changes before actually saving them to the back end. You can configure Oracle Composer to create a sandbox if you are using a database repository to store customizations. For information about creating a sandbox, see Section 10.2, "Using Oracle Composer Sandbox."

10.2 Using Oracle Composer Sandbox

A sandbox is a temporary storage layer for saving runtime page customizations until they are committed to the back end. If you configure a sandbox, a Save button is displayed on the Oracle Composer toolbar to enable users to save their changes. In a sandbox-enabled application, if a user clicks Close without first saving changes, a Close Confirm dialog prompts the user to save or cancel changes before closing Oracle Composer.

Personalizations made in View mode are saved immediately. As such changes are available only to the user modifying the page, there is no particular value in reviewing such changes before saving.

Since Edit mode customizations are available to all users who access the page, you can enable a sandbox so that a user can experiment with page customizations and assess them before committing them. If you enable a sandbox for the application, a Save button is displayed on the Oracle Composer toolbar in both Design view and Source view of the page.

This section discusses the steps you can take to enable sandbox creation and describes runtime behavior of a sandbox-enabled application. It contains the following subsections:

10.2.1 How to Enable Oracle Composer Sandbox Creation

You can enable a sandbox only if your application uses a database store. Therefore, you must ensure that you have configured a database store before performing the steps in this section. For information about setting up a database store, see Oracle Fusion Middleware Configuring and Managing JDBC for Oracle WebLogic Server.

This section describes how to enable the creation of an Oracle Composer sandbox. It contains the following subsections:

10.2.1.1 Updating Your Application's adf-config.xml File

You must update the adf-config.xml file to define and configure namespaces for all the metadata for which you want to support sandbox creation. This section describes how.

Note:

For information about the Oracle Composer-specific configurations you can make in adf-config.xml, see Section B.2.2, "adf-config.xml."

To configure sandbox creation in adf-config.xml:

  1. Open the adf-config.xml file located in the ADF META-INF folder under Descriptors in the Application Resources panel.

  2. Under the <metadata-namespaces> element, ensure that <namespace> elements are defined for all metadata for which you want to enable sandbox creation, as shown in Example 10-1.

    Example 10-1 Namespace Definitions in the adf-config.xml File

    <!-- Your jspx customizations alone go here -->  
       <namespace path="/pages" metadata-store-usage="WebCenterFileMetadataStore">
         <namespace-restriction type="CUSTOMIZATIONS"/>
       </namespace>
    <!-- Your pagedef customizations alone go here -->
       <namespace path="/pageDefs" metadata-store-usage="WebCenterFileMetadataStore">
         <namespace-restriction type="CUSTOMIZATIONS"/>
         </namespace>
    
  3. Add the <sandbox-namespaces> element within the <page-editor-config> section and add individual <namespace> tags for all namespaces for which you want to enable sandbox creation, as show in Example 10-2.

    Example 10-2 Configuring Namespaces for Sandbox Creation

    <sandbox-namespaces>
      <namespace path="/pages"/>
      <namespace path="/pageDefs"/>
    </sandbox-namespaces>
    
  4. Save the adf-config.xml file.

10.2.1.2 Updating Your Application's web.xml File

To ensure that a sandbox is configured when you are in Edit mode of a page, you must create a filter in your application's web.xml file and set the appropriate filter mappings. All requests are then routed through this filter, and a sandbox is created for all Edit mode customizations. If you are using a file system metadata store, then there is no action performed on a filtered request.

Note:

For information about the Oracle Composer-specific configurations you can make in web.xml, see Section B.2.3, "web.xml."

This section provides the example of defining a Composer-specific filter and its relevant filter mappings in your application's web.xml file. It describes how to add the filter, WebCenterComposerFilter.

To define a Composer-specific filter and the filter mappings:

  1. Open the application_root/ViewController/public_html/WEB-INF/web.xml file.

  2. Add ServletADFFilter and WebCenterComposerFilter before the adfBindings filter so that all requests are routed through these filters first:

    <filter>
      <filter-name>ServletADFFilter</filter-name>
      <filter-class>oracle.adf.share.http.ServletADFFilter</filter-class>
    </filter>
    <filter>
      <filter-name>WebCenterComposerFilter</filter-name>
       <filter-class>oracle.adf.view.page.editor.webapp.WebCenterComposerFilter</filter-class>
    </filter>
    
  3. Add corresponding <filter-mapping> elements before the filter mapping for AdfBindingFilter as shown in Example 10-3.

    Example 10-3 Filter Mappings for Composer-Specific Filter

    <filter-mapping>
      <filter-name>ServletADFFilter</filter-name>
      <servlet-name>Faces Servlet</servlet-name>
      <dispatcher>FORWARD</dispatcher>
      <dispatcher>REQUEST</dispatcher>
    </filter-mapping>
    <filter-mapping>
      <filter-name>WebCenterComposerFilter</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>
    <filter-mapping>
      <filter-name>WebCenterComposerFilter</filter-name>
      <url-pattern>/faces/*</url-pattern>
      <dispatcher>FORWARD</dispatcher>
      <dispatcher>REQUEST</dispatcher>        
    </filter-mapping>    
    

    The <url-pattern> tag is used to specify the pages that must pass through the WebCenterComposerFilter so that sandbox creation can be enabled when a page goes into Edit mode.

    Note:

    The order in which you define filters is important. Requests pass through these filters sequentially and if they are not defined in the correct order, the application will not run as designed. Your web.xml file must have the ServletADFFilter implementation first, followed by WebCenterComposerFilter and AdfBindingFilter implementations, in that order.
  4. Save the web.xml file.

10.2.1.3 Selecting a Database Store for Your Application

To enable sandbox creation, your application must be configured to use a database store. Therefore, while deploying your application to a WebLogic Managed Server, ensure that you select a database repository and specify a partition name for the application.

For information about deploying your application from JDeveloper to a WebLogic Managed Server, see Section 38.3.3, "Deploying a Custom WebCenter Application to a Managed Server."

10.2.2 What Happens at Runtime

When a user switches to page Edit mode, the presence of a Save button on the Oracle Composer toolbar indicates that sandbox creation is enabled for the application. Changes made to the page or shared components on the page are not saved until the user clicks Save. Once saved, the customizations are available to all application users. If the Save button is not rendered, then sandbox is not available and each change is committed immediately.

When editing component properties in the Component Properties dialog, clicking Apply results in the following:

  • If the sandbox is not available, then the page is refreshed to display the changes made to component properties and changes are saved to the back end.

  • If the sandbox is available, then the page is refreshed to display the changes made to component properties. To save changes, user must click Save.

Clicking Save or Close on the page results in the following events:

  • On clicking Save, the sandbox is committed and a new sandbox is created. The page remains in Edit mode.

  • On clicking Close, either of the following two events can occur:

    • If there are no changes since the last Save operation, then the sandbox is destroyed and Oracle Composer is closed, taking the user back to View mode.

    • If there are unsaved changes, then a Close Confirmation dialog lists the page name and unsaved task flow names, as shown in Figure 10-1.

      Figure 10-1 Confirm Close Dialog in Oracle Composer

      Description of Figure 10-1 follows
      Description of "Figure 10-1 Confirm Close Dialog in Oracle Composer"

      Users can select from the following options:

      • Click Save to commit the sandbox and close Oracle Composer.

      • Click Don't Save to destroy the sandbox and close Oracle Composer.

      • Click Cancel to close the dialog and return to Oracle Composer without saving the changes.

      Notes:

      If a user navigates away from a page while editing it and then returns to the page, any unsaved changes are lost.

What Happens During Concurrent Edits

If two or more users are editing the same page or task flow using the same customization layer, then the page displays a message to each user that another user is editing the page or task flow, as shown in Figure 10-2.

Figure 10-2 Page Concurrency Message

Description of Figure 10-2 follows
Description of "Figure 10-2 Page Concurrency Message"

If two or more users have zoomed into a task flow at the same time in the same customization layer and are editing it, then a concurrency message appears, as shown in Figure 10-3.

Figure 10-3 Task Flow Concurrency Message

Description of Figure 10-3 follows
Description of "Figure 10-3 Task Flow Concurrency Message"

Note:

If a user zoomed into a task flow, made some customizations, and zoomed out of the task flow, then the task flow concurrency message continues to display to other users until that user saves the customizations.

Changes that are saved last overwrite prior changes. For example, if users A and B are editing a page or task flow simultaneously, then concurrency issues are handled as follows:

  • If A saves the page or task flow first, then A's changes are committed to MDS. Later, when B saves the page or task flow, A's changes are overwritten with B's changes.

  • If A deletes a component while B is trying to personalize (say move) that same component in View mode, a WebCenter error page is displayed to B. B has to simply navigate back to the original page. The deleted component does not appear, and B can continue working on other components.

10.2.3 How to Disable Sandbox for an Application

To ensure that changes are committed to the back end immediately, you can disable the sandbox.

To disable sandbox:

  1. Open the adf-config.xml file located in the ADF META-INF folder under Descriptors in the Application Resources panel.

  2. Under the <page-editor-config> element, add the <disable-sandbox> attribute and set it to true.

  3. Save adf-config.xml.

10.2.4 How to Destroy Stale Sandboxes

When users edit a page at runtime, if the browser closes unexpectedly or the user navigates away from the page, the sandbox used in that session is still available. Any other user accessing the same page continues to see a concurrency message that another user is editing the same page. You can destroy such stale sandboxes to free some space in the database store and enhance performance.

You can ensure that a stale sandbox is destroyed when:

  • A session times out.

    The <session-timeout> element in the application's web.xml file defines the time duration after which the sandbox is destroyed.

  • The user logs in to Edit mode of the page again, with the same user name.

    In this case, a new sandbox is created when the same user switches to Edit mode. To ensure this happens, you must configure WebCenterComposerSessionListener in your application's web.xml file. This listener is called when a session times out. It creates a new sandbox when the same user renters page Edit mode.

To configure WebCenterComposerSessionListener:

  1. Open the application_root/ViewController/public_html/WEB-INF/web.xml file.

  2. Define a new listener, WebCenterComposerSessionListener, as shown in the following example:

    <listener>
      <description>Oracle Composer Http Session Listener</description>
      <display-name>Oracle Composer Http Session Listener</display-name>
      <listener-class>
        oracle.adf.view.page.editor.webapp.WebCenterComposerSessionListener
      </listener-class>
    </listener>
    
  3. Save the web.xml file.

For information about the Oracle Composer-specific configurations you can make in web.xml, see Section B.2.3, "web.xml."

10.2.5 How to Enable Application Sandbox Creation

Consider an example where you have created an application that displays a banner at the top of the page, a sidebar on the left with options to manage pages, and the page at the center of the browser window. You may want to enable users to edit the page in Oracle Composer and edit the sidebar using some other mechanism such as updating an XML file. Enabling Oracle Composer sandbox in such a case only saves changes to page content but not the sidebar. If you enable the application sandbox, then all changes made at runtime are saved at one time, to one location. If you enable sandbox creation at the application level, then Oracle Composer does not create its own sandbox when page Edit mode is invoked. Instead, the application sandbox is used. That is, a user interface provided by the application is used for committing and destroying the sandbox. To enable the application to provide a sandbox for Oracle Composer, you must first perform a set of configurations.

Another example where it is useful to enable the application sandbox is if you want users to edit page content, but ensure that the page is saved only on approval from the manager. By using an application sandbox, changes made by a user are in the sandbox until the manager approves the changes. The page is saved on approval.

To enable an application sandbox for use in Oracle Composer:

  1. Implement a ComposerSessionOptionsFactory class to provide MDSSessionOptions for each request.

    For information about performing this task, see Section 10.3.4, "How to Implement the ComposerSessionOptionsFactory Class."

  2. Register your implementation with Oracle Composer.

    For information about performing this task, see Section 10.3.5, "How to Register the Implementation with Oracle Composer."

  3. Configure WebCenterComposerFilter.

    For information about performing this task, Section 10.3.6, "How to Configure WebCenterComposerFilter."

10.2.6 What Happens When You Enable Application Sandbox Creation

At runtime, the application-defined user interface enables users to save their changes to the back end or close Oracle Composer without saving the changes. In this case, Oracle Composer has no control over when customizations are canceled or committed to the back end.

10.3 Adding Customization Layers to View and Edit Modes: Example

You can apply customizations to a metadata object based on client-defined criteria. For example, you can customize an application and the metadata objects that it uses based on an end-user's permissions, an application's deployment location (also called localization), or a specific industry domain. Each such category—permissions, localization, and domain—denotes a customization layer, and each is depicted using a CustomizationClass. A CustomizationClass is the interface MDS uses to identify the customization layer to be overlaid on the base definition. See Section 10.3.3, "How to Create a Custom UserCC Tip Layer" for an example.

When you implement a CustomizationClass, you must also register it with the MDS. The MDS provides the ability to associate a list of CustomizationClass types with a single MetadataObject. This is called fine-grained association. The MDS also provides the ability to associate a list of CustomizationClass types with a set of MetadataObjects. This is called the coarse-grained association.

A customizable application can have multiple customization layers. You can select the layer to which you want to apply customizations. The layer you choose to customize is called the tip layer. When you drop Oracle Composer components onto a JSF page, the ADF configures a default SiteCC (site) tip layer in the application. Consequently, the adf-config.xml file is updated to include the SiteCC customization class. This tip layer stores all customizations made to the page.

This section explains through example how adding customization tip layers to View and Edit runtime modes provides personalization capabilities to all users and customization capabilities to selective users. To enable customizations in the Edit mode, the site tip layer is added. To enable personalization in the View mode, the user tip layer is added. By default, the user tip layer is applied on top of the site tip layer. The user tip layer stores all customizations made in the View mode in a specific location created for the user who made them. Such changes are visible only to that user. The site tip layer stores all customizations made in the Edit mode and are visible to all users.

To enable tip layers at runtime, Oracle Composer provides the WebCenterComposerFilter filter and supplies a means of defining an abstract factory for creating the MDS SessionOptions object. This object provides applicable customization layers at runtime and enables users to perform personalizations (View mode) or customizations (Edit mode) based on their role. When creating a new MDS session, the MDSSession.createSession method of this object is used to specify the session options.

This section provides an example exercise for creating, implementing, and registering customization layers, configuring WebCenterComposerFilter, and switching between MDS customization layers. It contains the following subsections:

10.3.1 How to Add Oracle Composer to a JSF Page

This section describes how to add the Page Customizable component to a JSF page. The purpose of this exercise is to provide Oracle Composer in the Edit mode at runtime so that the admin user can perform customizations at the site level. This section includes the addition of a Change Mode Link to enable switching from View mode to Edit mode at runtime.

To add Oracle Composer to a JSF Page:

  1. Open the JSPX page and select Oracle Composer from the Component Palette.

  2. Select Change Mode Link and drop it onto the page.

  3. Select Page Customizable and drop it onto the page.

    The Source view should like this:

    <af:form id="f1">
      <pe:changeModeLink id="cml1"/>
      <pe:pageCustomizable id="pageCustomizable1">
        <cust:panelCustomizable id="panelCustomizable1" layout="scroll"/>
          <f:facet name="editor">
            <pe:pageEditor id="pep1"/>
          </f:facet>
      </pe:pageCustomizable>
    </af:form>
    

    When you drop these components onto the page, the default SiteCC tip layer is extended by the ADF. Consequently, the adf-config.xml file is updated with this customization class:

    <cust-config>
      <match>
        <customization-class name="oracle.adf.share.config.SiteCC" />
      </match>
    </cust-config>
    

    Note:

    If you want your application to use UserCC as the default tip layer, you can simply replace oracle.adf.share.config.SiteCC with oracle.adf.share.config.UserCC in the cust-config section of the adf-config.xml file. However, to use UserCC as the default tip layer, you must have secured your application. You cannot implement a UserCC tip layer without provisioning users and roles in your application.

10.3.2 How to Create a Custom SiteCC Tip Layer

This section describes how to create a custom SiteCC tip layer, site, in which all site-level customizations performed in Edit mode are stored. In this sample application, site-level customizations are stored in the /mds/mdssys/cust/site/webcenter/pagename.jspx.xmldirectory.

To create the site tip layer:

  1. From the File menu, choose New.

  2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.

    The Create Java Class dialog opens.

  3. In the Name field, enter SiteCC.

  4. In the Extends field, enter CustomizationClass.

    This imports oracle.mds.cust.CustomizationClass.

  5. Click OK.

    The SiteCC.java file is rendered in the Source view.

  6. To implement the getCacheHint, getName, and getValue methods, double-click the bulb on the left corner and select Implement Methods.

  7. In the Implement Methods dialog, click OK.

  8. In the Source view, press Enter after public class SiteCC extends CustomizationClass, and add the following string:

    {
      private static final String DEFAULT_LAYER_NAME = "site";
      private String mLayerName = DEFAULT_LAYER_NAME;
      private String mLayerValue = "webcenter";
    

    The following libraries are imported:

    import oracle.mds.core.MetadataObject;
    import oracle.mds.core.RestrictedSession;
    import oracle.mds.cust.CacheHint;
    
  9. Update the code as shown in bold here:

    public class SiteCC extends CustomizationClass
    {
      private static final String DEFAULT_LAYER_NAME = "site";
      private String mLayerName = DEFAULT_LAYER_NAME;
      private String mLayerValue = "webcenter"; 
      //Note: You can provide any site name.
    
      public CacheHint getCacheHint()
      {
        return CacheHint.ALL_USERS;
      }
    
      public String getName()
      {
        return mLayerName;
      }
    
      public String[] getValue(RestrictedSession mdsSession, MetadataObject mo)
      {
        return new String[] { mLayerValue };
      }
    }
    
  10. Save the SiteCC.java file.

10.3.3 How to Create a Custom UserCC Tip Layer

This section describes an example showing how to create a custom user tip layer for a user, scott. This layer is applied on top of the site layer. The personalizations that a user performs in View mode are saved in this user tip layer in a folder created specifically for the logged-in user. In this example, the personalizations performed in View mode are saved in the /mds/mdssys/cust/user/scott/pagename.jspx.xmldirectory.

Note:

For illustration purpose, this example describes a simple scenario where a UserCC tip layer is created for just one user, scott. In a real life application, you can configure the UserCC layer to return the name of the user who requested the page.

To create the user tip layer:

  1. From the File menu, choose New.

  2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.

    The Create Java Class dialog opens.

  3. In the Name field, enter UserCC.

  4. In the Extends field, enter CustomizationClass.

    This imports the oracle.mds.cust.CustomizationClass.

  5. Click OK.

    The UserCC.java file displays in the Source view.

  6. To implement the getCacheHint, getName, and getValue methods, double-click the bulb on the left corner and select Implement Methods.

  7. In the Implement Methods dialog, click OK.

  8. In the Source view, press Enter after public class SiteCC extends CustomizationClass, and add the following string:

    {
      private static final String DEFAULT_LAYER_NAME = "user";
      private String mLayerName = DEFAULT_LAYER_NAME;
      private String mLayerValue = "scott"; //The name of the logged-in user
    in this example. The logged-in user name can be acquired dynamically.
    

    The following libraries are imported:

    import oracle.mds.core.MetadataObject;
    import oracle.mds.core.RestrictedSession;
    import oracle.mds.cust.CacheHint;
    
  9. Update the code as shown in bold here:

    public class UserCC extends CustomizationClass
    {
      private static final String DEFAULT_LAYER_NAME = "user";
      private String mLayerName = DEFAULT_LAYER_NAME;
      private String mLayerValue = "scott";
    
      public CacheHint getCacheHint()
      {
        return CacheHint.USER;
      }
    
      public String getName()
      {
        return mLayerName;
      }
    
      public String[] getValue(RestrictedSession mdsSession, MetadataObject mo)
      {
        return new String[]{mLayerValue};
      }
    }
    
  10. Save the UserCC.java file.

10.3.4 How to Implement the ComposerSessionOptionsFactory Class

In this section, the ComposerSessionOptionsFactory class provided by the ADF is implemented to supply MDS SessionOptions for each HTTP request.

To implement the ComposerSessionOptionsFactory class:

  1. From the File menu, choose New.

  2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.

    The Create Java Class dialog opens.

  3. In the Name field, enter AppsSessionOptionsFactoryImpl.

  4. Click OK.

    The AppsSessionOptionsFactoryImpl.java file is rendered in the Source view.

  5. Import the following libraries:

    import oracle.adf.view.page.editor.mds.ComposerSessionOptionsFactory;
    import oracle.adf.view.page.editor.mode.ModeContext;
    import oracle.mds.config.CustClassListMapping;
    import oracle.mds.config.CustConfig;
    import oracle.mds.core.SessionOptions;
    import oracle.mds.cust.CustClassList;
    import oracle.mds.cust.CustomizationClass;
    
  6. Add the following code to implement the ComposerSessionOptionsFactory class and provide SessionOptions:

    public class AppsSessionOptionsFactoryImpl
      implements ComposerSessionOptionsFactory
    {
    
      public SessionOptions createSessionOptions(SessionOptions defaultSessionOptions, String mode)
      {
        CustomizationClass[] custLayer;
        CustConfig custConfig = null;
    
        if (ModeContext.EDIT_MODE.equals(mode))
        {
          //Mode is Edit, change to SiteCC
          custLayer = EDIT_LAYER;
        }
        else
        {
          //Mode is View, change to UserCC + SiteCC
          custLayer = VIEW_LAYER;
        }
    
        try
        {
          CustClassList custClassList = new CustClassList(custLayer);
          CustClassListMapping custClassListMapping =
            new CustClassListMapping("/", null, null, custClassList);
          custConfig = new CustConfig(new CustClassListMapping[]
            { custClassListMapping });
        }
        catch (Exception e)
        {
          e.printStackTrace();
    
        }
    if(defaultOptions.getServletContextAsObject() != null){ 
        return new SessionOptions(defaultSessionOptions.getIsolationLevel(),
                                  defaultSessionOptions.getLocale(), custConfig,
                                  defaultSessionOptions.getVersionContext(),
                                  defaultSessionOptions.getVersionCreatorName(),
                                  defaultSessionOptions.getCustomizationPolicy());
                                  sessionOptions.getServletContextAsObject());
      }
        else
        {
          return new SessionOptions(sessionOptions.getIsolationLevel(),
                                  sessionOptions.getLocale(), custConfig,
                                  sessionOptions.getVersionContext(),
                                  sessionOptions.getVersionCreatorName(),
                                  sessionOptions.getCustomizationPolicy());
        }
      }
    
      //Edit mode SiteCC
      private static final CustomizationClass[] EDIT_LAYER =
        new CustomizationClass[]
        { new SiteCC() };
    
      //View mode SiteCC + USerCC
      private static final CustomizationClass[] VIEW_LAYER =
        new CustomizationClass[]
        { new SiteCC(), new UserCC() };
    
    }
    

10.3.5 How to Register the Implementation with Oracle Composer

For the site and user customization layers to function, you must register the ComposerSessionOptionsFactory class with Oracle Composer. For example, if the concrete class is view.AppsSessionOptionsFactoryImpl, the following snippet must be added to the adf-config.xml file located in the \.adf\META-INF folder in your application directory:

<page-editor-config xmlns="http://xmlns.oracle.com/adf/pageeditor/config">
  <session-options-factory>view.AppsSessionOptionsFactoryImpl</session-options-factory>
</page-editor-config>

10.3.6 How to Configure WebCenterComposerFilter

You must configure the WebCenterComposerFilter filter in the web.xml file located in the ViewController\public_html\WEB-INF folder in your application directory. This filter registers Oracle Composer's concrete SessionOptionsFactory with the ADF for every HTTP request. When the filter receives a call from the ADF, it forwards the request to the WebCenter application and gets the SessionOptions with the new customized layer. If you have not set the Sandbox or VersionContext in the SessionOptions, then Oracle Composer sets its own Sandbox and returns it to the ADF. For more information on Sandbox, see Section 10.2.1, "How to Enable Oracle Composer Sandbox Creation." The composerFilter and its filter mapping must be configured after ServletADFFilter and before ADFBindingFilter. For example, see the following web.xml file:

....

  <filter>
    <filter-name>ServletADFFilter</filter-name>
    <filter-class>oracle.adf.share.http.ServletADFFilter</filter-class>
  </filter>
  <!-- WebCenterComposerFilter goes here -->
  <filter>
    <filter-name>composerFilter</filter-name>
  <filter-class>oracle.adf.view.page.editor.webapp.WebCenterComposerFilter</filter-class>
  </filter>
  <filter>
    <filter-name>adfBindings</filter-name>
    <filter-class>oracle.adf.model.servlet.ADFBindingFilter</filter-class>
  </filter>
.....
  <filter-mapping>
    <filter-name>ServletADFFilter</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>REQUEST</dispatcher>
  </filter-mapping>

  <!-- WebCenterComposerFilter mapping goes here -->
  <filter-mapping>
    <filter-name>composerFilter</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>REQUEST</dispatcher>
  </filter-mapping>
  <filter-mapping>
    <filter-name>adfBindings</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>REQUEST</dispatcher>
  </filter-mapping>
....

Note:

The order in which you define filters is important. Requests pass through these filters sequentially and if they are not defined in the correct order, the application will not run as designed. Your web.xml file must have the ServletADFFilter implementation first, followed by WebCenterComposerFilter and AdfBindingFilter implementations, in that order.

For information about the Oracle Composer-specific configurations you can make in web.xml, see Section B.2.3, "web.xml."

10.3.7 How to Redirect the Servlet to Enable Switch Between MDS Customization Layers

To redirect the servlet, that is, to refresh the full page at runtime, you must create:

  • The AppNavigationUtils class, which calls the AppNavigationUtils.redirectToSamePage() method

  • The AppCloseHandler CloseListener, which uses the AppNavigationUtils class

  • The AppModeBean, which displays Edit mode

This section describes how to create these objects. It contains the following subsections:

10.3.7.1 How to Create the AppNavigationUtils Class

To create the AppNavigationUtils class:

  1. From the File menu, choose New.

  2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.

    The Create Java Class dialog opens.

  3. In the Name field, enter AppNavigationUtils and click OK.

    The AppNavigationUtils.java file is rendered in the Source view.

  4. Import the following libraries:

    import javax.faces.context.FacesContext;
    import javax.servlet.http.HttpServletRequest;
    
  5. Add the following code:

    public class AppNavigationUtils
    {
    
      public static void redirectToSamePage()
      {
        HttpServletRequest request =
    (HttpServletRequest)FacesContext.getCurrentInstance().getExternalContext().getRequest();
        String url = request.getRequestURL().toString();
        String _adfCtrlState = request.getParameter("_adf.ctrl-state");
        url = url + "?_adf.ctrl-state="+ _adfCtrlState;
        System.out.println(url);
        try
        {
          FacesContext.getCurrentInstance().getExternalContext().redirect(url);
          FacesContext.getCurrentInstance().responseComplete();
        }
        catch(Exception e)
        {
          e.printStackTrace();
        }
      }
    }
    

10.3.7.2 How to Create AppCloseHandler

To create AppCloseHandler:

  1. From the File menu, choose New.

  2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.

    The Create Java Class dialog opens.

  3. In the Name field, enter AppCloseHandler and click OK.

    The AppCloseHandler.java file displays in the Source view.

  4. Import the following libraries:

    import oracle.adf.view.page.editor.event.CloseEvent;
    import oracle.adf.view.page.editor.event.CloseListener;
    
  5. Add the following code:

    public class AppCloseHandler
      implements CloseListener
    {
    
      public void processClose(CloseEvent closeEvent)
      {
        AppNavigationUtils.redirectToSamePage(); 
      }
    }
    

10.3.7.3 How to Register the AppCloseHandler

After creating AppCloseHandler, you must register it in the Oracle Composer extension file, pe_ext.xml.

To register the event handler:

  1. In the pe_ext.xml file, add the following entries:

    <event-handlers>
      <event-handler event="close">view.AppCloseHandler</event-handler>   
    </event-handlers>
    
  2. Save the file.

For more information about event handlers, see Section 8.4, "Configuring Event Handlers for Oracle Composer UI Events."

10.3.7.4 How to Create AppModeBean

To create AppModeBean:

  1. From the File menu, choose New.

  2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.

    The Create Java Class dialog opens.

  3. In the Name field, enter AppModeBean and click OK.

    The AppModeBean.java file displays in the Source view.

  4. Import the following libraries:

    import javax.faces.event.ActionEvent;import oracle.adf.view.page.editor.mode.ModeContext;
    
  5. Add the following code:

    public class AppModeBean
    {
    
      public void edit(ActionEvent actionEvent)
      {
        ModeContext.getCurrent().setEditMode();
        AppNavigationUtils.redirectToSamePage();
      }
    }
    

10.3.8 What Happens at Runtime

To see how the site customization layer functions, first run the JSF page in a browser. Then log in to the page as admin, and click the Edit link to switch to Edit mode. At runtime, customize the page. For example, drop a Web page, movable box, or an image onto the page. The page should look like Figure 10-4.

Figure 10-4 Customized Page

Description of Figure 10-4 follows
Description of "Figure 10-4 Customized Page"

Go to \mds\mdssys\cust\site\webcenter in your application directory, and open the pagename.jspx.xml file. This is where the site-level customizations that you made to the page are stored.

To use the user customization layer, log in to the page as scott and personalize the page in View mode. Then go to \mds\mdssys\cust\user\scott in your application directory, and open the pagename.jspx.xml file. This is where the user-level customizations (personalizations) that you made to the page are stored.

10.4 Troubleshooting MDS-Related Problems with Oracle Composer

This section provides information to assist you in troubleshooting MDS-related problems you may encounter while using Oracle Composer.

For information about configuring logging, see "Configuring ADF Logging for Oracle Composer".

Problem

Your application is configured to use MDS sandbox. When you run the application, the sandbox either does not work or generates exceptions.

Solution

Ensure the following:

  • A database repository is used. Sandbox works only with a database-based repository, and not with a file-based repository.

  • Ensure that the order of filters in web.xml is correct. The <filter> entries must be in the correct order for sandbox to work correctly.

For information, see Section 10.2, "Using Oracle Composer Sandbox."