Author: taylor Date: Mon Aug 14 20:18:42 2006 New Revision: 431506 URL: http://svn.apache.org/viewvc?rev=431506&view=rev Log: profiler documentation
http://issues.apache.org/jira/browse/JS2-573 Added: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/ portals/jetspeed-2/trunk/xdocs/guides/images/profiler/pages.jpg (with props) portals/jetspeed-2/trunk/xdocs/guides/images/profiler/parameter-resolution-2.jpg (with props) portals/jetspeed-2/trunk/xdocs/guides/images/profiler/parameter-resolution.jpg (with props) portals/jetspeed-2/trunk/xdocs/guides/images/profiler/profiler-pipeline.jpg (with props) portals/jetspeed-2/trunk/xdocs/guides/images/profiler/user-profile-locator.jpg (with props) Modified: portals/jetspeed-2/trunk/xdocs/guides/guide-profiler.xml Modified: portals/jetspeed-2/trunk/xdocs/guides/guide-profiler.xml URL: http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/guide-profiler.xml?rev=431506&r1=431505&r2=431506&view=diff ============================================================================== --- portals/jetspeed-2/trunk/xdocs/guides/guide-profiler.xml (original) +++ portals/jetspeed-2/trunk/xdocs/guides/guide-profiler.xml Mon Aug 14 20:18:42 2006 @@ -26,168 +26,567 @@ <section name="Profiler Overview"> <p> The Jetspeed Profiler is a portal resource location rule-based engine. -As of Jetspeed version 2.0, the profiler locates the following kinds of portal resources: +The profiler locates the following kinds of portal resources: <ul> <li>PSML pages</li> <li>Folders</li> <li>Menus</li> + <li>Links</li> </ul> -When a request is received by the portal, the profiler will map the request to a resource -based on a normalized set of runtime parameters and state such as request parameters, HTTP headers, -and session attributes. The Profiler is invoked during the Jetspeed request processing pipeline in -the profiler valve. This valve requires that the request context is already populated with -the portal request and response, capabilities, language and user information. -The runtime parameters make up the profile criterion which the profiler uses to locate -portal resources. +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. </p> -<p> -The profiler works hand in hand with the Site and Page Manager components. -The profiler takes runtime information as input, generalized that information -into +<p> +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. +<img src="images/profiler/profiler-pipeline.jpg" border="1"/> +</p> +<p> +All of these runtime parameters are called the <i>profile criterion</i>, which the profiler uses to locate +portal resources. </p> </section> -<section name="Profiling Rules"> +<section name="Located Portal Resources: Pages"> +<p> +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 <i>physical</i> representation of the portal site. +The Jetspeed team plans to also support <i>logical</i> views of the portal site in future releases. +</p> <p> - +Analogous to a file system, there is one physical root to the portal site. However, using the concept of <i>subsites</i>, +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: +<table> + <tr> + <th>Reserved Folder</th> + <th>Description</th> + </tr> + <tr> + <td>_user</td> + <td>holds all user-specific folders and pages</td> + </tr> + <tr> + <td>_role</td> + <td>holds all role-organized folders and pages</td> + </tr> + <tr> + <td>_group</td> + <td>holds all group-organized folders and pages</td> + </tr> + <tr> + <td>_subsite-root</td> + <td>contains complete subsite trees, exactly like root tree</td> + </tr> +</table> +<img src="images/profiler/pages.jpg" border="1"/> +</p> +<p>By applying profiling rules, the profiler locates pages in the portal site directory.</p> +</section> +<section name="Profiling Rules"> +<p> + 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 generically locate portal resources +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 rulusing a less-specific algorithm until the least +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. </p> -<subsection name='Rule Criterion'> +<subsection name='Rule Criteria'> <p> -RuleCriteria are templates for locating profile properties. -The default implementation has a profiling policy defined in this proposal based on resource-specific URLs, Mime-Types and language preferences. More complex implementations will need to use other inputs in mapping to resources such as Cookies, IP Address Ranges, Statistical Resource Usage Analysis, Business Rules inside of servlets or EJBs,... - +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: +<table> + <tr><td>Type</td> + <td>The type of criterion. Types are configured in the profiler spring configuraiton. + Each type maps to a <i>rule criterion resolver</i>. A resolver is a Java class which maps request input + to a normalized location instruction. Valid resolvers are provided in the table below. + </td> + </tr> + <tr> + <td>Fallback Order</td> + <td>The sequential in which to apply this criterion within the profiling rule.</td> + </tr> + <tr> + <td>Fallback Type</td> + <td>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: + <table> + <tr> + <td>FALLBACK_CONTINUE</td> + <td>evaluate this criterion and if it fails continue to the next criterion</td> + </tr> + <tr> + <td>FALLBACK_STOP</td> + <td>evaluate this criterion and if it fails stop evaluation criteria for this rule</td> + </tr> + <tr> + <td>FALLBACK_LOOP</td> + <td>evaluate this criterion and if it fails continue evaluating</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>Name</td> + <td>The unique name (per rule) of this criterion. Upon matches, the name is mapped to the profile locator property name.</td> + </tr> + <tr> + <td>Value</td> + <td>The default value (not required) to use for this criterion when resolution fails.</td> + </tr> +</table> +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. </p> </subsection> <subsection name='Rule Criterion Resolvers'> <p> - +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 <i>org.apache.jetspeed.profiler.rules.RuleCriterionResolver</i>. +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. +</p> +<p>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. <table> <tr> <th>Resolver</th> <th>Description</th> - <th>Example</th> </tr> <tr> <td>request</td> - <td>resolve by matching to a request parameter name</td> - <td></td> + <td>resolve by matching a request parameter by name, returning the request parameter value for a locator property taking the name of the criterion</td> </tr> <tr> <td>session</td> - <td>resolve by matching to a session attribute name</td> - <td></td> - </tr> + <td>resolve by matching a session attribute by name, returning the session attribute value for a locator property taking the name of the criterion</td> + </tr> <tr> <td>request.session</td> - <td>resolve by matching to a request attribute name first, then matching to a session attribute name</td> - <td></td> + <td>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</td> </tr> <tr> - <td>hard.coded</td> - <td>resolve with a hard.coded value</td> - <td></td> + <td>path</td> + <td>resolve by matching the PSML page <i>path</i> value of the current request. The path is typically the path and name of a page, such as <i>default-page</i> for a locator property named <quote>path</quote></td> </tr> <tr> - <td>group.role.user</td> - <td>fallback controller: search for resource under folders of the current users group, then role, then users own folder</td> - <td></td> - </tr> + <td>path.session</td> + <td>resolve by matching the PSML page <i>path</i> value of the current request. The path is typically the path and name of a page, such as <i>default-page</i>. 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 <quote>path</quote></td> + </tr> <tr> - <td>user</td> - <td>match resources in the current user directory</td> - <td></td> + <td>hard.coded</td> + <td>resolve to a hard.coded default value, for example, set a locator property named page to <quote>/my-account.psml</quote></td> </tr> <tr> - <td>group</td> - <td></td> - <td></td> + <td>user</td> + <td>resolve by matching the name of the current authenticated user. The username is mapped to a locator property named <quote>user</quote></td> </tr> <tr> <td>role</td> - <td></td> - <td></td> + <td>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 <quote>role</quote>. 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.</td> </tr> <tr> - <td>mediatype</td> - <td>match media type in the request context</td> - <td></td> - </tr> + <td>group</td> + <td>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 <quote>group</quote>. 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.</td> + </tr> <tr> - <td>country</td> - <td></td> - <td></td> + <td>rolecombo</td> + <td>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 <quote>role</quote>. 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.</td> </tr> <tr> - <td>user.agent</td> - <td></td> - <td></td> + <td>mediatype</td> + <td>resolve by matching the media type (HTML,XHTML,WML...) from the request context. Sets a locator property named <quote>mediatype</quote></td> </tr> <tr> <td>language</td> - <td></td> - <td></td> - </tr> + <td>resolve by matching the browser's language from the request context locale (originating from the HTML headers). Sets a locator property named <quote>language</quote></td> + </tr> <tr> - <td>roles</td> - <td>Role Fallback</td> - <td></td> - </tr> - <tr> - <td>path</td> - <td></td> - <td></td> - </tr> - <tr> - <td>page</td> - <td></td> - <td></td> + <td>country</td> + <td>resolve by matching the browser's country code from the request context locale (originating from the HTML headers). Sets a locator property named <quote>country</quote></td> </tr> <tr> - <td>path.session</td> - <td></td> - <td></td> - </tr> + <td>group.role.user</td> + <td>resolve by first matching on a request parameter named <quote>group</quote>. If that fails, resolve on a request parameter named <quote>role</quote>. If that fails, resolve by matching the name of the current authenticated user. The username is mapped to a locator property named <quote>user</quote></td> + </tr> <tr> <td>user.attribute</td> - <td></td> - <td></td> + <td>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</td> + </tr> + <tr> + <td>user.agent</td> + <td>resolve by matching the browser's (client) user agent from the request context device capabilities (originating from the HTML headers)</td> </tr> <tr> <td>navigation</td> - <td>change the current navigation path</td> - <td></td> + <td>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 <quote>/pages/freecontent</quote></td> + </tr> +</table> +<i>Note that all criteria will fall back to the default value when no match is made. Locator property expects a criterion named <quote>navigation</quote></i> +</p> +</subsection> +<subsection name='Default Rules'> +<p> +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. +</p> +<table> + <tr> + <th>Rule</th> + <th>Description</th> </tr> + <tr> + <td>j1</td> + <td> + <p>Implements the Jetspeed-1 hard-coded profiler fallback algorithm, resolving in a most-specific to least-specific algorithm:</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>country</td> + <td>country</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>language</td> + <td>language</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>mediatype</td> + <td>mediatype</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>group.role.user</td> + <td>user|group|role</td> + <td></td> + <td>stop</td> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>stop</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>role-fallback</td> + <td> + <p>A role based fallback algorithm, trying to find the most-specific resource by searching over all security roles for the current authenticated user.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>stop</td> + </tr> + <tr> + <td>role</td> + <td>role</td> + <td></td> + <td>continue</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>group-fallback</td> + <td> + <p>A group based fallback algorithm, trying to find the most-specific resource by searching over all security groups for the current authenticated user.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>stop</td> + </tr> + <tr> + <td>group</td> + <td>group</td> + <td></td> + <td>continue</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>j2</td> + <td> + <p>The default profiling rule for users and mediatype minus language and country.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>mediatype</td> + <td>mediatype</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>group.role.user</td> + <td>user|group|role</td> + <td></td> + <td>stop</td> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>stop</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>security</td> + <td> + <p>The security profiling rule needed to force credential change requirements.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>hard.coded</td> + <td>page</td> + <td>/my-account.psml</td> + <td>stop</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>path</td> + <td> + <p>Only criterion applied is the path portion of the portal URL.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path</td> + <td>page</td> + <td>/</td> + <td>stop</td> + </tr> + </table> + </td> + </tr> + <tr> + <td>user-role-fallback</td> + <td> + <p>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.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>continue</td> + </tr> + <tr> + <td>role</td> + <td>role</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>navigation</td> + <td>navigation</td> + <td>/</td> + <td>loop</td> + </tr> + <tr> + <td>user</td> + <td>user</td> + <td></td> + <td>continue</td> + </tr> + + </table> + </td> + </tr> + <tr> + <td>user-rolecombo-fallback</td> + <td> + <p>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 <quote>role</quote> that is the concatenation of all roles into one string, such as <i>role1-role2-role3</i>. This combined string is used as the role name in the locator.</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path.session</td> + <td>page</td> + <td>default-page</td> + <td>continue</td> + </tr> + <tr> + <td>rolecombo</td> + <td>role</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>navigation</td> + <td>navigation</td> + <td>/</td> + <td>loop</td> + </tr> + <tr> + <td>user</td> + <td>user</td> + <td></td> + <td>continue</td> + </tr> + + </table> + </td> + </tr> + <tr> + <td>subsite-role-fallback-home</td> + <td> + <p>A rule based on role fallback algorithm with specified subsite and home page</p> + <table> + <tr> + <th>criterion</th> + <th>name</th> + <th>value</th> + <th>fallback</th> + </tr> + <tr> + <td>path</td> + <td>path</td> + <td>subsite-default-page</td> + <td>stop</td> + </tr> + <tr> + <td>role</td> + <td>role</td> + <td></td> + <td>continue</td> + </tr> + <tr> + <td>navigation</td> + <td>navigation</td> + <td>subsite-root</td> + <td>loop</td> + </tr> + </table> + </td> + </tr> -</table> - -</p> -</subsection> -<subsection name='Principal Rules'> -</subsection> -</section> + </table> +</subsection> +</section> <section name="Profile Locators"> <p> Profile Locators are used to locate profiled portal resources such as -pages, documents, and fragments. A locator contains properties describing -the actually resource to be located. Since the locator is based on properties -that are usually related to a user or other subject's profile, it is referred -to as a profile locator. +pages, folders, menus and links. A locator contains a collection of properties +(name value pairs) describing the actual resource to be located. </p> -<subsection name='Profile Locator Paths'> +<img src="images/profiler/parameter-resolution.jpg" border="1"/> <p> -</p> -</subsection> +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. +</p> +<img src="images/profiler/parameter-resolution-2.jpg" border="1"/> </section> +<section name='Principal Rules'> +<p>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 <quote>menu</quote> or <quote>page</quote>. 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: +</p> +<p> +<img src="images/profiler/user-profile-locator.jpg" border="1"/> +</p> +<p> +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. +</p> +</section> <section name="Component Configuration"> <p> +The profiler.xml Spring configuration file configures the profiler component. +<table> + <tr> + <th>Constructor Argument</th> + <th>Description</th> + </tr> + <tr> + <td>(0) JETSPEED-INF/ojb/profiler_repository.xml</td> + <td>Holds the OJB database to POJO mapper for marshalling profile information to and from the persistent store.</td> + </tr> + <tr> + <td>(1) j1</td> + <td>The default profiling rule. If a user does not have a profiling rule defined in the association table, this profiling rule is used.</td> + </tr> + <tr> + <td>(2) ProfileResolvers (ref bean)</td> + <td>The map of profiler resolver names to implementing resolver classes. New resolvers should be added to the ProfileResolver table.</td> + </tr> +</table> </p> </section> Added: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/pages.jpg URL: http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/images/profiler/pages.jpg?rev=431506&view=auto ============================================================================== Binary file - no diff available. Propchange: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/pages.jpg ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/parameter-resolution-2.jpg URL: http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/images/profiler/parameter-resolution-2.jpg?rev=431506&view=auto ============================================================================== Binary file - no diff available. Propchange: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/parameter-resolution-2.jpg ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/parameter-resolution.jpg URL: http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/images/profiler/parameter-resolution.jpg?rev=431506&view=auto ============================================================================== Binary file - no diff available. Propchange: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/parameter-resolution.jpg ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/profiler-pipeline.jpg URL: http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/images/profiler/profiler-pipeline.jpg?rev=431506&view=auto ============================================================================== Binary file - no diff available. Propchange: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/profiler-pipeline.jpg ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/user-profile-locator.jpg URL: http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/images/profiler/user-profile-locator.jpg?rev=431506&view=auto ============================================================================== Binary file - no diff available. Propchange: portals/jetspeed-2/trunk/xdocs/guides/images/profiler/user-profile-locator.jpg ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
