You can configure an application so that the value of the attributes listed in Table 52-1 can be persisted across sessions using the MDS repository. For example, if an application allowed persistence to the MDS repository, then a user could collapse the Payment Information box, as shown in Figure 52-2, and it would be collapsed the next time that user entered the application.

Along with the automatic persistence available through ADF Faces, you can create your own custom user customization capabilities for the following types of changes:

• Changing an attribute value

• Adding or removing a facet

• Adding or removing a child component

• Reordering child components

• Moving a child component to a different parent

If you want to create these types of custom user customizations, you need to add code (for example, in an event handler) that will call the APIs to handle the persistence.

Enabling an application to use the change persistence framework requires that you first enable your application to allow user customizations. Part of this process is determining where those changes should be persisted, either to the session or the MDS repository.

If you choose to persist changes to the session, by default all values as shown in Table 52-1 will be saved for the user's session. However if you choose to persist changes to a repository, you must explicitly configure which of these attribute values will be persisted to the repository. Instead of persisting all these attribute values, you can restrict changes so that only certain attribute value changes for a component are persisted, or so that only specific instances of the components persist changes.

For any applications that persist changes to an MDS repository, when you deploy your application, you must create a metadata archive (MAR) profile in the application's EAR assembly. See How to Create Deployment Profiles.

1. In the Applications window, double-click the web project in your application.
2. In the Project Properties dialog, select the ADF View node.
3. On the ADF View page, select the Enable User Customizations checkbox. If you want the changes to be persisted to only the session, select the For Duration of Session radio button. If you want the changes to persist to the MDS repository, select Across Sessions Using MDS.
4. If you choose to persist to the repository, you now need to declare each component tag and associated attribute values that you want persisted to the repository (if you choose to persist only to the session, all values will be persisted).

   For procedures to accomplish this task, see Configuring User Customizations. Once that configuration is complete, you can override those settings on a per component instance basis. For procedures, see Controlling User Customizations in Individual JSF Pages.

   Note:

   If you have created custom user customization capabilities as documented in Implementing Custom User Customizations, then you also need to declare those attribute values or operations.

When you elect to save changes only to the session, JDeveloper adds the CHANGE_PERSISTENCE context parameter to the web.xml file, and sets the value to session. This context parameter registers the ChangeManager class that will be used to handle persistence. If you instead elect to save the changes to the MDS repository, the value is set to oracle.adf.view.rich.change.FilteredPersistenceChangeManager, as shown in the following example.

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

When you elect to persist to the repository, JDeveloper also does the following:

• Adds the following JARs to the class path if they don't exist:

  • javatools-nodep.jar

  • facesconfigmodel.jar

  • taglib.jar

• Adds another context parameter to web.xml to register the MDSJSPProviderHelper class to handle merging MDS customization documents with the base JSP document, as shown in the following example.

  <context-param>
    <param-name>oracle.adf.jsp.provider.0</param-name>
    <param-value>oracle.mds.jsp.MDSJSPProviderHelper</param-value>
  </context-param>
  

• Adds the ADF Faces Change Manager Runtime 11 library to the project.

• In the adf-config.xml descriptor file, sets the persistent-change-manager element to the MDSDocumentChangeManager, which is the class that will be used to persist the changes. The following example shows the configuration for persisting to the MDS repository.

  <persistent-change-manager>
    <persistent-change-manager-class>
      oracle.adf.view.rich.change.MDSDocumentChangeManager
    </persistent-change-manager-class>
  </persistent-change-manager>
  

• Creates JSF JSP pages as XML documents. See Controlling User Customizations in Individual JSF Pages.

Additionally, when you elect to save the changes to the MDS repository, and you include facelets in your application, JDeveloper adds the faceletCache context parameter to the web.xml file. The value of this parameter is set to oracle.adfinternal.view.faces.facelets.rich.MDSFaceletCache, as shown in the following example.

<context-param>
  <param-name>com.sun.faces.faceletCache</param-name>

  <param-value>oracle.adfinternal.view.faces.facelets.rich.MDSFaceletCache</param-value>

</context-param>

The facelets cache enhances the performance of your application and the cache capacity can be configured in MDS on the server. See Managing the MDS Repository in Administering Oracle Fusion Middleware.

1. In the Application Resources panel, expand the Descriptors and ADF META-INF nodes, and then double-click adf-config.xml.
2. In the overview editor, click the View navigation tab.
3. In the View page, in the Tag Persistence section, in the Components table, select the component whose changes you want to persist (or not persist) to the repository.

   If the component does not appear in the table, click the Add icon to select and add it.

   Note:

   The filter rules specified in the adf-config.xml file are applicable only when you have chosen to persist to the MDS repository (see How to Enable User Customizations). These rules do not apply for persistence within session scope.

   If persistence fails for any reason (for example if one of the filter rules fails or there are MDS repository errors), then the values will be stored only within the session scope.

   The Attributes table displays all the attributes for the selected component whose values can be persisted.

