Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/credentials.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/credentials.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/credentials.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/credentials.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,168 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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 2 Security - Credentials Management</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + <person name="Ate Douma" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Credentials Management Overview"> + <subsection name="DefaultCredentialHandler Features"> + <p> + With the Jetspeed <a href="../apidocs/org/apache/jetspeed/security/spi/impl/DefaultCredentialHandler.html"> + <code>DefaultCredentialHandler</code></a> special management of password credentials can + easily be configured. Through the provided + <a href="../apidocs/org/apache/jetspeed/security/spi/PasswordCredentialProvider.html"> + <code>PasswordCredentialProvider</code></a> and + <a href="../apidocs/org/apache/jetspeed/security/spi/InternalPasswordCredentialInterceptor.html"> + <code>InternalPasswordCredentialInterceptor</code></a> components custom logic can be plugged in for:</p> + <ul> + <li>providing a custom + <a href="../apidocs/org/apache/jetspeed/security/PasswordCredential.html"> + <code>PasswordCredential</code></a> implementation</li> + <li>password encoding<br/> + If an + <a href="../apidocs/org/apache/jetspeed/security/spi/CredentialPasswordEncoder.html"> + <code>CredentialPasswordEncoder</code></a> is available from the + <code>PasswordCredentialProvider</code> passwords will be encoded with it before they are persisted. + The provided + <a href="../apidocs/org/apache/jetspeed/security/spi/impl/MessageDigestCredentialPasswordEncoder.html"> + <code>MessageDigestCredentialPasswordEncoder</code></a> uses + <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/security/MessageDigest.html";> + <code>MessageDigest</code></a> hash algorithms for the password encryption, and can for example be + configured to use <code>SHA-1</code> and <code>Base64</code>. + </li> + <li>enforcing password value rules<br/> + If an + <a href="../apidocs/org/apache/jetspeed/security/spi/CredentialPasswordValidator.html"> + <code>CredentialPasswordValidator</code></a> is available from the + <code>PasswordCredentialProvider</code>, passwords will be validated with it before they are persisted. + The + <a href="../apidocs/org/apache/jetspeed/security/spi/impl/DefaultCredentialPasswordValidator.html"> + <code>DefaultCredentialPasswordValidator</code></a> for example enforces non-emtpy password. And + with the + <a href="../apidocs/org/apache/jetspeed/security/spi/impl/SimpleCredentialPasswordValidator.html"> + <code>SimpleCredentialPasswordValidator</code></a> a minimum length and a minum number of numeric + characters can be enforced. + </li> + <li>intercepting + <a href="../apidocs/org/apache/jetspeed/security/om/InternalCredential.html"> + <code>InternalCredential</code></a> lifecycle events<br/> + If the <code>DefaultCredentialHandler</code> is provided with an + <code>InternalPasswordCredentialInterceptor</code>, it will invoke this interceptor (or an arbirary + set if + <a href="../apidocs/org/apache/jetspeed/security/spi/impl/InternalPasswordCredentialInterceptorsProxy.html"> + <code>InternalPasswordCredentialInterceptorsProxy</code></a> is used) on: + <ul> + <li>after loading a credential from the persistent store</li> + <li>after authenticating a user</li> + <li>before a new credential is saved to the persistent store</li> + <li>before a new password is save for the credential</li> + </ul> + Jetspeed already provides a basic set of interceptors, ready to be used: + <ul> + <li> + <a href="../apidocs/org/apache/jetspeed/security/spi/impl/ValidatePasswordOnLoadInterceptor.html"> + <code>ValidatePasswordOnLoadInterceptor</code></a><br/> + This interceptor can be used to validate (pre)set passwords in the persistent store and force + a required change by the user if invalid. It uses the configured <code>CredentialPasswordValidator</code> + of the <code>PasswordCredentialProvider</code>, the same as used when a password is changed. + </li> + <li> + <a href="../apidocs/org/apache/jetspeed/security/spi/impl/EncodePasswordOnFirstLoadInterceptor.html"> + <code>EncodePasswordOnFirstLoadInterceptor</code></a><br/> + This interceptor can be used if passwords needs to be preset in the persistent store or + migrated unencoded from a different store. With this interceptor, these cleartext password + will automatically be encoded the first time they are loaded from the database, using the + <code>CredentialPasswordEncoder</code> from the <code>PasswordCredentialProvider</code> + </li> + <li> + <a href="../apidocs/org/apache/jetspeed/security/spi/impl/PasswordExpirationInterceptor.html"> + <code>PasswordExpirationInterceptor</code></a><br/> + This interceptor can be used to enforce a maximum lifespan for passwords. + It manages the <code>expiration_date</code> and <code>is_expired</code> members of the + <code>InternalCredential</code> and sets the expired flag when on authentication of a user + its (valid) password is expired. The authentication will then fail.<br/> + Note: A Jetspeed pipeline Valve, the <code>PasswordCredentialValveImpl</code> can be + used to request or even enforce users to change their password in time to prevent a password + expiration (described further below). + </li> + <li> + <a href="../apidocs/org/apache/jetspeed/security/spi/impl/MaxPasswordAuthenticationFailuresInterceptor.html"> + <code>MaxPasswordAuthenticationFailuresInterceptor</code></a><br/> + This interceptor can be used to prevent password hacking by enforcing a maximum number of + invalid password attempts in a row. Once this number of authentication failures is reached, + the credential will be disabled. On a successful authentication though, this count + will automatically be reset to zero again by the <code>DefaultCredentialHandler</code>. + </li> + <li> + <a href="../apidocs/org/apache/jetspeed/security/spi/impl/PasswordHistoryInterceptor.html"> + <code>PasswordHistoryInterceptor</code></a><br/> + This interceptor can be used to enforce usage of unique new passwords in respect to a certain + number of previous used passwords. When a new password is set, the current password is saved + in a FIFO stack of used passwords. When a user itself changes its password, it must be different + from all the onces thus saved, otherwise a + <a href="../apidocs/org/apache/jetspeed/security/PasswordAlreadyUsedException.html"> + <code>PasswordAlreadyUsedException</code></a> will be + thrown. But setting a new password through the administrative interface still allows any + password (when otherwise valid) to be set. + </li> + </ul> + <p> + The <code>DefaultCredentialHandler</code> only supports one interceptor to be configured. + But, with the + <a href="../apidocs/org/apache/jetspeed/security/spi/impl/InternalPasswordCredentialInterceptorsProxy.html"> + <code>InternalPasswordCredentialInterceptorsProxy</code></a>, a list of interceptors can + be configured which then will be invoked sequentially.</p> + <p> + Jetspeed comes out of the box with several of these interceptors configured, and its very easy to + change and extend.See the <a href="../deployguide/security-config.html#security-spi-atn_xml">security-spi-atn.xml</a> + section in the <a href="../deployguide/security-config.html">Security Services Configuration</a> document for a description + of the default configuration. Also provided there is an example how to setup the interceptors to + restore the "old" (and much more restrict) configuration provided with the 2.0-M3 release and + earlier.</p> + </li> + </ul> + </subsection> + <subsection name="Credentials Management Implementation"> + <p> + The class diagram below describes the components used for the + <code>DefaultCredentialHandler</code> + implementation. + </p> + <p align="center"> + <img src="images/credential-handler-c.gif" border="0" /> + </p> + <p> + The OJB mappings for the default credentials implementation are described in + <code>security_repository.xml</code>: + <ul> + <li><code>InternalCredential</code>: Maps to the SECURITY_CREDENTIAL table.</li> + </ul> + The following database schema is used to stored credentials and their associations to principals. + </p> + <p align="center"> + <img src="images/principals-credentials-schema.gif" border="0" /> + </p> + </subsection> + </section> + </body> +</document>
Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dao.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dao.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dao.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dao.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,74 @@ +<?xml version="1.0" ?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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-2 RDBMS</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Data Access Overview"> + <p> + Jetspeed-2 RDBMS component provide some of level of abstraction from the underlying persistence mechanism. + </p> + <subsection name="Data Access Using Object Relational Mapping"> + <p> + Jetspeed-2 uses object relational mapping as the underlying technology for persistence. By default, + <a href="http://db.apache.org/ojb/";>Apache OJB</a> is used as an ORM engine. In order to minimize Jetspeed-2 + OJB dependencies, the <code>InitablePersistenceBrokerDaoSupport</code> provides a layer of abstraction that minimizes + the dependencies on a specific ORM engine. The class diagram below illustration the Jetspeed-2 implementation classes + that leverage <code>InitablePersistenceBrokerDaoSupport</code>:<br/> + <img src="images/persistence-broker-dao-c.gif" border="0"/> + </p> + <p> + The <code>InitablePersistenceBrokerDaoSupport</code> extends <code>org.springframework.orm.ojb.support.PersistenceBrokerDaoSupport</code>. + </p> + </subsection> + <subsection name="Spring ORM Support"> + <p> + Spring's adds significant support when using the O/R mapping layer of your choice to create data access applications. The + <code>InitablePersistenceBrokerDaoSupport</code> extends spring layer of abstraction for persistence support, specifically the + OJB <a href="http://static.springframework.org/spring/docs/1.2.x/reference/orm.html#orm-ojb";><code>PersistenceBroker</code> API support</a>. + </p> + <p> + Using such a layer of abstraction has many advantages. Some of the advantages outlined in Spring's documentation are: + <ul> + <li>Ease of testing. Spring's inversion of control approach makes it easy to swap the implementations and config locations of persistence manager instances, + JDBC DataSources, transaction managers, and mapper object implementations (if needed). This makes it much easier to isolate and test each piece of + persistence-related code in isolation.</li> + <li>Common data access exceptions. Spring can wrap exceptions from you O/R mapping tool of choice, converting them from proprietary (potentially checked) exceptions + to a common runtime DataAccessException hierarchy. This allows you to handle most persistence exceptions, which are non-recoverable, only in the appropriate layers, + without annoying boilerplate catches/throws, and exception declarations. You can still trap and handle exceptions anywhere you need to. Remember that JDBC exceptions + (including DB specific dialects) are also converted to the same hierarchy, meaning that you can perform some operations with JDBC within a consistent programming model.</li> + <li>General resource management. Spring application contexts can handle the location and configuration of persistence managers instances, JDBC DataSources, + and other related resources. This makes these values easy to manage and change. Spring offers efficient, easy and safe handling of persistence resources.</li> + <li>Integrated transaction management. Spring allows you to wrap your O/R mapping code with either a declarative, AOP style method interceptor, + or an explicit 'template' wrapper class at the Java code level. In either case, transaction semantics are handled for you, and proper transaction handling (rollback, etc) + in case of exceptions is taken care of. As discussed below, you also get the benefit of being able to use and swap various transaction managers, without your ORM specific code being affected: + for example, between local transactions and JTA, with the same full services (such as declarative transactions) available in both scenarios. As an additional benefit, + JDBC-related code can fully integrate transactionally with the code you use to do O/R mapping. This is useful for data access that's not suitable for O/R mapping, + such as batch processing or streaming of BLOBs, which still needs to share common transactions with O/R mapping operations.</li> + <li>To avoid vendor lock-in, and allow mix-and-match implementation strategies.</li> + </ul> + </p> + </subsection> + </section> + </body> +</document> + Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-capabilities.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-capabilities.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-capabilities.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-capabilities.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,226 @@ +<?xml version="1.0" ?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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-2 Capabilities</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Capabilities Overview"> + <p> + Jetspeed-2 capabilities provides a mechanism for mapping the client used to access Jetspeed-2 to media types + for page rendering. + </p> + <subsection name="Capabilities Definitions"> + <p> + The Jetspeed-2 capability engine maps clients to media types to mime types. Here are some more detailed + definitions: + <ul> + <li>Clients: The application that initiates a request to the Jetspeed-2 portal engine. Jetspeed-2 uses + the <code>User-Agent</code> to determine the client that initiates a request.</li> + <li>Media Type: The type of media requesting the content (HTML, WML, etc.). Content in Jetspeed-2 + can be requested by different type of devices through different media.</li> + <li>Mime Type: The type of content being requested.</li> + </ul> + </p> + <p> + Jetspeed-2 works with the following media types: + <table> + <tr> + <th>Name</th> + <th>Character Set</th> + <th>Description</th> + </tr> + <tr> + <td>html</td> + <td>UTF-8</td> + <td>Rich HTML for HTML 4.0 compliants browsers</td> + </tr> + <tr> + <td>wml</td> + <td>UTF-8</td> + <td>Format for mobile phones and PDAs compatible with WML 1.1</td> + </tr> + <tr> + <td>vxml</td> + <td>UTF-8</td> + <td>Format suitable for use with an audio VoiceXML server</td> + </tr> + <tr> + <td>xml</td> + <td></td> + <td>XML 1.0</td> + </tr> + <tr> + <td>xhtml-basic</td> + <td>UTF-8</td> + <td>XHTML Basic used in WAP devices</td> + </tr> + </table> + </p> + <p> + Jetspeed-2 is configured to recognize the following clients: + <table> + <tr> + <th>Client</th> + <th>User Agent Pattern</th> + <th>Manufacturer</th> + <th>Preferred Mime Type</th> + </tr> + <tr> + <td>ie5</td> + <td>.*MSIE 5.*</td> + <td>Microsoft</td> + <td>html</td> + </tr> + <tr> + <td>ie6</td> + <td>.*MSIE 6.*</td> + <td>Microsoft</td> + <td>html</td> + </tr> + <tr> + <td>ns4</td> + <td>.*Mozilla/4.*</td> + <td>Netscape</td> + <td>html</td> + </tr> + <tr> + <td>mozilla</td> + <td>.*Mozilla/5.*</td> + <td>Mozilla</td> + <td>html</td> + </tr> + <tr> + <td>lynx</td> + <td>Lynx.*</td> + <td>GNU</td> + <td>html</td> + </tr> + <tr> + <td>opera7</td> + <td>.*Opera/7.*</td> + <td>Opera</td> + <td>html</td> + </tr> + <tr> + <td>ie5mac</td> + <td>.*MSIE 5.*Mac.*</td> + <td>Microsoft</td> + <td>html</td> + </tr> + <tr> + <td>safari</td> + <td>.*Mac.*Safari.*</td> + <td>Apple</td> + <td>html</td> + </tr> + <tr> + <td>xhtml-basic</td> + <td>DoCoMo/2.0.*|KDDI-.*UP\.Browser.*|J-PHONE/5.0.*|Vodafone/1.0/.*</td> + <td>N/A</td> + <td>xhtml</td> + </tr> + <tr> + <td>agentxml</td> + <td>agentxml/1.0.*</td> + <td>N/A</td> + <td>xml</td> + </tr> + <tr> + <td>nokia_generic</td> + <td>Nokia.*</td> + <td>Nokia</td> + <td>wml</td> + </tr> + <tr> + <td>up</td> + <td>UP.*|.*UP\.Browser.*</td> + <td>United Planet</td> + <td>wml</td> + </tr> + <tr> + <td>sonyericsson</td> + <td>Ercis.*|SonyE.*</td> + <td>SonyEricsson</td> + <td>wml</td> + </tr> + <tr> + <td>wapalizer</td> + <td>Wapalizer.*</td> + <td>Wapalizer</td> + <td>wml</td> + </tr> + <tr> + <td>klondike</td> + <td>Klondike.*</td> + <td>Klondike</td> + <td>wml</td> + </tr> + <tr> + <td>wml_generic</td> + <td>.*WML.*|.*WAP.*|.*Wap.*|.*wml.*</td> + <td>N/A</td> + <td>wml</td> + </tr> + <tr> + <td>vxml_generic</td> + <td>.*VoiceXML.*</td> + <td>N/A</td> + <td>vxml</td> + </tr> + <tr> + <td>nuance</td> + <td>Nuance.*</td> + <td>Nuance</td> + <td>vxml</td> + </tr> + </table> + </p> + </subsection> + <subsection name="Capabilities and Content Rendering"> + <p> + The <code>media-type</code> is used to locate the appropriate decorations template for the given <code>media-type</code>. + </p> + </subsection> + <subsection name="Capabilities Implementation"> + <p> + The <code>Capabilities</code> component derive a <code>CapabilityMap</code> from the information provided + by the <code>User-Agent</code> request header: + <source> +cm = capabilities.getCapabilityMap(agent); + </source> + </p> + <p> + This operation occurs at the very beginning of Jetspeed-2 request pipeline processing. Once the + <code>CapabilityMap</code> is retrieved, it is added to the Jetspeed-2 <code>org.apache.jetspeed.request.RequestContext</code> + and made available to the portal engine for processing the request. + </p> + <p> + The two pictures below describes the <code>Capabilities</code> interfaces and the relational database model + backing the implementation.<br/><br/> + <img src="images/capabilities-c.gif" border="0"/><br/><br/> + <img src="images/capabilities-db.gif" border="0"/> + </p> + </subsection> + </section> + </body> +</document> + Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-cm.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-cm.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-cm.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-cm.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,47 @@ +<?xml version="1.0" ?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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-2 Component Manager</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Component Manager Overview"> + <p> + The <code>ComponentManager</code> provides a layer of abstraction on top of the component framework that + will be used by Jetspeed-2. This provides a flexible architecture where the component framework used can + easily be "swapped". By default Jetspeed-2 uses the <a href="http://www.springframework.com";>spring + framework</a>. + </p> + <subsection name="Component Manager with Spring"> + <p> + The <code>ComponentManager</code> delegates the initialization of the component framework engine + to an implementation specific to the component framework as illustrated below. The <code>SpringComponentManager</code> + is responsible for initializing the spring engine and calls to spring components within the Jetspeed-2 engines are wrapped + behind generic methods such as <code>getComponent()</code>. + </p> + <p> + <img src="images/spring-component-manager-c.gif" border="0"/><br/><br/> + </p> + </subsection> + </section> + </body> +</document> + Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-deploy.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-deploy.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-deploy.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-deploy.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,87 @@ +<?xml version="1.0" ?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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-2 Deploy Tools</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Jetspeed-2 Deployment Overview"> + <subsection name="Deploying Portlets in Jetspeed-2: An End User View"> + <p> + Deploying custom portlets in Jetspeed-2 is simple. Portlets are very similar to servlets. + They require a deployment descriptor, <code>portlet.xml</code> which goes in <code>WEB-INF</code> + and need to be packaged in a war-like format. You can find quite a few example <code>portlet.xml</code> files within the Jetspeed-2 source tree. + For starters take a look at the one under <code>/portal/src/webapp/WEB-INF</code>. In order to deploy a portlet, Jetspeed-2 requires the user + to follow those steps: + <ol> + <li>Build you portlet as a portlet application just as you would a web application.</li> + <li>Package your portlet application into a .war file.</li> + <li>Copy the .war file to Jetspeed's deployment directory, by default this is <code>WEB-INF/deploy</code>. + Jetspeed will take care of automatically deplying the portlet into the portlet registry and will also deploy the portlet + as a web application into the app server Jetspeed is deployed to.</li> + <li>The easiest way to view your portlet is to add an entry to the <code>default-page.psml</code> under <code>jetspeed/WEB-INF/pages</code>. + The id for the portlet fragment uses a unique combination of <code>${portlet.application.id}::${portlet.name}</code> + where <code>${portlet.application.id}</code> is the actual name of the war file (minus the ".war") that contains your portlet app and + <code>${portlet.name}</code> needs to be the value in the portlet name tags, <code><portlet-name>MyPortlet</portlet-name></code>. + Changes to the psml will be picked up automatically and you should now be able to view your portlet! + </li> + </ol> + </p> + </subsection> + <subsection name="Portlet Deployment: How Does it Work?"> + <p> + The component hierarchy below describes the assembly dependencies supporting Jetspeed-2 deployment functionality. + </p> + <p> + <img src="images/deployment-mgr-assembly.gif" border="0"/><br/><br/> + </p> + <p> + The <code>DeploymentManager</code> is configured with the properties specified in + <code>WEB-INF/conf/jetspeed.properties</code>: + <ul> + <li><code>autodeployment.staging.dir</code>: The directory scanned for autodeployment.</li> + <li><code>autodeployment.delay</code>: The frequency of the deploy directory scanning.</li> + </ul> + The <code>DeploymentManager</code> is also configured with 2 types of <code>DeploymentEventListener</code>: + </p> + <p> + <img src="images/deployment-event-listener-c.gif" border="0"/><br/><br/> + </p> + <p> + <ul> + <li>The <code>DeployPortletAppEventListener</code> handles the hot deployment of portlet applications.</li> + <li>The <code>DeployDecoratorEventListener</code>: handles the hot deployment of decorators. See + <a href="guide-decorators.html">guide to decorators</a> for more information.</li> + </ul> + </p> + <p> + Jetspeed-2 provides a <code>StandardDeploymentManager</code>. The <code>StandardDeploymentManager</code> leverages + a <code>FileSystemScanner</code> to scan for new assets to deploy. It leverages Jetspeed-2 + <a href="../deployguide/deploy-tools.html">deploy tools</a> to prepare portlet applications prior to deployment. + </p> + <p> + <img src="images/deployment-mgr-c.gif" border="0"/><br/><br/> + </p> + </subsection> + </section> + </body> +</document> + Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-prefs.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-prefs.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-prefs.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-prefs.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,144 @@ +<?xml version="1.0" ?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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-2 Preferences</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Preferences Overview"> + <p> + The + <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/prefs/Preferences.html";>java.util.prefs.Preferences API</a> + provides a generic mechanism for storing user and system preferences, as well as configuration data. Jetspeed 2 relies on this API to provide a + wide ranging of functionality to higher level services. Some of the Jetspeed components leveraging the + <code>java.util.prefs.Preferences</code> + API are: + <ul> + <li> + Portlet Preferences: Portlet preferences are stored in the system preferences tree. The following path structure is used to establish + the location of a given portlet preference in the preferences tree: + <code>/portlet_application/${Portlet Application Name}/portlets/${Portlet Name}/preferences/${Preference Name}/values</code> + . The preferences values are stored under the + <code>values</code> + node as a map of key/values. + </li> + <li> + User Attributes: User attributes are stored in the user preferences tree as follow. The following path structure is used to stored a + user's attributes: + <code>/user/${User Name}/userinfo</code> + . The user attributes are stored as a preferences key/values map under the userinfo node. + </li> + <li> + Roles and groups hierarchy: Documentation on how roles and groups hierarchy use the + <code>Preferences</code> + model can be found in the + <a href="hierarchy.html#Leveraging_Preferences_to_Manage_Hierarchies">security section</a> + of the documentation. + </li> + </ul> + </p> + <subsection name="Preferences Goals"> + <p> + The <i>Preferences</i> API provides a generic implementation for organizing properties as illustrated below: + <source> +<preferences EXTERNAL_XML_VERSION="1.0"> +<root type="user"> + <map /> + <node name="user"> + <map /> + <node name="principal1"> + <map /> + <node name="propertyset1"> + <map> + <entry key="set1prop1" value="256" /> + <entry key="set1prop2" value="314" /> + </map> + </node> + </node> +</root></source> + </p> + <p> + A good reference article can be found at <a href="http://www.onjava.com/pub/a/onjava/synd/2001/10/17/j2se.html";> + ONJava.com</a>. + </p> + </subsection> + <subsection name="Preferences Implementation Overview"> + <p> + Jetspeed 2 + <code>Preferences</code> + implementation leverages the following classes: + </p> + <p> + <img src="images/preferences-c.gif" border="0" /> + </p> + <table> + <tr> + <th>Class</th> + <th>Description</th> + </tr> + <tr> + <td> + <code>PreferencesFactoryImpl</code> + </td> + <td> + Implements the <code>java.util.prefs.PreferencesFactory</code> that generates + <code>Preferences</code> objects. The <code>PreferencesFactoryImpl</code> is + configured through spring assembly (<code>prefs.xml</code>) to use a + <code>PreferencesProvider</code> that encapsalutes the backing store implementation. + + </td> + </tr> + <tr> + <td> + <code>PreferencesImpl</code> + </td> + <td> + Extends the <code>java.util.prefs.AbstractPreferences</code> and implements the SPI by + leveraging the <code>PreferencesProvider</code> API. Jetspeed <code>Preferences</code> + implementation can be configured to validate that preferences map key/values are created + for predefined keys. A <code>PropertyManager</code> enforces the checks if enabled. + </td> + </tr> + <tr> + <td> + <code>PreferencesProvider</code> + </td> + <td> + Encapsulates the preferences implementation again a specific backing store. In Jetspeed 2, the + default implementation is provided by + <code>org.apache.jetspeed.prefs.impl.PersistenceBrokerPreferencesProvider</code> + </td> + </tr> + </table> + </subsection> + <subsection name="Preferences Database Schema"> + <p> + The following database schema is being used in Jetspeed 2 to store <code>Preferences</code> + in a relational database model. + </p> + <p> + <img src="images/preferences-schema.gif" border="0"/> + </p> + </subsection> + </section> + </body> +</document> + Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-rdbms.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-rdbms.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-rdbms.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-rdbms.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,101 @@ +<?xml version="1.0" ?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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-2 RDBMS</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="RDBMS Overview"> + <p> + Jetspeed-2 RDBMS component provide a layer of abstraction from the persistence mechanism used by Jetspeed-2. + It provides facilities for datasource configuration as well as data access. + </p> + <subsection name="Datasource Configuration"> + <p> + Jetspeed-2 uses <a href="http://db.apache.org/ojb/";>OJB</a> <code>PersistenceBroker</code> API as its default + persistence mechanism. The <code>ConnectionRepositoryEntry</code> component configures OJB for Jetspeed-2 as well + as the properties available under <code>/etc/db-ojb</code> in the Jetspeed-2 source repository or <code>WEB-INF/classes</code> + in a deployed instance of Jetspeed-2. + </p> + <p> + The <code>datasource.xml</code> spring assembly configuration file configures <code>ConnectionRepositoryEntry</code> and is located + in <code>WEB-INF/assembly/boot</code>. + </p> + <p> + The <code>ConnectionRepositoryEntry</code> configures an entry in OJB's ConnectionRepository according to its properties. + The properties <code>driverClassName</code>, <code>url</code>, <code>username</code> and <code>password</code> are used + only if no <code>jndiName</code> is set, i.e. if the connection factory uses the driver to create data sources. The platform + settings are derived from the configured data source or database driver using OJB's <code>JdbcMetadataUtils</code> class. The default + Jetspeed-2 <code>ConnectionRepositoryEntry</code> configuration expose a datasource. + <source> + <bean id="JetspeedDS" class="org.apache.jetspeed.components.rdbms.ojb.ConnectionRepositoryEntry"> + <property name="jndiName"> + <value>java:comp/env/jdbc/jetspeed</value> + </property> + </bean></source> + </p> + <p> + In order for OJB to be configured properly with Jetspeed-2, the <code>OJB.properties</code> file (located under + <code>/etc/db-ojb/OJB.properties</code> in the source tree and <code>WEB-INF/classes</code> in the deployed application) + must set: + <source> + ConnectionManagerClass=org.apache.jetspeed.components.rdbms.ojb.ConnectionManagerImpl</source> + instead of: + <source> + ConnectionFactoryClass=org.apache.ojb.broker.accesslayer.ConnectionFactoryManagedImpl</source> + </p> + <p> + A class diagram of <code>ConnectionRepositoryEntry</code> and <code>ConnectionManagerImpl</code> is + provided below:<br/> + <img src="images/connection-repository-c.gif" border="0"/> + </p> + </subsection> + <subsection name="OJB Datasource Configuration"> + <p> + The bean name provided in <code>datasource.xml</code> must match the <code>jdbc-connection-descriptor</code> + <code>jcd-alias</code> property (by default <code>JetspeedDS</code>) located in OJB <code>repository_database.xml</code> + as illustrated below. + <source> + <jdbc-connection-descriptor + jcd-alias="JetspeedDS" + default-connection="true" + batch-mode="false"></source> + </p> + </subsection> + <subsection name="Jetspeed-2 Datasource Configuration in Tomcat"> + <p> + Jetspeed-2 configure the following datasource in Tomcat. In the source tree, the Tomcat datasource configuration + is located under <code>/etc/conf/tomcat</code>. When deployed Jetspeed-2 in a Tomcat instance, the Jetspeed-2 + datasource configuration are deployed under <code>${tomcat_home}/conf/Catalina/localhost/jetspeed.xml</code>. If a different + portal name is being used for Jetspeed-2, the configuration file will be named accordingly. + <source> + <Resource name="jdbc/jetspeed" auth="Container" + factory="org.apache.commons.dbcp.BasicDataSourceFactory" + type="javax.sql.DataSource" username="" password="" + driverClassName="org.apache.derby.jdbc.EmbeddedDriver" + url="jdbc:derby:/tmp/productiondb;create=true" + maxActive="100" maxIdle="30" maxWait="10000"/></source> + </p> + </subsection> + </section> + </body> +</document> + Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-search.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-search.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-search.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-search.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,84 @@ +<?xml version="1.0" ?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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-2 Search</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Search Overview"> + <p> + Jetspeed-2 provides an integration with the popular <a href="http://lucene.apache.org/";>Apache Lucene</a>, + a high-performance, full-featured text search engine library written entirely in Java; a technology suitable + for nearly any application that requires full-text search, especially cross-platform.. + </p> + <subsection name="SearchEngine Overview"> + <p> + Jetspeed-2 provides a <code>SearchEngine</code> component configured as a spring component. The <code>SearchEngine</code> + component is configured in <code>WEB-INF/assembly/search.xml</code>. The default implementation based on the embedded Lucene + search engine must specify the location of the search index file, the name of the analyzer class (if null the default analyzer + <code>StandardAnalyzer</code> is used), whether to optimize after update and the <code>HandlerFactory</code>: + <source> + <bean id="org.apache.jetspeed.search.SearchEngine" + class="org.apache.jetspeed.search.lucene.SearchEngineImpl"> + <constructor-arg index="0"><value>${applicationRoot}/WEB-INF/search_index</value></constructor-arg> + <constructor-arg index="1"><null /></constructor-arg> + <constructor-arg type="boolean"><valu>true</value></constructor-arg> + <constructor-arg><ref bean="org.apache.jetspeed.search.HandlerFactory"/></constructor-arg> + </bean></source> + </p> + <p> + The <code>HandlerFactory</code> provides the <code>SearchEngine</code> with a list of <code>ObjectHandler</code> + that will handle the various document types supported by Jetspeed-2 for search. By default, Jetspeed-2 supports + portlet instances and portlet definitions as searchable entities. When portlets are registered to the portal, + <code>searchEngine.add(pa)</code> and <code>searchEngine.add(pa.getPortletDefinitions())</code> are invoked. This + action updates the Jetspeed-2 search index. For more information on how portlets are registered to the search engine, + see <code>org.apache.jetspeed.tools.pamanager.PortletApplicationManager</code>. + <br/> + <img src="images/searchengine-c.gif" border="0"/> + </p> + </subsection> + <subsection name="Document Handlers Overview"> + <p> + Document Handlers are responsible for the parsing of a specific document type in order to index the relevant document fields. + </p> + <p> + Jetspeed-2 provides 2 document handlers implementations responsible for parsing parsing the documents supported by Jetspeed-2 + as <code>org.apache.jetspeed.search.ParsedObject</code>. The <code>ParsedObject</code> specify the list of fields + and documents supported by Jetspeed-2 that can then be added to <code>org.apache.lucene.document.Document</code> and + written to the index through <code>indexWriter.addDocument(doc)</code> operation of the + <a href="http://lucene.apache.org/java/docs/api/index.html";><code>IndexWriter</code></a>. + </p> + <p> + By default, Jetspeed-2 can index portlet applications and portlet definitions respectively through the + <code>PortletApplicationHandler</code> and <code>PortletDefinitionHandler</code>. + <br/> + <img src="images/searchhandlers-c.gif" border="0"/> + </p> + </subsection> + <subsection name="An Extensible Framework"> + <p> + As most components in Jetspeed-2, the search engine can easily be extended to support addional document types. + </p> + </subsection> + </section> + </body> +</document> + Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-security.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-security.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-security.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-security.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,90 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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 2 Security Architecture</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Overview"> + <p> + Jetspeed 2 security architecture provides a comprehensive suite of security services that can be used to protect a wide ranging type of portal + resources. The security service implementation is fairly independent of the other portal services and + can be reused outside of the portal application. At its core, Jetspeed 2 security services rely entirely + on JAAS to provide authentication and authorization services to the portal: + </p> + <ul> + <li>Authentication services are implemented through the use of JAAS login modules.</li> + <li>Authorization services are implemented through the use of custom JAAS policies.</li> + </ul> + <p> + Both authentication and authorization services have been implemented with the goal of providing a direct plugin to the underlying application + server security framework. Jetspeed 2 can leverage the underlying application server login module as well as through the use of JACC, the + application server policy management capabilities available in J2EE 1.4 (see + <a href="http://java.sun.com/j2ee/javaacc/";>API Specifications</a> + ). + </p> + </section> + <section name="Jetspeed 2 Security Services"> + <p> + JAAS defines the contract for authentication and authorization but does not specify any guidelines for the management of the security resources. + Jetspeed 2 provide a modular set of components aims at providing management functionality for the portal security components. + </p> + <p> + Leveraging Jetspeed 2 component, architecture, the security services provide a set of loosely coupled components providing specialized services: + </p> + <ul> + <li>UserManager: Service providing user management capabilities.</li> + <li>GroupManager: Service providing group management capabilities.</li> + <li>RoleManager: Service providing role management capabilities.</li> + <li>PermissionManager: Service providing permission management capabilities.</li> + </ul> + </section> + <section name="A Modular and Pluggable Architecture"> + <p> + Jetspeed 2 security components are assembled using + <a href="http://martinfowler.com/articles/injection.html";>Dependency Injection</a> + . By default, Jetspeed uses the + <a href="http://www.springframework.org";>Spring Framework</a> + as its default IoC container. + </p> + <p> + <img src="images/components.jpg" align="right" border="0" hspace="1" vspace="2" /> + Jetspeed 2 security services are founded on a set of modular and extensible security modules exposed through an SPI model. The SPI model + provides the ability to modify the behavior of the Jetspeed coarsed security services (UserManager, RoleManager, GroupManager) + through the modification and configuration of specialized handlers. For + instance, Jetspeed security services can be configured to retrieve user security principals through the default Jetspeed store or through an + LDAP store or both. + <br /> + A + <code>SecurityProvider</code> + exposes the configured SPI handlers to the security services. Jetspeed component assembly (based on Spring) architecture provides an easy way to + reconfigure the security services to satisfy the needs of a specific implementation. + </p> + </section> + <section name="Role Based Access Control"> + <p> + Role based access control (RBAC) in Jetspeed 2 support multiple hierarchy resolution strategies as defined in + <a href="http://www.doc.ic.ac.uk/~ecl1/wiki/lib/exe/fetch.php?id=emil%3Aresearchthemes%3Apubbytheme&cache=cache&media=research:papers:1999rbac.pdf";>The Uses of Hierarchy in Access Control</a> + . See <a href="hierarchy.html">Hierarchy Management Overview</a> for more information. + </p> + </section> + </body> +</document> Added: portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-statistics.xml URL: http://svn.apache.org/viewvc/portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-statistics.xml?rev=1691449&view=auto ============================================================================== --- portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-statistics.xml (added) +++ portals/site/jetspeed/jetspeed-2.3/jetspeed-guide-dev/src/site/xdoc/dev-statistics.xml Thu Jul 16 21:01:09 2015 @@ -0,0 +1,179 @@ +<?xml version="1.0" ?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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-2 Statistics</title> + <authors> + <person name="David Le Strat" email="[email protected]" /> + </authors> + </properties> + <body> + <section name="Statistics Overview"> + <p> + Jetspeed-2 provides components for collecting portal data for various application events. + </p> + <subsection name="Collecting Portal Data"> + <p> + <code>PortalStatistics</code> provides APIs for collecting portal application events. The following event types + are supported out of the box: + <ul> + <li>Portlet rendering statistics.</li> + <li>Page rendering statistics.</li> + <li>User access statistics.</li> + </ul> + The <code>PortalStatistics</code> implementation logs usage data based on the + <a href="http://httpd.apache.org/docs/logs.html";>Apache Common Log Format (CLF)</a> + where each log entry is formatted in the form: + <source> + %h %l %u %t \"%r\" %>s %b</source> + where: + <ul> + <li><b>%h </b>- remote host</li> + <li><b>%l </b>- remote log name</li> + <li><b>%u </b>- remote user</li> + <li><b>%t </b>- time in common log time format</li> + <li><b>%r </b>- first line of HTTP request</li> + <li><b>%s </b>- HTTP status code</li> + <li><b>%b </b>- number of bytes sent ("-" if no bytes sent).</li> + </ul> + <br/> + <img src="images/portalstatistics-c.gif" border="0" /> + </p> + <p> + Statistics data is stored in 3 relational tables as illustrated below: + <br/><br/> + <img src="images/statistics-db.gif" border="0" /> + </p> + <p> + Each event type is mapped to a data holder that gets persisted in the statistics tables illustrated above. + <img src="images/logrecord-c.gif" border="0" /> + <br/> + Jetspeed-2 persists the collected data in batches through the <code>BatchedStatistics</code> component. + <br/><br/> + <img src="images/batchedstatistics-c.gif" border="0" /> + </p> + </subsection> + <subsection name="PortalStatistics Configuration"> + <p> + The <code>PortalStatistics</code> component is configured in <code>WEB-INF/assembly/statistics.xml</code> and + requires the following configuration parameters: + <ul> + <li><b>logToCLF</b>: Whether to log to a Common Log Format file.</li> + <li><b>logToDatabase</b>: Whether to record the statistics in the database.</li> + <li><b>maxRecordToFlush_Portlet</b>: The maximum number of portlet events that can be in the portlet statistics FIFO before a flush occurs.</li> + <li><b>maxRecordToFlush_User</b>: The maximum number of user events that can be in the user statistics FIFO before a flush occurs.</li> + <li><b>maxRecordToFlush_Page</b>: The maximum number of page events that can be in the page statistics FIFO before a flush occurs.</li> + <li><b>maxTimeMsToFlush_Portlet</b>: The maximum length of time between FIFO flushes for the portlet statistics FIFO. </li> + <li><b>maxTimeMsToFlush_User</b>: The maximum length of time between FIFO flushes for the user statistics FIFO. </li> + <li><b>maxTimeMsToFlush_Page</b>: The maximum length of time between FIFO flushes for the page statistics FIFO. </li> + <li><b>jetspeedDSEntry</b>: The reference to the Jetspeed data source.</li> + </ul> + </p> + <p> + The FIFO parameters may be adjusted depending on site specific needs. For example, tuning the events and times down makes the system less likely to loose events in the + case of a failure, and also makes the user experience viewing the statistics more responsive to recent events. On the other hand, tuning them higher will reduce the overhead + to the database. Generally newer sites with fewer users should use smaller tuning parameters and larger more mature sites should use larger ones. + </p> + <p> + A sample configuration is provided below: + <source> + <bean id="PortalStatistics" + class="org.apache.jetspeed.statistics.impl.PortalStatisticsImpl" + init-method="springInit" + destroy-method="springDestroy"> + <!-- logToCLF --> + <constructor-arg index='0' type="boolean"><value>false</value></constructor-arg> + <!-- logToDatabase --> + <constructor-arg index='1' type="boolean"><value>true</value></constructor-arg> + <!-- maxRecordToFlush_Portal --> + <constructor-arg index='2'><value>300</value></constructor-arg> + <!-- maxRecordToFlush_User --> + <constructor-arg index='3'><value>50</value></constructor-arg> + <!-- maxRecordToFlush_Page --> + <constructor-arg index='4'><value>100</value></constructor-arg> + <!-- maxTimeMsToFlush_Portal --> + <constructor-arg index='5'><value>300000</value></constructor-arg> + <!-- maxTimeMsToFlush_User --> + <constructor-arg index='6'><value>5000</value></constructor-arg> + <!-- maxTimeMsToFlush_Page --> + <constructor-arg index='7><value>60000</value></constructor-arg> + <!-- jetspeedDSEntry --> + <constructor-arg index='8'><ref bean="JetspeedDS"/></constructor-arg> + </bean></source> + </p> + </subsection> + </section> + <section name="Viewing Statistics"> + <subsection name="Where are the Event Recorded?"> + <p> + Portal statistics events collection is injected at multiple points in the portal engine. Some examples are + provided below. + </p> + <p> + For user events, the <code>SecurityValveImpl</code> logs a user login event in <code>getSubject(RequestContext request)</code>. + <source> + statistics.logUserLogin(request, 0);</source> + </p> + <p> + For portlet events, the <code>RenderingJobImpl</code> invoked in <code>RenderingJob</code> <code>buildRenderingJob</code> logs + a portlet access event. + <source> + statistics.logPortletAccess(requestContext, fragment.getName(), PortalStatistics.HTTP_OK, end - start);</source> + </p> + </subsection> + + </section> + <section name="Data Aggregation Overview"> + <p> + Jetspeed-2 provides a mechanism for aggregating portal statistics for reporting purpose. + </p> + <subsection name="Retrieving Aggregate Statistics"> + <p> + The <code>PortalStatistics</code> component exposes a <code>queryStatistics</code> method that given + a <code>StatisticsQueryCriteria</code> will return <code>AggregateStatistics</code>. + <source> + AggregateStatistics queryStatistics(StatisticsQueryCriteria criteria)</source> + The <code>AggregateStatistics</code> can then be used for reporting purpose. + <br/> + <img src="images/aggregatestatistics-c.gif" border="0" /> + </p> + </subsection> + <subsection name="Using Aggregate Statistics"> + <p> + As illustrated in <a href="../adminguide/statistics.html">viewing statistics</a>, Jetspeed-2 provides a default reporting portlet + for view statistics. To query statistics, a <code>StatisticsQueryCriteria</code> must be set. According to this + criteria the <code>PortalStatistics</code> <code>queryStatistics()</code> method will return an <code>AggregateStatistics</code>. + </p> + <source> + StatisticsQueryCriteria criteria = statistics.createStatisticsQueryCriteria(); + ... + criteria.setUser(user); + criteria.setListsize("5"); + criteria.setSorttype("count"); + criteria.setSortorder("desc"); + criteria.setTimePeriod(timeperiod); + criteria.setQueryType(queryType); + AggregateStatistics stats = statistics.getDefaultEmptyAggregateStatistics(); + ... + statistics.forceFlush(); + stats = statistics.queryStatistics(criteria);</source> + </subsection> + </section> + </body> +</document> +
