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:tay...@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:tay...@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-unsubscr...@portals.apache.org For additional commands, e-mail: jetspeed-dev-h...@portals.apache.org
