Profiler Overview

The Jetspeed Profiler is a portal resource location rule-based engine. The profiler locates the following kinds of portal resources:

  • PSML pages
  • Folders
  • Menus
  • Links
When a request is received by the portal, the profiler will compute a normalized instruction set, known as a profile locator. The locator is then added to the request context, from which subsequent components on the Jetspeed pipeline, most notably the Page Manager and Portal Site components, can take the profile locator and use it to find a requested resource. For example, the Page Manager uses the locator to find a page or folder. The Portal Site component uses the locator build the options on a menu.

The profile locator is the output from the profiler. The input is a normalized set of runtime parameters and state. The profiler input is defined in profiling rules, and can be made of any Java class available on the pipeline. Jetspeed comes with quite a few predefined rules for taking criteria from request parameters, HTTP headers, security information, language and session attributes. The profiler is invoked during the Jetspeed request processing pipeline in the profiler valve.

All of these runtime parameters are called the profile criterion, which the profiler uses to locate portal resources.

Located Portal Resources: Pages

The Profiler searches over a directory tree of PSML pages trying to locate a PSML page to be displayed. By default, this directory structure is found under WEB-INF/pages. The pages directory can also be stored in the database. This directory structure, comprised of portal resources (pages, folders, menus, links), is a physical representation of the portal site. The Jetspeed team plans to also support logical views of the portal site in future releases.

Analogous to a file system, there is one physical root to the portal site. However, using the concept of subsites, the Jetspeed site can support entire subsites that are not visible to other subsites, or the main site. There are several reserved (system) directories standardized by the profiler:

Reserved Folder Description
_user holds all user-specific folders and pages
_role holds all role-organized folders and pages
_group holds all group-organized folders and pages
_subsite-root contains complete subsite trees, exactly like root tree

By applying profiling rules, the profiler locates pages in the portal site directory.

Profiling Rules

A ProfilingRule defines a list of criteria used when evaluating a request to determine the location of a specific resource. Profiling rules are used by the profiler to locate portal resources based on the decoupled criteria for known portlet request data. A rule consists of an ordered list of criteria which should be applied in a given order. Following this rule's order, the profiling engine applies each criteria of the rule using a less-specific algorithm until the least specific resource criterion is considered. When all criteria are exhausted, the rule will fail and a fallback resource will be required.

Rule Criteria

A Rule Criterion specifies one criterion in a list of profiling rule criteria. The rule is used to build a normalized profiling locator and then locate a portal resource based on the current user request. Rule Criteria are templates for locating profile properties. Criteria consist of:

Type The type of criterion. Types are configured in the profiler spring configuraiton. Each type maps to a rule criterion resolver. A resolver is a Java class which maps request input to a normalized location instruction. Valid resolvers are provided in the table below.
Fallback Order The sequential in which to apply this criterion within the profiling rule.
Fallback Type After evaluation this criterion, the rule can either continue processing the remaining criteria, or stop processing. The fallback type determines how to continue processing. Valid values are:
FALLBACK_CONTINUE evaluate this criterion and if it fails continue to the next criterion
FALLBACK_STOP evaluate this criterion and if it fails stop evaluation criteria for this rule
FALLBACK_LOOP evaluate this criterion and if it fails continue evaluating
Name The unique name (per rule) of this criterion. Upon matches, the name is mapped to the profile locator property name.
Value The default value (not required) to use for this criterion when resolution fails.
More complex implementations will need to use other inputs in mapping to resources such as Cookies, IP Address Ranges, Statistical Resource Usage Analysis, or Business Rules.

Rule Criterion Resolvers

The table below displays all default rule criterion resolvers available with Jetspeed out of the box. Resolvers are Java classes, implementing the interface from the Jetspeed API org.apache.jetspeed.profiler.rules.RuleCriterionResolver. You may use this default set of resolvers to build your own profiling rules. Rules are currently stored in the Jetspeed database. Portal administrators may edit the rules using an administrative portlet. In the demo system, login as the user "admin" to see an example of the Jetspeed Profiler Administration portlet.

Additionally, you may add your own resolvers to Jetspeed. You will need to create a jar file holding your custom resolvers, and then drop them into the Jetspeed webapp's class path. Resolvers will need to be given a unique name. This is done by modifying the profiler.xml in the Spring assembly. See the section below on configuration to see where to add a resolver to the Spring configuration.