4. In the Attributes table, select Persist Changes for each of the attributes whose values you want persisted. Deselect any if you do not want the values persisted.

When you select the component tags and attribute values to be persisted in the adf-config.xml file, JDeveloper enters tag library information for the components and attributes that are to be persisted. The following example shows the entry for persisting the value of the disclosed attribute on the panelBox component.

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

When an application is configured to persist changes to the session, any changes made during the session are recorded in a session variable in a data structure that is indexed according to the view ID and the component's ID attribute value. Every time the page is requested, in the subsequent create View or Restore View phase, all changes are applied in the same order as they were added. This means that the changes registered through the session will be applied only during subsequent requests in the same session.

When an application is configured to persist changes to the MDS repository, any changes made during the session are recorded by mutating the Document Object Model that MDS maintains for the JSP document behind the view. A JSF phase listener registered by ADF controller triggers a commit on the MDS session during the appropriate lifecycle phase, resulting in the change document being persisted in the MDS store. Every time the page is requested, Oracle's JSP engine seeks the JSP document from an MDS JSP provider, which provides a flattened document after merging the stored changes to the base document. MDS records the change against the unique value of the component's ID attribute.

Additionally, be aware that when you run the application from JDeveloper in the Integrated WebLogic Server, MDS creates a local file-based repository to persist metadata customizations. In contrast, when the application is deployed to a test or production environment, customizations are persisted to the configured MDS repository. For more information about MDS repository configuration, see the Administering Oracle Fusion Middleware. For more information about deploying an application, see Deploying the Application.

How changes are persisted for components on templates or regions is handled differently, depending on whether the changes are persisted to the session or to the MDS repository. With session persistence, changes are recorded and restored on components against the viewId for the given session. As a result, when the change is applied on a component that belongs to a region or page template, that change is applicable only in scope of the page that uses the region or template. It does not span all pages that consume the region or template.For example, suppose you have pageOne.jspx and pageTwo.jspx, and they both contain the region defined in region.jsff, which in turn contains a showDetail component. When pageOne.jspx is rendered and the disclosed attribute on the showDetail component changes, the implicit attribute change is recorded and will be applied only for pageOne.jspx. If the user navigates to pageTwo.jspx, no attribute change is applied.

When you persist changes to the MDS repository, MDS records and restores customizations for a document identified by a combination of the JSP page path and customization name/value configuration setting as set on the customization class (for more information, see Customization Classes). As a result, for a given page that is rendered, when MDS applies a change on a component within a region or template, it is applicable for all pages that consume the region or template and that have the same customization name and value as the source page.

In the previous example, assume that the showDetail component uses the ID of myShowDetail. When pageOne.jspx is rendered and the disclosed attribute on the showDetail component changes, the attribute change is recorded for region.jsff (and not the page that consumes it). This change is applied when any page that contains the region is rendered, as long as the ID remains the same.

To better understand what you need to do to create custom user customizations, it may help to have a deeper understanding of the change persistence and MDS frameworks. When you elect to persist changes to the MDS repository, the change persistence framework works in conjunction with the MDS framework. Where and how the customizations are saved are determined by how you set up your MDS repository, your customization layers, and your customization classes. Details about the MDS framework and the repository and how to use it are covered in Customizing Applications with MDS .

The change persistence framework uses the underlying change manager classes from Apache MyFaces Trinidad (in the org.apache.myfaces.trinidad.change package) along with a few ADF Faces-specific classes (in the oracle.adf.view.rich.change package). The instance of the registered ChangeManager class is accessible through the RequestContext object. It is responsible for gathering changes as they are created and added during a request, and then persisting them. The SessionChangeManager class is an implementation of ChangeManager which handles persistence within a session only, while the MDSDocumentChangeManager class is an implementation that persists to the MDS repository only. The FilteredPersistenceChangeManager class is an implementation of ChangeManager that stores the changes that pass the filter rules into the repository using the registered persistence change manager. Any change that does not get persisted to the repository will be persisted to the session when FilteredPersistenceChangeManager is used.

Additional classes are used to describe the changes to a component. You use these APIs to handle persisting any changes to components other than the implicit value changes the ADF Faces framework provides (as shown in Table 52-1). ComponentChange is the base class for all classes used to implement specific changes that act on the JSF component hierarchy, such as adding or removing a facet or a child component. These changes are automatically applied during subsequent creation of the view, in the same order in which they were added. Classes that extend the ComponentChange class and that also implement the DocumentChange interface can directly persist changes to the MDS repository. Classes that do not implement the DocumentChange interface can persist changes only to the session.

