The Jetspeed Profiler is a portal resource location rule-based engine. The profiler locates the following kinds of portal resources:
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.
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.
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.
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:
|
||||||
| 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. |
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 |
navigation
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:
|
||||||||||||||||||||||||
| 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.
|
||||||||||||||||||||||||
| 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.
|
||||||||||||||||||||||||
| j2 | The default profiling rule for users and mediatype minus language and country.
|
||||||||||||||||||||||||
| security | The security profiling rule needed to force credential change requirements.
|
||||||||||||||||||||||||
| path | Only criterion applied is the path portion of the portal URL.
|
||||||||||||||||||||||||
| 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.
|
||||||||||||||||||||||||
| 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
|
||||||||||||||||||||||||
| subsite-role-fallback-home | A rule based on role fallback algorithm with specified subsite and home page
|
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.
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.