Resolver Description
request resolve by matching a request parameter by name, returning the request parameter value for a locator property taking the name of the criterion
session resolve by matching a session attribute by name, returning the session attribute value for a locator property taking the name of the criterion
request.session resolve by first matching a request parameter by name. If not matched, try matching a session attribute name, returning the request parameter or session attribute value for a locator property taking the name of the criterion
path resolve by matching the PSML page path value of the current request. The path is typically the path and name of a page, such as default-page for a locator property named path
path.session resolve by matching the PSML page path value of the current request. The path is typically the path and name of a page, such as default-page. If fails to find a valid path in the request, will then look in the session for the page value. The locator property will be named path
hard.coded resolve to a hard.coded default value, for example, set a locator property named page to /my-account.psml
user resolve by matching the name of the current authenticated user. The username is mapped to a locator property named user
role resolve by matching all of the security roles of the current authenticated user (in the JAAS Subject of the request context) and putting them in a comma-separated list. The locator property should be named role. The role criterion is often used in combination with path criteria, to create a role-fallback rule that searches over all security roles for a given user.
group resolve by matching all of the groups of the current authenticated user (in the JAAS Subject of the request context) and putting them in a comma-separated list. The locator property should be named group. The group criteion is often used in combination with path criteria, to create a group-fallback rule that searches over all security groups for a given user.
rolecombo resolve by matching all of the security roles of the current authenticated user (in the JAAS Subject of the request context) and putting them in a dash-separated string, for example: (role1-role2-role3). The locator property should be named role. The role criterion is often used in combination with path criteria, to create a role-fallback rule that searches over all security roles for a given user.
mediatype resolve by matching the media type (HTML,XHTML,WML...) from the request context. Sets a locator property named mediatype
language resolve by matching the browser's language from the request context locale (originating from the HTML headers). Sets a locator property named language
country resolve by matching the browser's country code from the request context locale (originating from the HTML headers). Sets a locator property named country
group.role.user resolve by first matching on a request parameter named group. If that fails, resolve on a request parameter named role. If that fails, resolve by matching the name of the current authenticated user. The username is mapped to a locator property named user
user.attribute resolve by matching a Portlet API User Attribute by name, returning the user attribute value for a locator property taking the name of the criterion
user.agent resolve by matching the browser's (client) user agent from the request context device capabilities (originating from the HTML headers)
hostname resolve by matching the host name from the server name in the request, returning the host name
domain resolve by matching the domain from the server name in the request, returning the domain
navigation A directive to changes the current navigation path during a profile location resolution performed by the page manager. The value can be the location of a folder, for example /pages/freecontent
Note that all criteria will fall back to the default value when no match is made. Locator property expects a criterion named navigation

Default Rules

Several rules are provided by default with the Jetspeed system. The rules in the table below display the criterion in a most-specific to least-specific ordering.

Rule Description
j1

Implements the Jetspeed-1 hard-coded profiler fallback algorithm, resolving in a most-specific to least-specific algorithm:

criterion name value fallback
country country continue
language language continue
mediatype mediatype continue
group.role.user user|group|role stop
path.session page default-page stop
role-fallback

A role based fallback algorithm, trying to find the most-specific resource by searching over all security roles for the current authenticated user.

criterion name value fallback
path.session page default-page stop
role role continue
group-fallback

A group based fallback algorithm, trying to find the most-specific resource by searching over all security groups for the current authenticated user.

criterion name value fallback
path.session page default-page stop
group group continue
j2

The default profiling rule for users and mediatype minus language and country.

criterion name value fallback
mediatype mediatype continue
group.role.user user|group|role stop
path.session page default-page stop
security

The security profiling rule needed to force credential change requirements.

criterion name value fallback
hard.coded page /my-account.psml stop
path

Only criterion applied is the path portion of the portal URL.

criterion name value fallback
path page / stop
user-role-fallback

Rule will first look for the resource in the user's home folder. If not found there, a role based fallback algorithm is applied, trying to find the most-specific resource by searching over all security roles for the current authenticated user.

criterion name value fallback
path.session page default-page continue
role role continue
navigation navigation / loop
user user continue
user-rolecombo-fallback

Rule will first look for the resource in the user's home folder. If not found there, a role based fallback algorithm is applied, trying to find the most-specific resource by searching over all security roles for the current authenticated user. Creates a locater property named role that is the concatenation of all roles into one string, such as role1-role2-role3. This combined string is used as the role name in the locator.

criterion name value fallback
path.session page default-page continue
rolecombo role continue
navigation navigation / loop
user user continue
subsite-role-fallback-home

A rule based on role fallback algorithm with specified subsite and home page

criterion name value fallback
path path subsite-default-page stop
role role continue
navigation navigation subsite-root loop

Profile Locators

Profile Locators are used to locate profiled portal resources such as pages, folders, menus and links. A locator contains a collection of properties (name value pairs) describing the actual resource to be located.

The profiler takes runtime information as input, generalized into generalized profile locators that are passed on to the page manager to locate a page or menu. The profile locators are normalized and not coupled to the profiler or page manager implementation.

Principal Rules

Each user principal can be mapped to specific profiling rule. This association is stored in the Jetspeed database. The association is three-way, combining the PRINCIPAL + PROFILING RULE + LOCATOR, where the locator values currently supported are menu or page. Thus we can have two different profiling rules applied for locating resources per user: locate pages and locate menus. When the profiler attempts to locate a page for the current user, it will apply the profiling rule for the given user. The Jetspeed User Administration portlet has a tab for editing user profile information:

Often, profiling rules are determined and then associated by portal-specific logic during user registration (or self-registration). A Jetspeed-specific self-registration portlet could handle the registration process of adding a user to the system, granting roles, setting user attributes, and assigning the profiling rule for the user.