Table 52-2 describes the specialized classes that handle specific customizations. If "yes" appears in the Repository column, then the class implements the DocumentChange interface and it can persist changes to the MDS repository.

Aside from a ChangeManager class, you may also need to implement and register the DocumentChangeFactory interface with the ChangeManager class. If the DocumentChangeFactory implementation can provide an equivalent DocumentChange for a ComponentChange, the ChangeManager will use it to persist the DocumentChange to the repository.

1. Create a managed bean for the page that contains the component, as described in Using a Managed Bean in a Fusion Web Application.

   For more information regarding managed beans and how they are used as backing beans for JSF pages, see the "Creating and Using Managed Beans" section in Developing Web User Interfaces with Oracle ADF Faces.

2. Add code to the event handler method for the component that will be used to make the change. This code should obtain the component that contains the change. It should then use the component and the appropriate APIs to create, record, and persist the change.

   The following example shows the code on the action event handler for a command button for a change that will be persisted to the MDS repository. When a user clicks the button, that source graphic file changes. The event handler method accesses the component and changes the source attribute for the graphic. It then calls the private addAttributeChange method, which first uses the component API to record the change, and then uses the AttributeComponentChange class to set the new source attribute value.

   public void modifyObjectImage(ActionEvent event) {
          UIComponent uic = event.getComponent().findComponent("oi1");
          String source = "/images/mediumAd.gif";
          uic.getAttributes().put("source", source);
          _addAttributeChange(uic, "source", source);
       }
   . . .
   private static void _addAttributeChange(UIComponent uic, String attribName, 
                                               Object attribValue) {
          FacesContext fc = FacesContext.getCurrentInstance();
          ChangeManager cm = 
               RequestContext.getCurrentInstance().getChangeManager();
          ComponentChange cc = 
               new AttributeComponentChange(attribName, attribValue);
          cm.addComponentChange(fc, uic, cc);
       }
   

   Note:

   When you persist changes, in addition to explicitly recording a change on the component (which is done in the example above using uic.getAttributes().put("source", source) method), you must also directly apply the change using the component API, as was done using the private _addAttributeChange(uic, "source", source) method. Applying the change in this way allows the user to see the change in response to the same request. If the change is recorded on the component, then the change will not be seen until a subsequent request.

   Additionally, if you know that the component will always persist to the repository regardless of any restricted change persistence settings, you can instead call the AdfFacesContext.getCurrentInstance(). getPersistentChangeManager() method.

3. The ChangeManager class provides support for automatically converting an AttributeComponentChange into an AttributeDocumentChange, thereby allowing persistence to a repository. However, if you need to convert another type of change and you use a specialized change manager class that does not implement the DocumentChange class, you need to create a custom DocumentFactory implementation that converts the component change to a document change.

   Note:

   Automatic conversion of AttributeComponentChange into an AttributeDocumentChange assumes that the component attribute is represented as an attribute of the same name on the associated element in the JSPX document.

   Only those attribute values that are expressible in the JSPX document can be persisted using AttributeDocumentChange. In other words, CharSequence, Number, Boolean and ValueExpression are the only supported data types.

   Only values that implement java.io.Serializable can be persisted using AttributeComponentChange.

4. If you create a custom DocumentFactory implementation, you need to register it with the appropriate change manager class using the following method in your bean:

   public static void registerDocumentFactory(String targetClassName, 
                                              String converterClassName)
   

   Where targetClassName is the name of the ComponentChange class and converterClassName is the name of your DocumentChangeFactory extension that is capable of converting the target ComponentChange into a DocumentChange. The semantics of name for these classes is same as that of getName() in the java.lang.Class class.

