portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tay...@apache.org
Subject svn commit: r1510080 [2/2] - in /portals/jetspeed-2/portal/trunk: ./ components/jetspeed-cm/ components/jetspeed-locator/src/main/java/org/apache/jetspeed/profiler/impl/ components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/ compo...
Date Sat, 03 Aug 2013 23:35:20 GMT
Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/Profiler.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/Profiler.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/Profiler.java
(original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/Profiler.java
Sat Aug  3 23:35:19 2013
@@ -26,62 +26,99 @@ import java.util.Collection;
 import java.util.Map;
 
 /**
- * ProfilerService
- * Jetspeed-2 Profiler service. 
- * Locates portal resources given a set of request parameters, properties, and attributes
- * The Profiler is invoked during the request processing pipeline.
- * It requires that the request context is already populated with the portal request and
response,
- * and capability and user information. The request context parameters, properties and attributes
- * make up the profile criterion which the profiler uses to locate portal resources:
- *   1. page
- *   2. navigations
- *   3. document lists
- * 
- * In all cases, a fallback algorithm should be applied to fallback
- * to default portal resources.
+ * 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 {@link ProfileLocator}.
+ * The locator is then added to the request context {@link RequestContext}, from which subsequent
components
+ * on the Jetspeed pipeline, most notably the Page Manager {@link org.apache.jetspeed.page.PageManager}
and
+ * Portal Site {@link org.apache.jetspeed.portalsite.PortalSite} components, can take the
profile locator
+ * and use it to find a requested  resource. For example, the Page Manager uses the locator
to find a page or folder.
+ * The Portal Site component uses the locator build the options on a menu. The profile locator
is
+ * the output from the profiler. The input is a normalized set of runtime parameters and
state. The profiler input is
+ * defined in profiling rules {@link ProfilingRule}, and can be made of any Java class
+ * available on the pipeline. Jetspeed comes with quite a few predefined rules for taking
+ * criteria {@link RuleCriterion} {@link org.apache.jetspeed.profiler.rules.RuleCriterionResolver}
from request parameters,
+ * HTTP headers, security information, language and session attributes.
+ * The profiler is invoked during the request processing pipeline {@link org.apache.jetspeed.pipeline.Pipeline}
+ * in the profiler valve {@link org.apache.jetspeed.pipeline.valve.Valve}.
  *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id$
  */
 public interface Profiler
 {
-    
-    
     /**
-     *  Get the Profile object using the request parameters.
+     *  Retrieve a profile locator {@link ProfileLocator} for the given runtime parameters
represented in the request
+     *  context and for the locatorName. Commonly used locator names are:
+     *  <ul>
+     *      <li>To locate a page - {@link ProfileLocator#PAGE_LOCATOR}</li>
+     *      <li>To locate a security redirect page - {@link ProfileLocator#SECURITY_LOCATOR}</li>
+     *  </ul>
+     *
+     * The algorithm for this method looks up a {@link ProfilingRule} for
+     * the current user on the request context and for the locator name. That rule is then
applied to return a
+     * normalized profile. The profile locator holds the normalized set of rules that are
used further in the
+     * pipeline to locate the resource to be retrieved and rendered.
+     * @see ProfilingRule#apply(org.apache.jetspeed.request.RequestContext, Profiler)
      *
-     * @param context The request context
-     * @param locatorName The name of the profile locator to find i.e. "page", "docset",
...
-     * @return a new Profile Locator object or null if failed to find a appropriate locator.
+     * @param context the request context holding runtime request parameters to be normalized
+     * @param locatorName the commonly known name of the profile locator such as {@link ProfileLocator#PAGE_LOCATOR}
+     * @return a new ProfileLocator object or null if failed to find a appropriate locator.
+     * @throws ProfilerException
      */
     ProfileLocator getProfile(RequestContext context, String locatorName) throws ProfilerException;
-    
+
     /**
-     * 
-     * <p>
-     * getDefaultProfile
-     * </p>
-     * Intstead of using the princpal found within the request, the DEFAULT_RULE_PRINCIPAL
is used.
-     *
-     * @param context The request context
-     * @param locatorName The name of the profile locator to find i.e. "page", "docset",
...
-     * @return a new Profile Locator object or null if failed to find a appropriate locator.
+     *  Retrieve the default profile locator {@link ProfileLocator} for the given runtime
parameters represented in the request
+     *  context and for the locatorName. Differs from {@link #getProfile} in that instead
of using the user principal
+     *  found within the request context's subject, a default, global principal is used.
+     *
+     *  Commonly used locator names are:
+     *  <ul>
+     *      <li>To locate a page - {@link ProfileLocator#PAGE_LOCATOR}</li>
+     *      <li>To locate a security redirect page - {@link ProfileLocator#SECURITY_LOCATOR}</li>
+     *  </ul>
+     *
+     * The algorithm for this method looks up a {@link ProfilingRule} for
+     * the default principal and for the locator name. That rule is then applied to return
a
+     * normalized profile. The profile locator holds the normalized set of rules that are
used further in the
+     * pipeline to locate the resource to be retrieved and rendered.
+     * @see ProfilingRule#apply(org.apache.jetspeed.request.RequestContext, Profiler)
+     *
+     * @param context the request context holding runtime request parameters to be normalized
+     * @param locatorName the commonly known name of the profile locator such as {@link ProfileLocator#PAGE_LOCATOR}
+     * @return a new  object or null if failed to find a appropriate locator.
+     * @throws ProfilerException
      */
     ProfileLocator getDefaultProfile(RequestContext context, String locatorName) throws ProfilerException;
 
     /**
-     *  Get the Profile object using the request parameters and the rule.
+     *  Retrieve a profile locator {@link ProfileLocator} for the given runtime parameters
represented in the request
+     *  context and for the provided {@link ProfilingRule}.
+     * <p>
+     * The algorithm for this method takes the {@link ProfilingRule} directly and applies
that rule
+     * to return a normalized profile. The profile locator holds the normalized set of rules
that are used further in the
+     * pipeline to locate the resource to be retrieved and rendered.
+     * @see ProfilingRule#apply(org.apache.jetspeed.request.RequestContext, Profiler)
      *
-     * @param context The request context
-     * @return a new Profile Locator object or null if failed to find a appropriate locator.
-     */        
+     * @param context The request context  holding runtime request parameters to be normalized
+     * @param rule The ProfilingRule to apply and find a {@link ProfileLocator}
+     * @return a new ProfileLocator object or null if failed to find a appropriate locator.
+     * @throws ProfilerException
+     */
     ProfileLocator getProfile(RequestContext context, ProfilingRule rule) throws ProfilerException;
       
     
     /**
       * Creates a new ProfileLocator object that can be managed by
       * the current Profiler implementation
       *
-      * @param context The request context
+      * @param context The request context containing runtime parameters to determine which
locator to create
       * @return A new ProfileLocator object
       */
     ProfileLocator createLocator(RequestContext context);
@@ -89,7 +126,7 @@ public interface Profiler
     /**
      * For a given principal, lookup the associated profiling rule to that principal name.
      * 
-     * @param principal Lookup the profiling rule based on this principal. 
+     * @param principal Lookup the profiling rule based on this principal
      * @param locatorName the unique name of a locator for this principal/rule/locator 
      * @return The rule found or null if not found
      */
@@ -97,8 +134,7 @@ public interface Profiler
 
     /**
      * For a given principal, associate a profiling rule to that principal name.
-     * TODO: this API should be secured and require admin role
-     * 
+     *
      * @param principal
      *            Lookup the profiling rule based on this principal.
      * @param rule
@@ -126,7 +162,7 @@ public interface Profiler
      * Given a rule id, get the rule
      * 
      * @param id
-     * @return the rule
+     * @return the rule associated the given id
      */
     ProfilingRule getRule(String id);
 
@@ -144,32 +180,27 @@ public interface Profiler
      * For a given principal, find all supported locators and return a
      * collection of principal rules.
      * 
-     * @param principal
-     *            The given principal.
+     * @param principal The given principal such as a user principal
      * @return collection of PrincipalRules
      */
     Collection<PrincipalRule> getRulesForPrincipal(Principal principal);
 
     /**
-     * Gets all supported locators for a principal.
+     * Retrieves a map of all supported locators for a principal, mapping locator name to
profile locator
      * 
-     * @param context
-     * @param principal
-     * @return
+     * @param context the request context  holding runtime request parameters to be normalized
+     * @param principal the given principal such a User Principal
+     * @return a map of locator names mapping to profile locators
      * @throws ProfilerException
      */
     Map<String,ProfileLocator> getProfileLocators(RequestContext context, Principal
principal)
             throws ProfilerException;
 
     /**
-     * 
-     * <p>
-     * getDefaultProfileLocators
-     * </p>
-     * Gets all the supported locators for the DEFAULT_RULE_PRINCIPAL
-     * 
-     * @param context
-     * @return
+     * Retrieves a map of all default locators, mapping locator name to profile locator
+     *
+     * @param context the request context  holding runtime request parameters to be normalized
+     * @return a map of locator names mapping to profile locators
      * @throws ProfilerException
      */
     Map<String,ProfileLocator> getDefaultProfileLocators(RequestContext context)
@@ -177,58 +208,65 @@ public interface Profiler
 
     /*
      * Persist a profiling rule to the persistent store.
-     * 
+     *
+     * @param rule the profiling rule to be persisted
+     * @throws ProfilerException
      */
     void storeProfilingRule(ProfilingRule rule) throws ProfilerException;
 
     /*
      * Deletes a profiling rule from the persistent store.
-     * 
+     *
+     * @param rule the profiling rule to be deleted
+     * @throws ProfilerException
      */
     void deleteProfilingRule(ProfilingRule rule) throws ProfilerException;
 
     /*
      * Persist a principal rule to the persistent store.
-     * 
+     *
+     * @param rule the principal rule to be deleted
+     * @throws ProfilerException
      */
     void storePrincipalRule(PrincipalRule rule) throws ProfilerException;
 
     /*
      * Deletes a principal rule from the persistent store.
-     * 
+     *
+     * @param rule the principal rule to be deleted
+     * @throws ProfilerException
      */
     void deletePrincipalRule(PrincipalRule rule) throws ProfilerException;
 
     /**
-     * Factory for Profiling Rule. The boolean argument specifies whether to
+     * Factory for creating Profiling Rules. The boolean argument specifies whether to
      * obtain a new instance of a standard profiling rule or of a fallback rule.
      * 
      * @param standard
      *            true if standard rule is requested, false if fallback
      * @return New instance of a (standard or fallback) Profiling Rule
      * @throws ClassNotFoundException
-     *             if the beanfactory couldn't instantiate the bean
+     *             if the bean factory couldn't instantiate the bean
      */
     public ProfilingRule createProfilingRule(boolean standard)
             throws ClassNotFoundException;
 
     /**
      * Factory for PrincipalRule, the container to connect profiling rule and
-     * (user) prinicpal
-     * <p>
+     * (user) principals
+     *
      * Replaces the previous Class.forName and .instantiate logic with the
      * Spring based factory.
      * 
      * @return New instance of a principal rule
      * @throws ClassNotFoundException
-     *             if the beanfactory couldn't instantiate the bean
+     *             if the bean factory couldn't instantiate the bean
      */
     public PrincipalRule createPrincipalRule() throws ClassNotFoundException;
 
     /**
-     * Factory for Rule Criterion
-     * <p>
-     * 
+     * Factory for creating Rule Criterion
+     *
      * @return New instance of a rule criterion
      * @throws ClassNotFoundException
      *             if the beanfactory couldn't instantiate the bean
@@ -239,8 +277,9 @@ public interface Profiler
     
     /**
      * Resets the default rule for this portal
+     *
      * @param defaultRule
-     *            The default rule to set.
+     *            The name of the rule to set as default
      */
     public void setDefaultRule(String defaultRule);
 

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/PrincipalRule.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/PrincipalRule.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/PrincipalRule.java
(original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/PrincipalRule.java
Sat Aug  3 23:35:19 2013
@@ -66,8 +66,7 @@ public interface PrincipalRule extends S
      * @param name The name of the locator in this association.
      */        
     void setLocatorName(String name);
-    
-        
+
     /**
      * Gets the profiling rule associated with the principal name 
      * 

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/ProfileResolvers.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/ProfileResolvers.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/ProfileResolvers.java
(original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/ProfileResolvers.java
Sat Aug  3 23:35:19 2013
@@ -19,16 +19,26 @@ package org.apache.jetspeed.profiler.rul
 import java.util.Map;
 
 /**
- * Spring component to hold criterion resolvers for building profiling rules.
+ * Holds the mapping of resolver names to criterion resolvers for building profiling rules.
This component is configured
+ * in the Jetspeed configuration
  *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id: PrincipalRule.java 188415 2005-03-23 22:15:25Z ate $
  */
 public interface ProfileResolvers 
 {
+    /**
+     * Lookup a resolver for a given resolver name
+     *
+     * @param resolverName the name of the resolver to lookup
+     * @return the found resolver or if not found, null
+     */
     RuleCriterionResolver get(String resolverName);
+
     /**
-     * return the map of resolver
+     * Returns a representation of all resolvers and their associated names in a map
+     *
+     * @return the map of resolver names mapped to resolvers
      */
     Map<String,RuleCriterionResolver> getResolvers();
 }

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/ProfilingRule.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/ProfilingRule.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/ProfilingRule.java
(original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/ProfilingRule.java
Sat Aug  3 23:35:19 2013
@@ -16,12 +16,13 @@
  */
 package org.apache.jetspeed.profiler.rules;
 
-import java.io.Serializable;
-import java.util.Collection;
 import org.apache.jetspeed.profiler.ProfileLocator;
 import org.apache.jetspeed.profiler.Profiler;
 import org.apache.jetspeed.request.RequestContext;
 
+import java.io.Serializable;
+import java.util.Collection;
+
 /**
  * A ProfilingRule defines a list of criteria used when evaluating a request
  * to determine the location of a specific resource. Profiling rules are 
@@ -73,20 +74,20 @@ public interface ProfilingRule extends S
     public final static String STANDARD_ROLE_FALLBACK = "roles";
 
     /**
-     * Given a criterion name, look up a value resolver
+     * Given a criterion name, look up a resolver
      * 
      * @param name The name of the criterion
-     * @return
+     * @return the resolver if found, otherwise null
      */
     RuleCriterionResolver getResolver(String name);    
     
     /**
      * Applying the profiling rule generates a generic profile locator.
      * With this locator we can then locate a profiling resource.
-     * 
-     * @param context
-     * @param service
-     * @return
+     *
+     * @param context the request context holding runtime request parameters to be normalized
+     * @param service the profiler service to be called back
+     * @return the generated profiler locator for this context
      */
     ProfileLocator apply(RequestContext context, Profiler service);
     
@@ -95,7 +96,7 @@ public interface ProfilingRule extends S
      * Each criteria consists of a normalized property/attribute/parameter 
      * associated with a request type.
      * 
-     * @return a sorted map of rule criteria.
+     * @return a sorted map of rule criteria
      */         
     Collection<RuleCriterion> getRuleCriteria();
                      
@@ -129,7 +130,7 @@ public interface ProfilingRule extends S
     
     /**
      * Get the implementing classname of this rule from the database.
-     * The class must exist in the hiearchy and in fact refers to itself when instantiated.
+     * The class must exist in the hierarchy and in fact refers to itself when instantiated.
      * 
      * @return The classname of this instance.
      */
@@ -137,13 +138,24 @@ public interface ProfilingRule extends S
     
     /**
      * Sets the implementing classname of this rule from the database.
-     * The class must exist in the hiearchy and in fact refers to itself when instantiated.
+     * The class must exist in the hierarchy and in fact refers to itself when instantiated.
      * 
      * @param classname The classname of this instance.
      */
     void setClassname(String classname);
-    
+
+    /**
+     * Returns the mapping of resolver names to criterion resolvers for building profiling
rules
+     *
+     * @return the mapping of resolver names to criterion resolvers
+     */
     ProfileResolvers getResolvers();
+
+    /**
+     * Sets the mapping of resolver names to criterion resolvers for building profiling rules
+     *
+     * @param resolvers the mapping of resolver names to criterion resolvers
+     */
     void setResolvers(ProfileResolvers resolvers);
                            
 }

Modified: portals/jetspeed-2/portal/trunk/jetspeed-portal-resources/src/main/resources/assembly/administration.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-portal-resources/src/main/resources/assembly/administration.xml?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-portal-resources/src/main/resources/assembly/administration.xml
(original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-portal-resources/src/main/resources/assembly/administration.xml
Sat Aug  3 23:35:19 2013
@@ -97,6 +97,9 @@
     <property name="passwordGenerator">
       <ref bean="org.apache.jetspeed.administration.PasswordGenerator"/>
     </property>
+    <property name="configuration">
+      <ref bean="PortalConfiguration" />
+    </property>
   </bean>
 
   <bean id="PortalAdministration" parent="baseTransactionProxy">

Modified: portals/jetspeed-2/portal/trunk/pom.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/pom.xml?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/pom.xml (original)
+++ portals/jetspeed-2/portal/trunk/pom.xml Sat Aug  3 23:35:19 2013
@@ -232,7 +232,7 @@
     <commons-betwixt.version>0.8</commons-betwixt.version>
     <commons-codec.version>1.3</commons-codec.version>
     <commons-collections.version>3.2</commons-collections.version>
-    <commons-configuration.version>1.6</commons-configuration.version>
+    <commons-configuration.version>1.9</commons-configuration.version>
     <commons-dbcp.version>1.2.2</commons-dbcp.version>
     <commons-digester.version>1.8</commons-digester.version>
     <commons-fileupload.version>1.2</commons-fileupload.version>



---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org


Mime
View raw message