Sun Java System Portal Server 7.1 Technical Reference

Chapter 17 Merge Semantics

This chapter contains the following sections

Introduction

The display profile is composed of a hierarchy of XML documents. The software can store a display profile document for the user, each role the user belongs to, and the user’s organization or suborganization. At runtime, the system merges these multiple display profile documents to deliver a particular portal desktop to the user. This process of merging display profile documents affects the final display profile by potentially changing channel, provider, and property definitions.

The display profile data format contains syntax that defines how these documents are combined. This definition is commonly known as merge semantics.

Merge semantics control how attributes are combined as display profile documents from different LDAP nodes (base DN, DN, and role DNs) which are merged to form a single representation (that is, Desktop). Merge semantics assume an ordering to display profile documents. The Sun Java System Portal Server 7.1 software imposes an additional ordering on Sun Java System Access Manager software roles to simulate a hierarchical structure.

The set of display profile documents for a user consists of: the documents that exist at the user’s LDAP organization and suborganization nodes; the documents that exist at each of the user’s role nodes; and the document that exists at the user’s entry node. Documents do not need to be defined at each of these nodes, but there must be at least one document defined at a node. The set of documents is sorted according to a priority value that the display profile document defines. See Display Profile Document Priorities for more information.

You can visualize the process of document merging as laying one display profile document on top of another. A merge happens where like named channels, providers, and properties fall on top of one another. Merging is based on the name of the display profile object, not the XML structure defined in the display profile document. Like named channels can exist in different containers within the containment hierarchy in the display profile to be merged.

For example, Figure 18–1 shows a sample DIT with each level having its own display profile document. At the top of the tree is the global display profile. Next is the base DN, dc=sesta,dc=com. It has a two role DNs, training and manager. The tree ends at the uid DN, user1. Each node in the DIT has its own display profile document. The resultant display profile document is produced through a merge of all the display profile documents, based on their priorities. This merge result is presented to the user at login. Merge semantics control how display profile documents are combined. These semantics include replace, remove, and fuse. Display profile objects can also be locked. During the merge, a higher priority document can lock a display profile object to prevent a lower priority document from altering it.

Figure 17–1 Example of Merge Process

Process of Merging

When a user logs in to the Portal Server 7.1 Desktop, and after authentication takes place, the system determines the user’s display profile by:

To Determine the User Display Profile:

Locating all the display profile documents for that user by searching through the global display profile, and LDAP organization, suborganization, role, and user nodes that the user belongs to.

Placing the retrieved display profile documents in a temporary area, which can be visualized as a bag.

Sorting the display profile documents in the bag based on priority, starting at the lowest priority. (The node at which the document was retrieved does not influence the priority sorting. Also, the user display profile document always has the highest priority.)

Taking the documents out of the bag, lowest priority first, then placing the next higher level priority document over this document, and applying merge and lock semantics.

Continuing Process of Merging until all the documents have been taken out of the bag so that the system returns a value to the user that is a merge of the objects found in the documents.

Types of Merge

This section explains the types of merge available to combine the display profile documents.

Overview

Display profile uses the following three types of merges to determine how to combine display profile documents:

replace

All the display profile objects defined in the higher priority document completely override the ones defined at the lower one. If the object does not exist in the lower priority document, it is added to the merge result (the object replaces the value in the merge results).

remove

The named object is removed from the merge up to this point (the object is removed from the merge results). It no longer exists in the display profile (but it can be re-introduced by another document to be merged). It can be redefined by a higher priority document.

fuse

The object from the lower priority document is combined with one from the higher priority document (the object is merged with the value in the merge results).

Note –

The exact meaning of each merge type depends on the display profile object they are applied to.

For channels and providers, fuse has special meaning. The channels themselves are not actually fused together. Rather, fuse indicates that the channel’s or provider’s properties should be combined. The replace semantic replaces the entire channel or provider, including all properties. The remove semantic removes the entire channel or provider from the merge up to that point.

The display profile <DisplayProfile> root node can also have merge semantics. The replace semantic means that all the DP objects defined in the higher priority document completely override the ones defined at the lower one. All merges up to that point are negated and the higher priority document is used as the new base for merging. The remove semantic indicates that all merge results up to the point of this document are to be discarded. The merge begins with the next display profile document found in the sorted set. As with channels and providers, the fuse semantic means that the contained objects (channels and providers) should be combined.

Atomic display profile properties (those that cannot contain other properties) cannot use the fuse semantic. This includes the String, Integer, Boolean, and Reference properties.