5. If the class you use to create the component change adds a child that has a subtree of components, and you want to persist the changes to the repository, you must create a DocumentFragment to represent the change.

   The following example shows how to use the AddComponentDocumentChange specialized class to create a DocumentChange object and use a DocumentFragment to represent the change.

   public void appendChildToDocument(ActionEvent event)
   {
     UIComponent eventSource = event.getComponent();
     UIComponent uic = eventSource.findComponent("pg1");
     // only allow the image to be added once
     if (_findChildById(uic,"oi3") != null)
       return;
     FacesContext fc = FacesContext.getCurrentInstance();
     DocumentFragment imageFragment = _createDocumentFragment(_IMAGE_MARK_UP);
     DocumentChange change = new AddChildDocumentChange(imageFragment);
     ChangeManager apm = RequestContext.getCurrentInstance().getChangeManager();
     apm.addDocumentChange(fc, uic, change);
   }
    private static final String _IMAGE_MARK_UP =
    "<af:objectImage id='oi3' height='100' width='120' " +
        "source='http://www.somewhere.com/someimage.jpg' " +
        "xmlns:af='http://xmlns.oracle.com/adf/faces'/>";
    
   private static DocumentFragment _createDocumentFragment(
       String markUp)
   {
    // prepend XML declaration
     markUp = "<?xml version = '1.0' encoding = 'ISO-8859-1'?>" + markUp;
     DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
     factory.setNamespaceAware(true);
     factory.setValidating(false);
     DocumentBuilder builder;
     try
     {
       builder = factory.newDocumentBuilder();
     }
     catch (ParserConfigurationException pce)
     {
       _LOG.log(Level.WARNING, "Unable to get XML Parser:", pce);
        return null;
     }
     try
     {
       // use a version explicitly with ISO-8859-1 instead
       byte[] markupBytes = markUp.getBytes();
       Document newDoc = builder.parse(new ByteArrayInputStream(markupBytes));
       DocumentFragment fragment = newDoc.createDocumentFragment();
       // add the document's root element to the fragment
       fragment.appendChild(newDoc.getDocumentElement());
       return fragment;
     }
     catch (SAXException se)
     {
       _LOG.log(Level.WARNING, "Unable to parse markup:" + markUp, se);
       return null;
     }
     catch (IOException ioe)
     {
       _LOG.log(Level.WARNING, "IO Problem with markup:" + markUp, ioe);
       return null;
     }
   }
   

6. Register the user customizations in the adf-config.xml file, as documented in Configuring User Customizations. If the custom changes are of any type other than AttributeDocumentChange, you will need to manually edit the adf-config.xml file and indicate that all changes are allowed for the component, as shown in the following example.

   <tag name="inputText">
     <attribute name="label">
       <persist-changes>true</persist-changes>
     </attribute>
     <persist-operations>ALL</persist-operations>
   </tag>
   

1. In the Applications window, double-click the custom component class Java file.
2. Add code to the broadcast method that will use the specialized class to create a new ComponentChange object and then call the ChangeManager to add the change.

   The following example shows the code added to the UIXShowDetail class that persists a change to the disclosed attribute. In this case, the AttributeComponentChange class is used.

   public class UIXShowDetail extends UIXComponentBase
   {
     ...
     public void broadcast(FacesEvent event) throws AbortProcessingException
     {
       super.broadcast(event);
       ...
       if (event instanceof DisclosureEvent)
       {
         boolean isDisclosed = ((DisclosureEvent) event).isExpanded();
         setDisclosed(isDisclosed);
         //Record a Change for 'disclosed' attribute
         AttributeComponentChange aa =
          new AttributeComponentChange('disclosed', isDisclosed ? Boolean.TRUE : Boolean.FALSE);
         AdfFacesContext adfContext = AdfFacesContext.getCurrentInstance();
         adfContext.getChangeManager().addComponentChange(getFacesContext(), this, aa);
         ...
       }
     }
     ...
   

1. In the Applications window, double-click the custom component's render class Java file.
2. Use the findTypeConstants method, which takes a ClientMetadata instance and use the addPersistedProperty method to mark certain properties as persisted. The following example shows code from the renderer class used for the ADF Faces PanelSplitter component, which implicitly persists the splitterPosition attribute value.

   // Code from PanelSplitterRenderer.java  
   protected void findTypeConstants(
       FacesBean.Type type,
       ClientMetadata metadata)
     {
       super.findTypeConstants(type, metadata);
       metadata.addRequiredProperty(
         _orientationKey = type.findKey("orientation"));
       metadata.addRequiredProperty(
         _positionedFromEndKey = type.findKey("positionedFromEnd"));
       metadata.addRequiredProperty(
         _disabledKey = type.findKey("disabled"));
       metadata.addRequiredProperty(
         _splitterPositionKey = type.findKey("splitterPosition"));
       metadata.addPersistedProperty(_splitterPositionKey);
     }
   

3. In the JavaScript component peer class, define the attribute value to be persisted, using the setProperty function. This function needs to be invoked with the attribute name (as defined in the renderer in the previous step), the value, and "true", meaning the value of the attribute will be set. The following example shows code from the panelSplitter class that sets the splitter position.

   // Code from AdfDhtmlPanelSplitterPeer.js file where we set the
      splitter position
   
     var component = this.getComponent();
    component.setProperty("splitterPosition",position, true);
   // position is the value to be set