You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jetspeed-dev@portals.apache.org by at...@apache.org on 2007/03/04 03:13:24 UTC
svn commit: r514329 [4/7] - in /portals/jetspeed-2/trunk/xdocs: ./ guides/
style/
Modified: portals/jetspeed-2/trunk/xdocs/guides/guide-portal-design.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/guide-portal-design.xml?view=diff&rev=514329&r1=514328&r2=514329
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-portal-design.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-portal-design.xml Sat Mar 3 18:13:22 2007
@@ -1,174 +1,174 @@
-<?xml version="1.0"?>
-<!--
-Copyright 2004 The Apache Software Foundation
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
--->
-<document>
- <properties>
- <title>Guide to Portal Design</title>
- <subtitle>Documentation for Designers working with Jetspeed Portal Design</subtitle>
- <authors>
- <person name="David Sean Taylor" email="taylor@apache.org"/>
- </authors>
- </properties>
- <body>
-<section name="Portal Design Introduction">
-<p>
-The Java Portlet API (JSR-168) defines the Java standard interface for programming portlets.
-The Java Portlet API specification enables interoperability between Portlets and Portals.
-It is the standard specification for developing Java portlets. However the Java Portlet API
-does not define standards for laying out and aggregating portlets and markup on a page.
-The documentation here under "Portal Design" covers:
-<ul>
- <li><a href='guide-psml.html'>Page Aggregation - see the section on PSML</a></li>
- <li><a href='guide-decorators.html'>Page and Portlet Decorators</a></li>
- <li><a href='guide-layouts.html'>Page Layouts</a></li>
- <li><a href='guide-jpt.html'>The Jetspeed Power Tool</a></li>
- <li><a href='guide-site.html'>The Site Content Model</a></li>
- <li><a href='#Template Locators'>Template Locators</a></li>
- <li><a href='#Terminology'>Terminology</a></li>
-</ul>
-</p>
-</section>
-<section name='Templates'>
-<p>
-Rendering one or more portlets into a portlet page is largely made up of the process of aggregating
-portlets as dynamic content with templates. Jetspeed-2 makes use of Velocity templates in
-creating a page layout. Although the Jetspeed-2 architecture fully supports the use of JSP templates for
-decorators and layouts, the developers thus far have chosen Velocity as the tool of choice for writing
-templates. There are two types of templates in Jetspeed: layouts and decorators.
-The process of rendering a page is the combined aggregation of a layout template,
-a page decorator template, a PSML definition, and one or more portlet decorator templates.
-</p>
-<subsection name='Layout Templates'>
-<p>
-Layout templates are packaged in special Jetspeed-specific and deployable portlet applications.
-Layout templates control the overall aggregation of a portal page. Layout templates are
-combined with portlets, providing a component model for aggregation. Jetspeed-2 comes out
-of the box with several layout components including one, two and three column layouts.
-See the <a href='layouts.html'>Layout Documentation</a> for all available Layouts in the
-default Jetspeed-2 system. Of course you can define and derive your own layouts.
-</p>
-</subsection>
-<subsection name='Decorators'>
- <p>
-Decorator templates are packaged in special Jetspeed-specific and deployable archives.
-Layout templates control the overall aggregation of a portal page. Layout templates are
-combined with portlets, providing a component model for aggregation. Jetspeed-2 comes out
-of the box with several layout components including one, two and three column layouts.
-See the <a href='guide-decorators.html'>Decorator Documentation</a> for all available Layouts in the
-default Jetspeed-2 system. Of course you can define and derive your own layouts.
-</p>
-</subsection>
-</section>
-<section name='Template Locators'>
-<p>
-Templates are located by the Jetspeed Template (and Decorator) Locator Component. These components
-locates templates using a normalized name/value pair URL scheme.
-using this scheme in what is called a 'normalized' URL to either a decorator or layout.
-However, templating engines such as Velocity need to work with templates using paths to templates that are
-relative of a document root. The <a href='guide-jpt.html'>Jetspeed Power Tool</a> facilitates conversion between normalized
-and relative paths. Typically in the Spring configuration, the template root of all decorators is defined as:
-<source test=""><![CDATA[
-${applicationRoot}/WEB-INF/decorations
-]]></source>
-and the root of all layouts (per portlet application) is defined as:
-<source test=""><![CDATA[
-${applicationRoot}/WEB-INF/templates
-]]></source>
-The Normalized Path is defined with named pair values. Examples:
-<source test=""><![CDATA[
-type/layout/media-type/html/name/tigris/decorator.vm
-type/decorator/media-type/html/language/en/country/US/name/metal/decorator.vm
-]]></source>
-<table>
- <tr>
- <th>Name</th>
- <th>Value</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>type</td>
- <td>layout | portlet | generic</td>
- <td>The type of template locator. Expected to be either one of the following values
- <b>layout</b>, <b>portlet</b> (decorator) or <b>generic</b> (decorator). Layouts can be for either page layouts
- or decorators. Generic type decorators can be used
- for either portlets or page decorations.</td>
- </tr>
- <tr>
- <td>media-type</td>
- <td>html | wml | dhtml | ...</td>
- <td>The markup media type to be located. Should be a valid media type (html, dhtml, wml...)</td>
- </tr>
- <tr>
- <td>name</td>
- <td>A valid decorator or layout name</td>
- <td>The name of the decorator or layout. Usually corresponds to a
- sub-directory holding the decorator or layout templates, images and stylesheets.</td>
- </tr>
- <tr>
- <td>language</td>
- <td>A valid ISO-639 standard two-character language abbreviation</td>
- <td>ISO-639 (http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt) defines a standard for language abbreviations.
- Typical abbreviations are en for english, fr for french, de for German, ...</td>
- </tr>
- <tr>
- <td>country</td>
- <td>A valid ISO-3166 standard two-character country code abbreviation</td>
- <td>ISO-3166 (http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html) defines a standard for country code abbreviations.
- Typical abbreviations are US for United States, FR for France, ...</td>
- </tr>
-
-</table>
-
-</p>
-</section>
-
-<section name='Terminology'>
-<table>
- <tr>
- <th>
- Term
- </th>
- <th>
- Definition
- </th>
- </tr>
- <tr>
- <td>
- Layout
- </td>
- <td>
-Defines the fashion in which grouping of Fragments
-will organized relative to the final, aggregated
-content of a request to the portal. Layouts are defined by
-a portlet which applies an algorithm to a template to
-generate the aggregated content of a page. Typical
-algorithms are two column, three column, nested.
- </td>
- </tr>
- <tr>
- <td>
- TODO: left off here:
- </td>
- <td>
- fragment, decoration, page, page decorator, portlet decorator,
- application relative, normalized template path, absolute URL
- </td>
- </tr>
-</table>
-</section>
-</body>
-</document>
-
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<document>
+ <properties>
+ <title>Guide to Portal Design</title>
+ <subtitle>Documentation for Designers working with Jetspeed Portal Design</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="taylor@apache.org"/>
+ </authors>
+ </properties>
+ <body>
+<section name="Portal Design Introduction">
+<p>
+The Java Portlet API (JSR-168) defines the Java standard interface for programming portlets.
+The Java Portlet API specification enables interoperability between Portlets and Portals.
+It is the standard specification for developing Java portlets. However the Java Portlet API
+does not define standards for laying out and aggregating portlets and markup on a page.
+The documentation here under "Portal Design" covers:
+<ul>
+ <li><a href='guide-psml.html'>Page Aggregation - see the section on PSML</a></li>
+ <li><a href='guide-decorators.html'>Page and Portlet Decorators</a></li>
+ <li><a href='guide-layouts.html'>Page Layouts</a></li>
+ <li><a href='guide-jpt.html'>The Jetspeed Power Tool</a></li>
+ <li><a href='guide-site.html'>The Site Content Model</a></li>
+ <li><a href='#Template Locators'>Template Locators</a></li>
+ <li><a href='#Terminology'>Terminology</a></li>
+</ul>
+</p>
+</section>
+<section name='Templates'>
+<p>
+Rendering one or more portlets into a portlet page is largely made up of the process of aggregating
+portlets as dynamic content with templates. Jetspeed-2 makes use of Velocity templates in
+creating a page layout. Although the Jetspeed-2 architecture fully supports the use of JSP templates for
+decorators and layouts, the developers thus far have chosen Velocity as the tool of choice for writing
+templates. There are two types of templates in Jetspeed: layouts and decorators.
+The process of rendering a page is the combined aggregation of a layout template,
+a page decorator template, a PSML definition, and one or more portlet decorator templates.
+</p>
+<subsection name='Layout Templates'>
+<p>
+Layout templates are packaged in special Jetspeed-specific and deployable portlet applications.
+Layout templates control the overall aggregation of a portal page. Layout templates are
+combined with portlets, providing a component model for aggregation. Jetspeed-2 comes out
+of the box with several layout components including one, two and three column layouts.
+See the <a href='layouts.html'>Layout Documentation</a> for all available Layouts in the
+default Jetspeed-2 system. Of course you can define and derive your own layouts.
+</p>
+</subsection>
+<subsection name='Decorators'>
+ <p>
+Decorator templates are packaged in special Jetspeed-specific and deployable archives.
+Layout templates control the overall aggregation of a portal page. Layout templates are
+combined with portlets, providing a component model for aggregation. Jetspeed-2 comes out
+of the box with several layout components including one, two and three column layouts.
+See the <a href='guide-decorators.html'>Decorator Documentation</a> for all available Layouts in the
+default Jetspeed-2 system. Of course you can define and derive your own layouts.
+</p>
+</subsection>
+</section>
+<section name='Template Locators'>
+<p>
+Templates are located by the Jetspeed Template (and Decorator) Locator Component. These components
+locates templates using a normalized name/value pair URL scheme.
+using this scheme in what is called a 'normalized' URL to either a decorator or layout.
+However, templating engines such as Velocity need to work with templates using paths to templates that are
+relative of a document root. The <a href='guide-jpt.html'>Jetspeed Power Tool</a> facilitates conversion between normalized
+and relative paths. Typically in the Spring configuration, the template root of all decorators is defined as:
+<source test=""><![CDATA[
+${applicationRoot}/WEB-INF/decorations
+]]></source>
+and the root of all layouts (per portlet application) is defined as:
+<source test=""><![CDATA[
+${applicationRoot}/WEB-INF/templates
+]]></source>
+The Normalized Path is defined with named pair values. Examples:
+<source test=""><![CDATA[
+type/layout/media-type/html/name/tigris/decorator.vm
+type/decorator/media-type/html/language/en/country/US/name/metal/decorator.vm
+]]></source>
+<table>
+ <tr>
+ <th>Name</th>
+ <th>Value</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>type</td>
+ <td>layout | portlet | generic</td>
+ <td>The type of template locator. Expected to be either one of the following values
+ <b>layout</b>, <b>portlet</b> (decorator) or <b>generic</b> (decorator). Layouts can be for either page layouts
+ or decorators. Generic type decorators can be used
+ for either portlets or page decorations.</td>
+ </tr>
+ <tr>
+ <td>media-type</td>
+ <td>html | wml | dhtml | ...</td>
+ <td>The markup media type to be located. Should be a valid media type (html, dhtml, wml...)</td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>A valid decorator or layout name</td>
+ <td>The name of the decorator or layout. Usually corresponds to a
+ sub-directory holding the decorator or layout templates, images and stylesheets.</td>
+ </tr>
+ <tr>
+ <td>language</td>
+ <td>A valid ISO-639 standard two-character language abbreviation</td>
+ <td>ISO-639 (http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt) defines a standard for language abbreviations.
+ Typical abbreviations are en for english, fr for french, de for German, ...</td>
+ </tr>
+ <tr>
+ <td>country</td>
+ <td>A valid ISO-3166 standard two-character country code abbreviation</td>
+ <td>ISO-3166 (http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html) defines a standard for country code abbreviations.
+ Typical abbreviations are US for United States, FR for France, ...</td>
+ </tr>
+
+</table>
+
+</p>
+</section>
+
+<section name='Terminology'>
+<table>
+ <tr>
+ <th>
+ Term
+ </th>
+ <th>
+ Definition
+ </th>
+ </tr>
+ <tr>
+ <td>
+ Layout
+ </td>
+ <td>
+Defines the fashion in which grouping of Fragments
+will organized relative to the final, aggregated
+content of a request to the portal. Layouts are defined by
+a portlet which applies an algorithm to a template to
+generate the aggregated content of a page. Typical
+algorithms are two column, three column, nested.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ TODO: left off here:
+ </td>
+ <td>
+ fragment, decoration, page, page decorator, portlet decorator,
+ application relative, normalized template path, absolute URL
+ </td>
+ </tr>
+</table>
+</section>
+</body>
+</document>
+
Propchange: portals/jetspeed-2/trunk/xdocs/guides/guide-portal-design.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: portals/jetspeed-2/trunk/xdocs/guides/guide-portlet-bridges.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/guide-portlet-bridges.xml?view=diff&rev=514329&r1=514328&r2=514329
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-portlet-bridges.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-portlet-bridges.xml Sat Mar 3 18:13:22 2007
@@ -1,83 +1,83 @@
-<?xml version="1.0"?>
-<!--
-Copyright 2004 The Apache Software Foundation
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
--->
-<document>
- <properties>
- <title>Jetspeed Portlet Bridges</title>
- <subtitle>Documentation for Apache Portals Portlet Bridges</subtitle>
- <authors>
- <person name="David Le Strat" email="dlestrat@apache.org"/>
- </authors>
- </properties>
- <body>
-<section name="Struts Portlet Bridge">
-<p>
-The Portals Bridges project provides a Portlet bridge for Struts which can be used with Jetspeed 2.
-Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-struts/index.html">Apache Portals Struts Portlet Bridge</a>
-sub project documentation.
-</p>
-<p>
-The Bridges project also provides a great Struts Portlet demo application:
-<ul>
- <li>The <a href="http://portals.apache.org/bridges/multiproject/jpetstore/index.html">iBATIS JPetstore Demo Portlet</a> application</li>
-</ul>
-</p>
-</section>
-<section name="JSF Portlet Bridge">
-<p>
-The Portals Bridges project provides a Portlet bridge for JSF which can be used with Jetspeed 2.
-Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-jsf/index.html">Apache Portals JSF Portlet Bridge</a>
-sub project documentation.
-</p>
-<p>
-Portals Bridges also provides a JSF portlet demo application based on MyFaces JSF implementation:
-<ul>
- <li>The <a href="http://portals.apache.org/bridges/multiproject/jsf-demo/index.html">JSF Portlet Demo</a> application using Apache Portals JSF Portlet Bridge</li>
-</ul>
-</p>
-</section>
-
-<section name="Velocity Portlet Bridge">
-<p>
-The Portals Bridges project provides a Portlet bridge for Velocity which is used extensively within Jetspeed 2 itself.
-Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-velocity/index.html">Apache Portals Velocity Portlet Bridge</a>
-sub project documentation.
-</p>
-<p>
-An example of the Velocity Bridge usage within Jetspeed 2 is:
-<ul>
- <li>The Jetspeed 2 <a href="../multiproject/j2-admin/index.html">Administration and Security</a> application</li>
-</ul>
-</p>
-</section>
-
-<section name="Perl Portlet Bridge">
-<p>
-The Portals Bridges project provides a Portlet bridge for Perl applications. Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-perl/index.html">Apache Portals Perl Portlet Bridge</a>
-sub project documentation.
-</p>
-</section>
-
-<section name="PHP Portlet Bridge">
-<p>
-The Portals Bridges project provides a Portlet bridge for PHP applications. Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-php/index.html">Apache Portals PHP Portlet Bridge</a>
-sub project documentation.
-</p>
-</section>
-
-</body>
-</document>
-
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<document>
+ <properties>
+ <title>Jetspeed Portlet Bridges</title>
+ <subtitle>Documentation for Apache Portals Portlet Bridges</subtitle>
+ <authors>
+ <person name="David Le Strat" email="dlestrat@apache.org"/>
+ </authors>
+ </properties>
+ <body>
+<section name="Struts Portlet Bridge">
+<p>
+The Portals Bridges project provides a Portlet bridge for Struts which can be used with Jetspeed 2.
+Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-struts/index.html">Apache Portals Struts Portlet Bridge</a>
+sub project documentation.
+</p>
+<p>
+The Bridges project also provides a great Struts Portlet demo application:
+<ul>
+ <li>The <a href="http://portals.apache.org/bridges/multiproject/jpetstore/index.html">iBATIS JPetstore Demo Portlet</a> application</li>
+</ul>
+</p>
+</section>
+<section name="JSF Portlet Bridge">
+<p>
+The Portals Bridges project provides a Portlet bridge for JSF which can be used with Jetspeed 2.
+Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-jsf/index.html">Apache Portals JSF Portlet Bridge</a>
+sub project documentation.
+</p>
+<p>
+Portals Bridges also provides a JSF portlet demo application based on MyFaces JSF implementation:
+<ul>
+ <li>The <a href="http://portals.apache.org/bridges/multiproject/jsf-demo/index.html">JSF Portlet Demo</a> application using Apache Portals JSF Portlet Bridge</li>
+</ul>
+</p>
+</section>
+
+<section name="Velocity Portlet Bridge">
+<p>
+The Portals Bridges project provides a Portlet bridge for Velocity which is used extensively within Jetspeed 2 itself.
+Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-velocity/index.html">Apache Portals Velocity Portlet Bridge</a>
+sub project documentation.
+</p>
+<p>
+An example of the Velocity Bridge usage within Jetspeed 2 is:
+<ul>
+ <li>The Jetspeed 2 <a href="../multiproject/j2-admin/index.html">Administration and Security</a> application</li>
+</ul>
+</p>
+</section>
+
+<section name="Perl Portlet Bridge">
+<p>
+The Portals Bridges project provides a Portlet bridge for Perl applications. Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-perl/index.html">Apache Portals Perl Portlet Bridge</a>
+sub project documentation.
+</p>
+</section>
+
+<section name="PHP Portlet Bridge">
+<p>
+The Portals Bridges project provides a Portlet bridge for PHP applications. Please visit the <a href="http://portals.apache.org/bridges/multiproject/portals-bridges-php/index.html">Apache Portals PHP Portlet Bridge</a>
+sub project documentation.
+</p>
+</section>
+
+</body>
+</document>
+
Propchange: portals/jetspeed-2/trunk/xdocs/guides/guide-portlet-bridges.xml
------------------------------------------------------------------------------
svn:eol-style = native
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?view=diff&rev=514329&r1=514328&r2=514329
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-profiler.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-profiler.xml Sat Mar 3 18:13:22 2007
@@ -1,595 +1,595 @@
-<?xml version="1.0"?>
-<!--
-Copyright 2004 The Apache Software Foundation
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
--->
-<document>
- <properties>
- <title>Profiler</title>
- <subtitle>Documentation for Jetspeed-2 Profiler</subtitle>
- <authors>
- <person name="David Sean Taylor" email="taylor@apache.org"/>
- </authors>
- </properties>
- <body>
-<section name="Profiler Overview">
-<p>
-The Jetspeed Profiler is a portal resource location rule-based engine.
-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 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 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="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 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.
-</p>
-<subsection name='Rule Criteria'>
-<p>
-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>
- </tr>
- <tr>
- <td>request</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 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 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>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>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>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>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>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>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>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>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>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>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>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>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>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>
-</subsection>
-</section>
-<section name="Profile Locators">
-<p>
-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.
-</p>
-<img src="images/profiler/parameter-resolution.jpg" border="1"/>
-<p>
-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>
-
-</body>
-</document>
-
+<?xml version="1.0"?>
+<!--
+Copyright 2004 The Apache Software Foundation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<document>
+ <properties>
+ <title>Profiler</title>
+ <subtitle>Documentation for Jetspeed-2 Profiler</subtitle>
+ <authors>
+ <person name="David Sean Taylor" email="taylor@apache.org"/>
+ </authors>
+ </properties>
+ <body>
+<section name="Profiler Overview">
+<p>
+The Jetspeed Profiler is a portal resource location rule-based engine.
+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 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 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="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 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.
+</p>
+<subsection name='Rule Criteria'>
+<p>
+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>
+ </tr>
+ <tr>
+ <td>request</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 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 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>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>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>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>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>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>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>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>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>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>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>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>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>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>
+</subsection>
+</section>
+<section name="Profile Locators">
+<p>
+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.
+</p>
+<img src="images/profiler/parameter-resolution.jpg" border="1"/>
+<p>
+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>
+
+</body>
+</document>
+
Propchange: portals/jetspeed-2/trunk/xdocs/guides/guide-profiler.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: portals/jetspeed-2/trunk/xdocs/guides/guide-profiling-ip.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/trunk/xdocs/guides/guide-profiling-ip.xml?view=diff&rev=514329&r1=514328&r2=514329
==============================================================================
--- portals/jetspeed-2/trunk/xdocs/guides/guide-profiling-ip.xml (original)
+++ portals/jetspeed-2/trunk/xdocs/guides/guide-profiling-ip.xml Sat Mar 3 18:13:22 2007
@@ -1,78 +1,78 @@
-<?xml version="1.0"?>
-<!--
- Copyright 2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-<document>
- <properties>
- <title>Guide to Profiling IP Addresses</title>
- <subtitle>Documentation for Using the ip-address Profiler rule</subtitle>
- <authors>
- <person name="Philip Mark Donaghy" email="philip.donaghy@gmail.com" />
- </authors>
- </properties>
- <body>
- <section name="Guide to Profiling IP Addresses">
- <p>
- Jetspeed has a built in mechanism to serve custom content
- to a specific IP address. This feature uses the Profiler
- to negociate pages based on the requesting clients IP address.
- </p>
- <subsection name="1. The Rule">
- <p>
- The rule is identified by the key <b>ip-address</b>. There is one criterion
- called <b>ip</b> resolved using the IP Criterion Resolver. This class implements
- the resolve method of the Rule Criterion Resolver in order to obtain the IP address
- from the request.
- </p>
- <source>
- public String resolve(RequestContext context, RuleCriterion criterion)
- {
- // look for override
- String value = super.resolve(context, criterion);
- if (value != null) { return value.toLowerCase(); }
-
- // Note IP addresses can vary depending on the client
- // Konqueror 3.4.2 returns IPv6 e.g. 0:0:0:0:0:0:0:1
- // Firefox 1.0.7 returns IPv4 e.g. 127.0.0.1
- // This is the value used to resolve pages in the _ip directory
- // TODO create an option to convert all IPv4 addresses to IPv6
- return context.getRequest().getRemoteAddr();
- }
- </source>
- </subsection>
- <subsection name="2. The Page Locator">
- <p>
- Users with this profile rule set to the <b>page</b> locator are served pages from the _ip
- directory of the psml site tree. Example, if a request is made for
- http://www.apache.org/jetspeed/portal/default-page.psml from 81.29.65.234
- then the rule will match /WEB-INF/pages/_ip/81.29.65.234/default-page.psml before
- falling back to /WEB-INF/pages/default-page.psml
- </p>
- </subsection>
- <subsection name="3. Example Use Cases">
- <p>
- You have a location in Tokyo serving content specific to that
- location. Your kiosk is configured with a fixed IP address. The annonymous
- user (guest by default) uses this profile rule. Anyone using
- the portal from that kiosk would be served content from the _ip directory.
- </p>
- <p>
- It could also be used to profile robots. Or keep out unwanted visitors. And can be the basis for
- profiling IP ranges or IP prefixes, networks and subnetworks, and geographic locations.
- </p>
- </subsection>
- </section>
- </body>
-</document>
+<?xml version="1.0"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document>
+ <properties>
+ <title>Guide to Profiling IP Addresses</title>
+ <subtitle>Documentation for Using the ip-address Profiler rule</subtitle>
+ <authors>
+ <person name="Philip Mark Donaghy" email="philip.donaghy@gmail.com" />
+ </authors>
+ </properties>
+ <body>
+ <section name="Guide to Profiling IP Addresses">
+ <p>
+ Jetspeed has a built in mechanism to serve custom content
+ to a specific IP address. This feature uses the Profiler
+ to negociate pages based on the requesting clients IP address.
+ </p>
+ <subsection name="1. The Rule">
+ <p>
+ The rule is identified by the key <b>ip-address</b>. There is one criterion
+ called <b>ip</b> resolved using the IP Criterion Resolver. This class implements
+ the resolve method of the Rule Criterion Resolver in order to obtain the IP address
+ from the request.
+ </p>
+ <source>
+ public String resolve(RequestContext context, RuleCriterion criterion)
+ {
+ // look for override
+ String value = super.resolve(context, criterion);
+ if (value != null) { return value.toLowerCase(); }
+
+ // Note IP addresses can vary depending on the client
+ // Konqueror 3.4.2 returns IPv6 e.g. 0:0:0:0:0:0:0:1
+ // Firefox 1.0.7 returns IPv4 e.g. 127.0.0.1
+ // This is the value used to resolve pages in the _ip directory
+ // TODO create an option to convert all IPv4 addresses to IPv6
+ return context.getRequest().getRemoteAddr();
+ }
+ </source>
+ </subsection>
+ <subsection name="2. The Page Locator">
+ <p>
+ Users with this profile rule set to the <b>page</b> locator are served pages from the _ip
+ directory of the psml site tree. Example, if a request is made for
+ http://www.apache.org/jetspeed/portal/default-page.psml from 81.29.65.234
+ then the rule will match /WEB-INF/pages/_ip/81.29.65.234/default-page.psml before
+ falling back to /WEB-INF/pages/default-page.psml
+ </p>
+ </subsection>
+ <subsection name="3. Example Use Cases">
+ <p>
+ You have a location in Tokyo serving content specific to that
+ location. Your kiosk is configured with a fixed IP address. The annonymous
+ user (guest by default) uses this profile rule. Anyone using
+ the portal from that kiosk would be served content from the _ip directory.
+ </p>
+ <p>
+ It could also be used to profile robots. Or keep out unwanted visitors. And can be the basis for
+ profiling IP ranges or IP prefixes, networks and subnetworks, and geographic locations.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>
Propchange: portals/jetspeed-2/trunk/xdocs/guides/guide-profiling-ip.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: portals/jetspeed-2/trunk/xdocs/guides/guide-properties.xml
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org