The set of properties for a channel consists of the channel’s properties plus the channel’s provider’s properties plus the channel’s parent’s properties, and so on. You can think of this total set of properties as the channel’s single document properties. An implication of document merging is that the total set of properties for a document consists of the set union of the channel’s single document properties for all documents in the user’s merge set.

Examples

This section provides examples for merge types such as remove, replace, and fuse.

Remove Example

This example uses the merge type remove to modify a container’s selected channel list.

The following example code shows how the merge sets of all users can consist of an organizational level document that contains the following display profile fragment.

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="UnixTipoftheDay"/>
    </Selected>
</Container>

The “unix tip of the day” describes ways to use UNIX. It is likely that users that belong to the admin role would not find this channel helpful. To remove this channel from everyone with the admin role, define the TemplateTableContainer channel in the admin role document as follows:

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Outages"/>
        <Reference value="SolarisAdmin"/>
        <Reference value="AdminTipoftheDay"/>
        <Reference value="UnixTipoftheDay" merge="remove"/>
    </Selected>
</Container>

The preceding sample snippet causes the <Reference value="UnixTipoftheDay"> to be removed from the admin role display profile.

Replace Example

This example uses the merge type replace to remove channel from all users’ display.

The following example shows how for a particular container, a role admin can ignore all of the channels defined in the organization level. The organization definition resembles the following:

<Container name=...>
    ...
    ...
    <Selected>
        <Reference name="X"/>
        <Reference name="Y"/>
        <Reference name="Z"/>
    </Selected>
</Container>

Because the role admin does not want any of the users under that role to have the X, Y, or Z channels, the container is defined as follows:

<Container name=...>
    ...
    ...
    <Selected merge="replace">
        <Reference name="A"/>
        <Reference name="B"/>
        <Reference name="C"/>
    </Selected>
</Container>

The selected list in the role document’s container replaces the selected list in the organization document’s container.

Fuse Example

This example uses the merge type fuse to create role-based channel list.

Use the fuse merge semantic to combine non-atomic display profile objects. These objects include Collection and the available or selected channel lists. Here, fuse indicates that all the properties contained in the non-atomic property should also be merged. Using fuse in this way enables the final non-atomic property presented to the user to be build up from various documents.

The following example display profile documents are for a user who belongs to the admin, employee, and movieFreak roles. The selected channels for the user appear at the end.

Example 17–1 Display Profile for the Admin Role

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Outages"/>
        <Reference value="SolarisAdmin"/>
        <Reference value="AdminTipoftheDay"/>
    </Selected>
</Container>

Display Profile for the Employee Role

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Benefits"/>
        <Reference value="EmployeeNews"/>
    </Selected>
</Container>

Display Profile for the movieFreak Role

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="NewMoviesReleases"/>
        <Reference value="MovieShowTimes"/>
    </Selected>
</Container>

The resultant list of selected channels for the user is as follows, with the available channel list ordered in the same way that the merging was applied, from lower to higher priority:

<Container name="JSPTableContainer" provider="JSPTableContainerProvider" merge="fuse">
    <Properties> ... </Properties>
    <Available> ... </Available>
    <Selected merge="fuse">
        <Reference value="Outages"/>
        <Reference value="SolarisAdmin"/>
        <Reference value="AdminTipoftheDay"/>
        <Reference value="Benefits"/>
        <Reference value="EmployeeNews"/>
        <Reference value="NewMoviesReleases"/>
        <Reference value="MovieShowTimes"/>
    </Selected>
</Container>

Merge Locking

Any display profile object that is able to be merged can also be locked. When an object is locked, it cannot be affected by merge semantics in higher priority documents. This enables low-priority documents to prevent a high-priority document from using the merge semantics to change particular aspects of the display profile.

Examples

Example 1

This example demonstrates how to use the merge lock feature to force property value for all users. The example shows how to ensure that for a particular organization, all users see the “employee news” channel. The users cannot remove this channel from their display. At the organization level document, the container channel’s selected list is defined as follows:

<Selected merge="fuse">
    ...
    <Reference value="EmployeeNews" lock="true"/>
    ...
</Selected>

Example 2

This example demonstrates how to use the merge lock feature to forcibly remove channel from all users’ display. The example shows how to force the “online games” channel to be removed. In this scenario, users have added this channel to the selected channels list in their user document, so simply removing it from the organization level document’s selected channel’s list will not work. Instead, the employee and organization lists will be merged together resulting in the “online games” channel being present. To forcibly remove the channel from all users under the organization, the selected channels list is defined as follows:

<Selected merge="fuse">
    ...
    <Reference value="OnlineGames" merge="remove" lock="true"/>
    ...
</Selected>

Here, the remove semantic removes the channel from merged result, and lock prevents lower priority documents from merging the value back in.