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 [1/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
Author: taylor
Date: Sat Aug  3 23:35:19 2013
New Revision: 1510080

URL: http://svn.apache.org/r1510080
Log:
JS2-874: more java collections generic conversion of jetspeed-api, updating javadocs

Modified:
    portals/jetspeed-2/portal/trunk/components/jetspeed-cm/pom.xml
    portals/jetspeed-2/portal/trunk/components/jetspeed-locator/src/main/java/org/apache/jetspeed/profiler/impl/ProfileLocatorPropertyImpl.java
    portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/PortalAdministrationImpl.java
    portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/PortalConfigurationImpl.java
    portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/aggregator/impl/PortletRendererImpl.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/AdministrationEmailException.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PasswordGenerator.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalAdministration.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalAuthenticationConfiguration.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalConfiguration.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalConfigurationConstants.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/RegistrationException.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/Aggregator.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/FailedToRenderFragmentException.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PageAggregator.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletAccessDeniedException.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletAggregator.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletContent.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletRenderer.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/RenderingJob.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/UnknownPortletDefinitionException.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/UnrenderedContentException.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/Worker.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/WorkerMonitor.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/pipeline/valve/Valve.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/ProfileLocator.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/ProfileLocatorProperty.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/Profiler.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/PrincipalRule.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/ProfileResolvers.java
    portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/rules/ProfilingRule.java
    portals/jetspeed-2/portal/trunk/jetspeed-portal-resources/src/main/resources/assembly/administration.xml
    portals/jetspeed-2/portal/trunk/pom.xml

Modified: portals/jetspeed-2/portal/trunk/components/jetspeed-cm/pom.xml
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/components/jetspeed-cm/pom.xml?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/components/jetspeed-cm/pom.xml (original)
+++ portals/jetspeed-2/portal/trunk/components/jetspeed-cm/pom.xml Sat Aug  3 23:35:19 2013
@@ -88,6 +88,10 @@
             <artifactId>commons-configuration</artifactId>
         </dependency>
         <dependency>
+            <groupId>commons-digester</groupId>
+            <artifactId>commons-digester</artifactId>
+        </dependency>
+        <dependency>
             <groupId>commons-dbcp</groupId>
             <artifactId>commons-dbcp</artifactId>
         </dependency>

Modified: portals/jetspeed-2/portal/trunk/components/jetspeed-locator/src/main/java/org/apache/jetspeed/profiler/impl/ProfileLocatorPropertyImpl.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/components/jetspeed-locator/src/main/java/org/apache/jetspeed/profiler/impl/ProfileLocatorPropertyImpl.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/components/jetspeed-locator/src/main/java/org/apache/jetspeed/profiler/impl/ProfileLocatorPropertyImpl.java (original)
+++ portals/jetspeed-2/portal/trunk/components/jetspeed-locator/src/main/java/org/apache/jetspeed/profiler/impl/ProfileLocatorPropertyImpl.java Sat Aug  3 23:35:19 2013
@@ -64,7 +64,7 @@ public class ProfileLocatorPropertyImpl 
     }
 
     /**
-     * @param string
+     * @param value
      */
     public void setValue(String value)
     {

Modified: portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/PortalAdministrationImpl.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/PortalAdministrationImpl.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/PortalAdministrationImpl.java (original)
+++ portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/PortalAdministrationImpl.java Sat Aug  3 23:35:19 2013
@@ -16,8 +16,6 @@
  */
 package org.apache.jetspeed.administration;
 
-import org.apache.commons.configuration.Configuration;
-import org.apache.jetspeed.Jetspeed;
 import org.apache.jetspeed.PortalReservedParameters;
 import org.apache.jetspeed.exception.JetspeedException;
 import org.apache.jetspeed.mockobjects.MockHttpServletRequest;
@@ -34,8 +32,14 @@ import org.apache.jetspeed.profiler.Prof
 import org.apache.jetspeed.profiler.Profiler;
 import org.apache.jetspeed.profiler.rules.ProfilingRule;
 import org.apache.jetspeed.request.RequestContext;
-import org.apache.jetspeed.security.*;
+import org.apache.jetspeed.security.GroupManager;
+import org.apache.jetspeed.security.JSSubject;
+import org.apache.jetspeed.security.PasswordCredential;
+import org.apache.jetspeed.security.RoleManager;
+import org.apache.jetspeed.security.SecurityAttributes;
 import org.apache.jetspeed.security.SecurityException;
+import org.apache.jetspeed.security.User;
+import org.apache.jetspeed.security.UserManager;
 import org.apache.velocity.VelocityContext;
 import org.apache.velocity.app.VelocityEngine;
 import org.slf4j.Logger;
@@ -51,7 +55,11 @@ import java.io.FileReader;
 import java.io.StringWriter;
 import java.security.Principal;
 import java.security.PrivilegedAction;
-import java.util.*;
+import java.util.Collection;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
 
 /**
  * PortalAdministrationImpl
@@ -71,7 +79,7 @@ public class PortalAdministrationImpl im
     /**
      * administration services
      */
-    protected Configuration config;
+    protected PortalConfiguration configuration;
     protected UserManager userManager;
     protected RoleManager roleManager;
     protected GroupManager groupManager;
@@ -132,14 +140,20 @@ public class PortalAdministrationImpl im
         }
     }
 
-    public void start() {
-        this.config = (Configuration) Jetspeed.getComponentManager().getComponent("portal_configuration");
+    public PortalConfiguration getConfiguration() {
+        return configuration;
+    }
 
-        this.defaultRoles = config.getList(PortalConfigurationConstants.REGISTRATION_ROLES_DEFAULT);
-        this.defaultGroups = config.getList(PortalConfigurationConstants.REGISTRATION_GROUPS_DEFAULT);
+    public void setConfiguration(PortalConfiguration configuration) {
+        this.configuration = configuration;
+    }
+
+    public void start() {
+        this.defaultRoles = configuration.getList(PortalConfigurationConstants.REGISTRATION_ROLES_DEFAULT);
+        this.defaultGroups = configuration.getList(PortalConfigurationConstants.REGISTRATION_GROUPS_DEFAULT);
 
-        String[] profileRuleNames = config.getStringArray(PortalConfigurationConstants.PROFILER_RULE_NAMES_DEFAULT);
-        String[] profileRuleValues = config.getStringArray(PortalConfigurationConstants.PROFILER_RULE_VALUES_DEFAULT);
+        String[] profileRuleNames = configuration.getStringArray(PortalConfigurationConstants.PROFILER_RULE_NAMES_DEFAULT);
+        String[] profileRuleValues = configuration.getStringArray(PortalConfigurationConstants.PROFILER_RULE_VALUES_DEFAULT);
         defaultRules = new HashMap<String, String>();
         if (profileRuleNames != null && profileRuleValues != null) {
             for (int ix = 0; ix < ((profileRuleNames.length < profileRuleValues.length) ? profileRuleNames.length : profileRuleValues.length); ix++) {
@@ -147,9 +161,9 @@ public class PortalAdministrationImpl im
             }
         }
         this.folderTemplate =
-                config.getString(PortalConfigurationConstants.PSML_TEMPLATE_FOLDER);
-        this.adminUser = config.getString(PortalConfigurationConstants.USERS_DEFAULT_ADMIN);
-        this.adminRole = config.getString(PortalConfigurationConstants.ROLES_DEFAULT_ADMIN);
+                configuration.getString(PortalConfigurationConstants.PSML_TEMPLATE_FOLDER);
+        this.adminUser = configuration.getString(PortalConfigurationConstants.USERS_DEFAULT_ADMIN);
+        this.adminRole = configuration.getString(PortalConfigurationConstants.ROLES_DEFAULT_ADMIN);
     }
 
     /* (non-Javadoc)
@@ -373,7 +387,7 @@ public class PortalAdministrationImpl im
                           Map<String, String> userAttributes)
             throws AdministrationEmailException {
 
-        String from = config.getString(PortalConfigurationConstants.EMAIL_SENDER);
+        String from = configuration.getString(PortalConfigurationConstants.EMAIL_SENDER);
         String subject = localizedSubject;
         String to = emailAddress;
         String text = mergeEmailTemplate(portletConfig, userAttributes, "map", localizedTemplatePath);
@@ -472,7 +486,7 @@ public class PortalAdministrationImpl im
     }
 
 
-    Map<String, Map<String, String>> forgottenPasswordData = new HashMap<String, Map<String, String>>();
+    final Map<String, Map<String, String>> forgottenPasswordData = new HashMap<String, Map<String, String>>();
 
     /* (non-Javadoc)
      * @see org.apache.jetspeed.administration.PortalAdministration#getNewLoginInfo(java.lang.String)
@@ -507,11 +521,9 @@ public class PortalAdministrationImpl im
         }
 
         Principal principal = request.getUserPrincipal();
-
-        if (principal != null) {
+        if (null != principal) {
             return adminUser.equals(principal.getName());
         }
-
         return false;
     }
 
@@ -519,7 +531,6 @@ public class PortalAdministrationImpl im
         if (adminRole == null) {
             throw new IllegalStateException("PortalAdministration component is not started or misconfigured for the default admin role.");
         }
-
         return request.isUserInRole(adminRole);
     }
 
@@ -563,7 +574,7 @@ public class PortalAdministrationImpl im
      * @throws Exception
      */
     private String invokeGetUserFolderPath(final User user, final Locale locale, final String serverName) throws Exception {
-        if (config.getString(PortalConfigurationConstants.JETUI_CUSTOMIZATION_METHOD).equals(PortalConfigurationConstants.JETUI_CUSTOMIZATION_AJAX)) {
+        if (configuration.getString(PortalConfigurationConstants.JETUI_CUSTOMIZATION_METHOD).equals(PortalConfigurationConstants.JETUI_CUSTOMIZATION_AJAX)) {
             return Folder.USER_FOLDER + user.getName();
         }
         Object doneAs = JSSubject.doAsPrivileged(userManager.getSubject(user), new PrivilegedAction() {
@@ -654,4 +665,5 @@ public class PortalAdministrationImpl im
         PortalSiteSessionContext sessionContext = portalSite.newSessionContext();
         return sessionContext.newRequestContext(locators, user.getName());
     }
+
 }

Modified: portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/PortalConfigurationImpl.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/PortalConfigurationImpl.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/PortalConfigurationImpl.java (original)
+++ portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/administration/PortalConfigurationImpl.java Sat Aug  3 23:35:19 2013
@@ -16,11 +16,11 @@
  */
 package org.apache.jetspeed.administration;
 
+import org.apache.commons.configuration.Configuration;
+
 import java.util.Iterator;
 import java.util.List;
 
-import org.apache.commons.configuration.Configuration;
-
 
 /**
  * Portal Configuration
@@ -82,7 +82,7 @@ public class PortalConfigurationImpl imp
         return configuration.getInt(key);        
     }
 
-    public List getList(String key)
+    public List<Object> getList(String key)
     {
         return configuration.getList(key);
     }

Modified: portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/aggregator/impl/PortletRendererImpl.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/aggregator/impl/PortletRendererImpl.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/aggregator/impl/PortletRendererImpl.java (original)
+++ portals/jetspeed-2/portal/trunk/components/jetspeed-portal/src/main/java/org/apache/jetspeed/aggregator/impl/PortletRendererImpl.java Sat Aug  3 23:35:19 2013
@@ -16,16 +16,6 @@
  */
 package org.apache.jetspeed.aggregator.impl;
 
-import java.util.ArrayList;
-import java.util.Collection;
-import java.util.Iterator;
-import java.util.List;
-
-import javax.portlet.PortletMode;
-import javax.portlet.WindowState;
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-
 import org.apache.jetspeed.JetspeedActions;
 import org.apache.jetspeed.PortalReservedParameters;
 import org.apache.jetspeed.aggregator.PortletAccessDeniedException;
@@ -49,6 +39,15 @@ import org.apache.pluto.container.Portle
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import javax.portlet.PortletMode;
+import javax.portlet.WindowState;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.List;
+
 /**
  * <h4>PortletRendererService <br />
  * Jetspeed-2 Rendering service.</h4>
@@ -301,8 +300,9 @@ public class PortletRendererImpl impleme
     /**
      * Retrieve cached content, if content retrieved successfully return true, if no content found return false
      * @param requestContext
-     * @param fragment
      * @param portletWindow
+     * @param expiration
+     * @param portletDefinition
      * @return true when content found, otherwise false
      */
     protected boolean retrieveCachedContent(RequestContext requestContext, 

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/AdministrationEmailException.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/AdministrationEmailException.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/AdministrationEmailException.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/AdministrationEmailException.java Sat Aug  3 23:35:19 2013
@@ -37,9 +37,9 @@ public class AdministrationEmailExceptio
         super(keyedMessage, nested);
     }
 
-    public AdministrationEmailException(KeyedMessage typedMessage)
+    public AdministrationEmailException(KeyedMessage keyedMessage)
     {
-        super(typedMessage);
+        super(keyedMessage);
     }
 
     public AdministrationEmailException(String msg, Throwable nested)

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PasswordGenerator.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PasswordGenerator.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PasswordGenerator.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PasswordGenerator.java Sat Aug  3 23:35:19 2013
@@ -17,9 +17,17 @@
 package org.apache.jetspeed.administration;
 
 /**
+ * Pluggable password generator service for auto-creating passwords in Jetspeed Administration. A simple password
+ * generator is provided by Jetspeed. This service can be wired in through Spring and replaced by your own algorithm.
+ *
  * @version $Id$
  */
 public interface PasswordGenerator
 {
+    /**
+     * Call this method to generate a new password following the credential policy of the Password Generator service
+     *
+     * @return a newly generated password
+     */
     String generatePassword();
 }
\ No newline at end of file

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalAdministration.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalAdministration.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalAdministration.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalAdministration.java Sat Aug  3 23:35:19 2013
@@ -28,11 +28,12 @@ import java.util.Map;
 /**
  * PortalAdministration
  * 
- * Aggregate portal administration functions:
- *  - Emails
- *  - Registration
- *  - Password Generation
- * 
+ * Aggregate portal administration functions are controlled with this service. Administrative services include:
+ * <ul>
+ *  <li>- Emails delivery services</li>
+ *  <li>- User Registration services and options</li>
+ *  <li>- Password Generation services</li>
+ * </ul>
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id: $
  */
@@ -57,7 +58,8 @@ public interface PortalAdministration
      *               if subsite not specified
      * @param serverName Server name used to compute new user folder path
      *                   if subsite not specified
-     * @since 2.1.2              
+     * @throws RegistrationException
+     * @since 2.1.2
      */
      void registerUser(
             String userName, 
@@ -72,6 +74,23 @@ public interface PortalAdministration
             String serverName)
         throws RegistrationException;
 
+    /**
+     * Registers and creates a new user, assigning userInfo, roles, groups,
+     * profiling rules and a folder template. If any values are null, defaults
+     * are used from the system wide configuration.
+     *
+     * @param userName Unique user principal identifier
+     * @param password Password for this user
+     * @param roles A list of roles to assign to this user
+     * @param groups A list of groups to assign to this user
+     * @param userInfo Portlet API User Information Attributes name value pairs (PLT.D)
+     * @param rules A map of name value pairs of profiling rules.
+     *              Well known rules names are 'page' and 'menu'
+     * @param template The full PSML path name of a folder to be deep
+     *               copied as the new user's set of folders, pages, links
+     * @param subsiteFolder The subsite folder to place the new user in
+     * @throws RegistrationException
+     */
     void registerUser(String userName, 
                       String password, 
                       List<String> roles,
@@ -82,6 +101,22 @@ public interface PortalAdministration
                       String subsiteFolder)
         throws RegistrationException;
 
+    /**
+     * Registers and creates a new user, assigning userInfo, roles, groups,
+     * profiling rules and a folder template. If any values are null, defaults
+     * are used from the system wide configuration.
+     *
+     * @param userName Unique user principal identifier
+     * @param password Password for this user
+     * @param roles A list of roles to assign to this user
+     * @param groups A list of groups to assign to this user
+     * @param userInfo Portlet API User Information Attributes name value pairs (PLT.D)
+     * @param rules A map of name value pairs of profiling rules.
+     *              Well known rules names are 'page' and 'menu'
+     * @param template The full PSML path name of a folder to be deep
+     *               copied as the new user's set of folders, pages, links
+     * @throws RegistrationException
+     */
     void registerUser(String userName, 
             String password, 
             List<String> roles,
@@ -94,38 +129,42 @@ public interface PortalAdministration
     /**
      * Register a new user using all default values
      * 
-     * @param userName
-     * @param password
+     * @param userName Unique user principal identifier
+     * @param password Password for this user
+     * @throws RegistrationException
      */
     void registerUser(String userName, String password)
         throws RegistrationException;
     
     /**
-     * Generate a unique password
+     * Generate a unique password following the credential policy of the Password Generator service
      * 
-     * @return unique password
+     * @return the unique password
      */
     String generatePassword();
     
     /**
-     * Helper to send an email to a recipient
+     * Using the portal's email configuration settings, sends an email to a mail recipient. Does a mail merge using
+     * the <code>userAttributes</code> parameter for merged values, merging into the mail body from
+     * the configured email <code>template</code>
      *
      * @param portletConfig portlet configuration
      * @param emailAddress the email address of the recipient
      * @param localizedSubject the subject of the email as a localized string
-     * @param templatePath path to templates
-     * @parm userAttributes map of user attributes
+     * @param template portal relative path to the template used to do the mail merge
+     * @param userAttributes map of user attributes to substitute into template
      * @throws AdministrationEmailException
      */
      void sendEmail(PortletConfig portletConfig,
                           String emailAddress, 
                           String localizedSubject, 
-                          String templatePath,
+                          String template,
                           Map<String,String> userAttributes)
         throws AdministrationEmailException;
     
     /**
-     * Helper to send an email to a recipient without the portal default sender, and without mail merge
+     * Using the portal's email configuration, sends a simple email to a mail recipient. Does not do a mail merge,
+     * simply sends the <code>text</code> parameter as the mail body.
      * 
      * @param from the email address of the sender
      * @param subject the subject of the email
@@ -136,26 +175,26 @@ public interface PortalAdministration
      void sendEmail(String from, String subject, String to, String text) throws AdministrationEmailException;
     
     /**
-     * Lookup a user given an email address
+     * Lookup a Jetspeed user, given an email address
      * 
      * @param email Given email address
-     * @return a Jetspeed <code>User</code>, or throw exception if not found
+     * @return a Jetspeed User or throw exception if not found
      * @throws AdministrationEmailException
      */
      User lookupUserFromEmail(String email)
         throws AdministrationEmailException;
     
     /**
-     * Provide a common way to get portal URLs
-     * Necessary for generating return URLs for features such as 
-     * forgotten password. The URL generated will be a combination
-     * of the Jetspeed base URL plus the path parameter appended 
+     * Provides a common way to generating portal URLs.
+     * Generates return URLs for features such as forgotten password. The URL generated will be a combination
+     * of the Jetspeed base URL plus the path parameter appended.  For example, the following idiom
+     * <pre>
      * Example:
      *  base URL = http://www.apache.org/jetspeed/portal
      *      path = /system/forgotten-password.psml
      *  Returns: 
      *     http://www.apache.org/jetspeed/portal/system/forgotten-password.psml
-     *     
+     * </pre>
      * @param request The portlet request.
      * @param response The portlet response, used to encode the path
      * @param path The relative path to a portal resource
@@ -165,59 +204,78 @@ public interface PortalAdministration
     
     
     /**
-     * @param guid    The ID which is passed throughte URL to the user
-     * @return
+     * Administrative portlets, like the forgotten password admin, need to track login information such as
+     * temporary links to recovery temporary passwords. This method takes a <code>GUID</code> and looks up
+     * the application specific login information associated with that GUID. This information is normally
+     * temporary and may have a short-lived lifespan.
+     *
+     * @param guid the temporary identifier to associate with the login information
+     * @return the new login information associated with the <code>guid</code>
      */
      Map<String,String> getNewLoginInfo(String guid);
 
     /**
-     * @param guid    the ID which is passed through the URL to the user.. 
-     * @param info    a Map, info from which will be used to reset the password
-     *                the password in this case is NOT encrypted, but this should probably
-     *                change if this information is stored on disk... ie a database
+     * Administrative portlets, like the forgotten password admin, need to track login information such as
+     * temporary links to recovery temporary passwords. This method takes a <code>GUID</code> and stores the
+     * the provided application specific login information associated with that GUID. This information is normally
+     * temporary and may have a short-lived lifespan.
+     *
+     * @param guid    the temporary identifier to associate with the login information
+     * @param info    a <code>Map</code> of login information specific to application
      */
      void putNewLoginInfo(String guid, Map<String,String> info);
     
     /**
-     * @param guid    the ID which will be removed from the storage when the info is no longer valid
+     * Administrative portlets, like the forgotten password admin, need to track login information such as
+     * temporary links to recovery temporary passwords. This method takes a <code>GUID</code> and removes
+     * application specific login information associated with that GUID. This information is normally
+     * temporary and may have a short-lived lifespan.
+     *
+     * @param guid the temporary identifier to associate with the login information
      */
      void removeNewLoginInfo(String guid);
     
     /**
-     * Returns true if the current request user principal's name is the name of the portal admin user.
-     * @param request
-     * @return
+     * Returns true if the current request is made by the special portal admin user.
+     *
+     * @see PortalConfigurationConstants#USERS_DEFAULT_ADMIN
+     * @param request the PortletRequest to check the user principal on
+     * @return <tt>true</tt> if this request is made by the portal admin user
      */
     boolean isAdminUser(PortletRequest request);
     
     /**
-     * Returns true if the current request user principal is in the portal admin role.
-     * @param request
-     * @return
+     * Returns true if the current request user principal is made by a user in the portal admin role
+     *
+     * @see PortalConfigurationConstants#ROLES_DEFAULT_ADMIN
+     * @param request the PortletRequest to check the user principal on
+     * @return <tt>true</tt> if this request is made by a user with the portal admin role
      */
     boolean isUserInAdminRole(PortletRequest request);
     
     /**
-     * Returns PSML user folder path for specified user by
-     * running full profiler and portal site rules.
+     * Returns a PSML path to the root user folder for the specified user by
+     * running the full profiler and portal site rules.
      * 
-     * @param userName existing portal user name
+     * @param userName the portal user name
      * @param locale optional locale, (defaults to system locale, for language
      *               profiling rules)
      * @param serverName server name, (required for subsite profiling rules)
-     * @return PSML user folder path
+     * @return a normalized PSML user folder path
+     * @deprecated
      */
     String getUserFolderPath(String userName, Locale locale, String serverName);
 
     /**
-     * Returns PSML base folder path for specified user by
-     * running full profiler and portal site rules.
+     * Returns a PSML path to the base user folder for the specified user by
+     * running the full profiler and portal site rules.
      * 
      * @param userName existing portal user name
      * @param locale optional locale, (defaults to system locale, for language
      *               profiling rules)
      * @param serverName server name, (required for subsite profiling rules)
-     * @return PSML base folder path
+     * @return a normalized PSML user folder path
+     * @deprecated
      */
     String getBaseFolderPath(String userName, Locale locale, String serverName);
 }

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalAuthenticationConfiguration.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalAuthenticationConfiguration.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalAuthenticationConfiguration.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalAuthenticationConfiguration.java Sat Aug  3 23:35:19 2013
@@ -18,7 +18,15 @@ package org.apache.jetspeed.administrati
 
 
 /**
- * PortalAdministration
+ * Portal Authentication Configuration for advanced settings on authentication activities going beyond default behavior.
+ * Extended authentication behaviors include:
+ * <ul>
+ *     <li>Create new session upon logging on. The default behavior is to create a new session.</li>
+ *     <li>Hard limit on session expiration. Overrides Servlet API inactivity-based session expiration
+ *         with hard limit expiration (ignores inactivity)</li>
+ *     <li>Configure the hard limit timeout expiration redirect URL</li>
+ * </ul>
+ * These settings are configurable via the portal's spring configuration
  * 
  * 
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
@@ -28,44 +36,60 @@ package org.apache.jetspeed.administrati
 public interface PortalAuthenticationConfiguration
 {   
     /**
-     * Is the session hard limit expiration feature enabled
-     * @return
+     *  Determine if the hard session timeout limit setting {@link #getMaxSessionHardLimit()} is turned on or not
+     *  in portal configuration. Hard limits override the Servlet API inactivity-based session expiration
+     *  with hard limit expiration (ignores activity-based session invalidation)
+     *
+     *  This setting requires the {@link #isCreateNewSessionOnLogin()} setting being enabled.
+     *
+     * @return whether {@link #getMaxSessionHardLimit()} setting is enabled
      */
     public boolean isMaxSessionHardLimitEnabled();
     
     /**
-     * hard session timeout limit in seconds, regardless of (in)activity
-     * 
-     * @return
+     *  The max value in seconds for session invalidation. Hard limits expirations override the Servlet API inactivity-based
+     *  session expiration with hard limit expiration (ignores activity-based session invalidation)
+     *
+     *  This setting requires the {@link #isCreateNewSessionOnLogin()} setting being enabled.
+     *
+     * @return the max session hard limit expiration value in seconds
      */
     public int getMaxSessionHardLimit();
-    
-    
+
+
     /**
-     * Get the session hard limit in milliseconds
-     * 
-     * @return session hard limit in milliseconds
+     *  The max value in milliseconds for session invalidation. Hard limits expirations override the Servlet API inactivity-based
+     *  session expiration with hard limit expiration (ignores activity-based session invalidation)
+     *
+     *  This setting requires the {@link #isCreateNewSessionOnLogin()} setting being enabled.
+     *
+     * @return the max session hard limit expiration value in milliseconds
      */
     public long getMsMaxSessionHardLimit();
     
     /**
-     * redirect location for hard session expiration, must be used with Max Session Hard Limit turned on
+     * A redirect URL location for hard session expiration,
+     * must be used with Max Session Hard Limit turned on {@link #isMaxSessionHardLimitEnabled()}
+     * This location is usually a logout-related URL
      * 
-     * @return
+     * @return the configured portal-relative redirect URL location
      */
     public String getTimeoutRedirectLocation();
 
     /**
-     * redirect location for hard session expiration, must be used with Max Session Hard Limit turned on
+     * Override the configured portal-relative redirect URL location for hard session expiration,
+     * must be used with Max Session Hard Limit turned on {@link #isMaxSessionHardLimitEnabled()}
+     * This location is usually a logout-related URL
      *  
-     * @param timeoutRedirectLocation
+     * @param timeoutRedirectLocation the new timeout redirect URL
      */
     public void setTimeoutRedirectLocation(String timeoutRedirectLocation);
 
     /**
-     * Should we create new session upon authentication
+     * Retrieve portal configuration setting which determines whether to create new session upon authentication.
+     * The default behavior is to create a new session.
      * 
-     * @return
+     * @return the portal configuration setting determining whether to create new sessions on login
      */
     public boolean isCreateNewSessionOnLogin();
    

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalConfiguration.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalConfiguration.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalConfiguration.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalConfiguration.java Sat Aug  3 23:35:19 2013
@@ -20,33 +20,145 @@ import java.util.Iterator;
 import java.util.List;
 
 /**
- * Portal Configuration
- * 
- * Retrieve basic data types from the jetspeed.properties configuration
- * This is a subset of Commons Configuration functionality
- * Not the best solution wrappering commons configuration, but it does continue 
- * with the requirements of interface-driven development and zero dependencies in API
- * 
+ * Retrieves configuration settings for all basic data types from the read only portal configuration. This configuration
+ * is usually a set of read only property files such as jetspeed.properties and override.properties.
+ *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @since 2.1.2
  * @version $Id: $
  */
 public interface PortalConfiguration
 {
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @return the boolean representation of this setting
+     */
     boolean getBoolean(String key);
-    boolean getBoolean(String key, boolean defaultValue);    
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @param defaultValue if the property is not found, use this default value
+     * @return the boolean representation of this setting
+     */
+    boolean getBoolean(String key, boolean defaultValue);
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @return the string representation of this setting
+     */
     String getString(String key);
-    String getString(String key, String defaultValue);    
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @param defaultValue if the property is not found, use this default value
+     * @return the string representation of this setting
+     */
+    String getString(String key, String defaultValue);
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @return the double representation of this setting
+     */
     double getDouble(String key);
-    double getDouble(String key, double defaultValue);        
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @param defaultValue if the property is not found, use this default value
+     * @return the double representation of this setting
+     */
+    double getDouble(String key, double defaultValue);
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @return the float representation of this setting
+     */
     float getFloat(String key);
-    float getFloat(String key, float defaultValue);        
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @param defaultValue if the property is not found, use this default value
+     * @return the float representation of this setting
+     */
+    float getFloat(String key, float defaultValue);
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @return the integer representation of this setting
+     */
     int getInt(String key);
-    int getInt(String key, int defaultValue);        
-    List getList(String key);    
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @param defaultValue if the property is not found, use this default value
+     * @return the integer representation of this setting
+     */
+    int getInt(String key, int defaultValue);
+
+    /**
+     * Retrieve a list of multivalued portal configuration settings
+     *
+     * @param key the name of the portal configuration setting
+     * @return the list of multivalued values for this setting
+     */
+    List getList(String key);
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @return the long representation of this setting
+     */
     long getLong(String key);
-    long getLong(String key, long defaultValue);        
+
+    /**
+     * Retrieve a portal configuration setting
+     *
+     * @param key the name of the portal configuration setting
+     * @param defaultValue if the property is not found, use this default value
+     * @return the long representation of this setting
+     */
+    long getLong(String key, long defaultValue);
+
+    /**
+     * Retrieve the multivalued string array of portal configuration setting for a given key
+     *
+     * @param key the name of the portal configuration setting
+     * @return the string array multiple values for this setting key
+     */
     String[] getStringArray(String key);
-    Iterator getKeys();
+
+    /**
+     * Retrieve an iterator over the keys of all portal configuration settings
+     *
+     * @return an {@link java.util.Iterator} over the keys for all configuration settings
+     */
+    Iterator<String> getKeys();
+
+    /**
+     * Set a non-persisted (runtime only) configuration setting value for a given key
+     *
+     * @param key the name of the portal configuration setting
+     * @param value the new value to override the existing value for this setting
+     */
     void setString(String key, String value);
 }

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalConfigurationConstants.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalConfigurationConstants.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalConfigurationConstants.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/PortalConfigurationConstants.java Sat Aug  3 23:35:19 2013
@@ -17,9 +17,9 @@
 package org.apache.jetspeed.administration;
 
 /**
- * PortalConfiguration portal configuration contants
- * TODO: integrate Configuration with JMX 
- * 
+ * Portal Configuration constants to read only portal global settings. These constants are the keys in the portal
+ * configuration store jetspeed.properties and override.properties.
+ *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id: $
  */

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/RegistrationException.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/RegistrationException.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/RegistrationException.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/administration/RegistrationException.java Sat Aug  3 23:35:19 2013
@@ -20,7 +20,7 @@ import org.apache.jetspeed.exception.Jet
 import org.apache.jetspeed.i18n.KeyedMessage;
 
 /**
- * Registration-related exceptions
+ * Portal Administration Registration-related exceptions
  * 
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id: $

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/Aggregator.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/Aggregator.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/Aggregator.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/Aggregator.java Sat Aug  3 23:35:19 2013
@@ -16,13 +16,14 @@
  */
 package org.apache.jetspeed.aggregator;
 
-import java.io.IOException;
-
 import org.apache.jetspeed.exception.JetspeedException;
 import org.apache.jetspeed.request.RequestContext;
 
+import java.io.IOException;
+
 /**
- * Basic aggregation interface
+ * Basic aggregation interface. The role of the aggregator service is to abstract the generation of web snippets, such
+ * as portlets, and build a response buffer into the provided request context.
  *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id$
@@ -30,9 +31,10 @@ import org.apache.jetspeed.request.Reque
 public interface Aggregator 
 {
     /**
-     * Builds the portlet set defined in the context into a portlet tree.
+     * Builds the portlet set defined in the context into a portlet tree. The response buffer is also
+     * set into the request context.
      *
-     * @return Unique Portlet Entity ID
+     * @param context the request context holding runtime request parameters to be normalized
      */
     public void build(RequestContext context)
         throws JetspeedException, IOException;

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/FailedToRenderFragmentException.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/FailedToRenderFragmentException.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/FailedToRenderFragmentException.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/FailedToRenderFragmentException.java Sat Aug  3 23:35:19 2013
@@ -19,40 +19,32 @@ package org.apache.jetspeed.aggregator;
 import org.apache.jetspeed.exception.JetspeedException;
 
 /**
- * <p>
- * FailedToRenderFragmentException
- * </p>
- * <p>
+ * Failed to Render Fragment exceptions denote error cases where a particular fragment failed to render during
+ * content aggregation process.
  *
- * </p>
  * @author <a href="mailto:weaver@apache.org">Scott T. Weaver</a>
  * @version $Id$
- *
  */
-public class FailedToRenderFragmentException extends JetspeedException
-{
+public class FailedToRenderFragmentException extends JetspeedException {
 
     /**
-     * 
+     *
      */
-    public FailedToRenderFragmentException()
-    {
+    public FailedToRenderFragmentException() {
         super();
     }
 
     /**
      * @param message
      */
-    public FailedToRenderFragmentException( String message )
-    {
+    public FailedToRenderFragmentException(String message) {
         super(message);
     }
 
     /**
      * @param nested
      */
-    public FailedToRenderFragmentException( Throwable nested )
-    {
+    public FailedToRenderFragmentException(Throwable nested) {
         super(nested);
     }
 
@@ -60,8 +52,7 @@ public class FailedToRenderFragmentExcep
      * @param msg
      * @param nested
      */
-    public FailedToRenderFragmentException( String msg, Throwable nested )
-    {
+    public FailedToRenderFragmentException(String msg, Throwable nested) {
         super(msg, nested);
     }
 

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PageAggregator.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PageAggregator.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PageAggregator.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PageAggregator.java Sat Aug  3 23:35:19 2013
@@ -16,19 +16,28 @@
  */
 package org.apache.jetspeed.aggregator;
 
-import java.io.IOException;
-
 import org.apache.jetspeed.exception.JetspeedException;
 import org.apache.jetspeed.om.page.ContentFragment;
 import org.apache.jetspeed.request.RequestContext;
 
+import java.io.IOException;
+
 /**
- * Page aggregation handles pipeline requests for pages of portlets.
+ * Defines the interface for rendering content for a page. Page aggregation handles pipeline requests for rendering
+ * full pages of layouts and portlets.
  *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id$
  */
 public interface PageAggregator extends Aggregator 
 {
+    /**
+     * Defines the interface for rendering content for a page.
+     *
+     * @param rc the request context holding runtime request parameters to be normalized
+     * @param root the root fragment to start rendering from
+     * @throws JetspeedException
+     * @throws IOException
+     */
     void renderContent(RequestContext rc, ContentFragment root) throws JetspeedException, IOException;
 }

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletAccessDeniedException.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletAccessDeniedException.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletAccessDeniedException.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletAccessDeniedException.java Sat Aug  3 23:35:19 2013
@@ -25,10 +25,9 @@ package org.apache.jetspeed.aggregator;
 import org.apache.jetspeed.exception.JetspeedException;
 
 /**
- * <p>
- * NoPortletAccessException
- * </p>
- * 
+ * Represents an exception when trying to render a portlet, but the current user did not have sufficient security
+ * access privileges to render the portlet. Thus an access denied exception is thrown.
+ *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id: $
  *

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletAggregator.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletAggregator.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletAggregator.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletAggregator.java Sat Aug  3 23:35:19 2013
@@ -17,7 +17,7 @@
 package org.apache.jetspeed.aggregator;
 
 /**
- * Portlet aggregation handles pipeline requests for single portlets and entities.
+ * Defines the interface for rendering content for a single portlet.
  *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id$

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletContent.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletContent.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletContent.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletContent.java Sat Aug  3 23:35:19 2013
@@ -16,20 +16,21 @@
 */
 package org.apache.jetspeed.aggregator;
 
-import java.io.PrintWriter;
-import java.util.List;
-
-import javax.portlet.PortletMode;
-import javax.portlet.WindowState;
-
 import org.apache.jetspeed.cache.ContentCacheKey;
 import org.apache.jetspeed.portlet.HeadElement;
 import org.apache.jetspeed.util.KeyValue;
 
+import javax.portlet.PortletMode;
+import javax.portlet.WindowState;
+import java.io.PrintWriter;
+import java.util.List;
+
 /**
- * <p>
- * PortletContent
- * </p>
+ * Portlet content is a container holding the generated content of a fragment (portlet). It is used by the aggregation
+ * engine to abstract access to rendered content per portlet. Content is represented as strings. This interface
+ * also supports multi-threaded aggregation, and can be checked to determine if the generation of content has completed.
+ * Content can also be cached. Expiration values are represented in this interface.
+ *
  * @author <a href="mailto:weaver@apache.org">Scott T. Weaver</a>
  * @author <a href="mailto:taylor@apache.org">David S. Taylor</a>  
  * @version $Id$
@@ -40,87 +41,91 @@ public interface PortletContent
     /**
      * Retrieve the actual content of a portlet as a string
      * 
-     * @return
+     * @return the content of a given fragment (portlet)
      */
     String getContent();
     
     /** 
-     * Has the renderer completed rendering the content?
+     * Has the renderer completed rendering the content? Used by the multi-threaded (parallel) rendering engine.
      * 
-     * @return
+     * @return <tt>true</tt> if the rendering of this fragment's content has completed.
      */
     boolean isComplete();
     
     /**
-     * Notify that this content is completed.
+     * Notifies that this content is completed.
      *
      */
     void complete();
     
     /**
      * Get a writer to the content to stream content into this object
-     * @return
+     *
+     * @return a writer into this content's stream
      */
     PrintWriter getWriter();
     
     /**
      * Get the expiration setting for this content if it is cached.
-     * @return
+     *
+     * @return the expiration value in seconds
      */
     int getExpiration();
     
     /**
-     * Sets the expiration setting for this content.
+     * Sets the expiration setting for this content in seconds
      * 
-     * @param expiration
+     * @param expiration the expiration value in seconds
      */
     void setExpiration(int expiration);
     
     /**
      * Get the cache key used to cache this content
+     *
      * @since 2.1.2 
-     * @return
+     * @return the name of the cache key associated with this content
      */
     ContentCacheKey getCacheKey();
     
     /**
-     * Get the title of the portlet, used during caching
+     * Get the cached title of the portlet
      * 
-     * @return
+     * @return the title of the portlet
      */
     String getTitle();
     
     /**
      * Set the title of this portlet, used during caching
-     * @param title
+     *
+     * @param title the title of this portlet
      */
     void setTitle(String title);
     
     /**
-     * Gets the content type of this portlet content.
+     * Gets the MIME content type of this portlet content.
      * 
-     * @return
+     * @return the MIME content type
      */
     String getContentType();
     
     /**
-     * Sets the content type of this portlet content.
+     * Sets the MIME content type of this portlet content.
      * 
-     * @param contentType
+     * @param contentType the MIME content type
      */
     void setContentType(String contentType);
     
     /**
-     * Gets the portlet mode of this portlet content.
+     * Gets the portlet mode of the portlet instance associated with this portlet content.
      * 
-     * @return
+     * @return the portlet mode
      */
     PortletMode getPortletMode();
     
     /**
-     * Gets the window state of this portlet content.
+     * Gets the window state of the portlet instance associated with this portlet content.
      * 
-     * @return
+     * @return the window state
      */
     WindowState getWindowState();
     
@@ -136,8 +141,8 @@ public interface PortletContent
      * Meanwhile, the element should implement java.io.Serializable.
      * Otherwise it will throw a java.io.NotSerializableException.
      * 
-     * @param element
-     * @param keyHint
+     * @param element the header element to contribute to the page
+     * @param keyHint the key hint to generate the header element
      */
     void addHeadElement(HeadElement element, String keyHint);
     
@@ -145,12 +150,20 @@ public interface PortletContent
      * Retrieves header element key value pairs to be contributed to the page.
      * Because the insertion order might be important for web development, it should be list instead of map.
      * 
-     * @return
+     * @return list of key value pairs of head element names to HeadElements
+     */
+    List<KeyValue<String, HeadElement>> getHeadElements();
+
+    /**
+     * Reset the buffer of this instance to empty. Also resets all state associated with this content.
+     *
      */
-    List<KeyValue<String, HeadElement>> getHeadElements(); 
-    
     void reset();
-    
+
+    /**
+     * Reset the buffer of this instance to empty. Does not reset state associated with this content.
+     *
+     */
     void resetBuffer();
     
     /**

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletRenderer.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletRenderer.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletRenderer.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/PortletRenderer.java Sat Aug  3 23:35:19 2013
@@ -16,20 +16,19 @@
  */
 package org.apache.jetspeed.aggregator;
 
-import java.util.List;
-
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-
 import org.apache.jetspeed.container.PortletWindow;
 import org.apache.jetspeed.om.page.ContentFragment;
 import org.apache.jetspeed.request.RequestContext;
 
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.util.List;
+
 /**
- * <h4>PortletRendererService<br />
- * Jetspeed-2 Rendering service.</h4>
- * <p>This service process all portlet rendering requests and interfaces with the portlet
- * container to generate the resulting markup</p>
+ * The Portlet Renderer Service is the interface to processing portlet rendering requests and interfaces with the portlet
+ * container to generate the resulting markup. The renderer is called by the aggregator {@link PortletAggregator} to
+ * render the content of one portlet. The render works directly with {@link ContentFragment}s, which are wrappers
+ * around portlet instances.
  *
  * @author <a href="mailto:raphael@apache.org">Rapha�l Luta</a>
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
@@ -39,55 +38,76 @@ import org.apache.jetspeed.request.Reque
 public interface PortletRenderer 
 {
     /**
-        Render the specified Page fragment.
-        Result is returned in the PortletResponse.
+     * Renders the specified fragment immediately.
+     *
+     * @param fragment represents the content and runtime preferences about the portlet instance to be rendered
+     * @param request the request context holding runtime request parameters to be normalized
      */
     public void renderNow(ContentFragment fragment, RequestContext request);
 
     /**
-     * Render the specified Page fragment in a separate Thread from the current (rendering) Thread
-     * Result is returned in the PortletResponse.
+     * Render the specified fragment immediately. If spawned is set to true, the rendering can occur in a separate
+     * thread from the current (rendering) thread.
+     *
+     * @param fragment represents the content and runtime preferences about the portlet instance to be rendered
+     * @param request the request context holding runtime request parameters to be normalized
+     * @param spawned <tt>true</tt> if this rendering to occur in a separate thread
     */
     public void renderNow(ContentFragment fragment, RequestContext request, boolean spawned);
 
     /**
-        Render the specified Page fragment.
-        Result is returned in the PortletResponse.
+     * Render the specified fragment immediately. If spawned is set to true, the rendering can occur in a separate
+     * thread from the current (rendering) thread.
+     *
+     * @param fragment represents the content and runtime preferences about the portlet instance to be rendered
+     * @param request the servlet request
+     * @param response the servlet response
+     * @deprecated
      */
     public void renderNow(ContentFragment fragment, HttpServletRequest request, HttpServletResponse response);
 
     /** 
-     * 
-     * Create a rendering job for the specified Page fragment.
-     * The method returns a rendering job which should be passed to 'processRenderingJob(RenderingJob job)' method.
-     * @return portlet rendering job to pass to render(RenderingJob job) method
+     * Create a rendering job for the specified content fragment. All rendering is done under the context of a
+     * rendering job, whether is scheduled in parallel, or sequential. The returned job is passed
+     * to the {@link #processRenderingJob(RenderingJob job)} method.
+     *
+     * @param fragment represents the content and runtime preferences about the portlet instance to be rendered
+     * @param request the request context holding runtime request parameters to be normalized
+     * @return a portlet rendering job to pass to {@link #processRenderingJob(RenderingJob job)} method
      * @throws PortletAccessDeniedException
      */
     public RenderingJob createRenderingJob(ContentFragment fragment, RequestContext request)
     throws PortletAccessDeniedException;
 
     /** 
-     * 
-     * Render the specified rendering job.
-     * The method returns before rendering is complete when the job is processed in parallel mode.
-     * When the job is not parallel mode, it returns after rendering is complete.
+     * Processes the actual rendering of the specified rendering job, dispatching to the portlet container to process
+     * the rendering of a portlet instance. The implementation can return before rendering is complete when the job
+     * is processed in parallel mode. When the job is not parallel mode, it returns after rendering is complete.
+     *
+     * @param job the rendering job to process
      */
     public void processRenderingJob(RenderingJob job);
         
     /**
-     * Wait for all rendering jobs in the collection to finish successfully or otherwise. 
-     * @param renderingJobs the Collection of rendering job objects to wait for.
+     * Waits for all rendering jobs in the list of jobs to finish successfully or otherwise.
+     *
+     * @param renderingJobs the list of rendering job objects to wait for.
      */
     public void waitForRenderingJobs(List<RenderingJob> renderingJobs);
     
     /**
-     * Notify that content completed by worker jobs 
-     * So that renderer can update its state
-     * @param context
-     * @param window
+     * Notification callback from job to this renderer informing that the content rendering has completed.
+     *
+     * @param context the request context holding runtime request parameters to be normalized
+     * @param window the portlet window associated with the job
      */
     public void notifyContentComplete(RequestContext context, PortletWindow window);
 
+    /**
+     * Returns an instance of the PortletTrackingManager which is monitoring this rendering request.
+     *
+     * @return the PortletTrackingManager
+     */
     PortletTrackingManager getPortletTrackingManager();
     
 }

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/RenderingJob.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/RenderingJob.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/RenderingJob.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/RenderingJob.java Sat Aug  3 23:35:19 2013
@@ -16,62 +16,145 @@
  */
 package org.apache.jetspeed.aggregator;
 
-import java.security.AccessControlContext;
-
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-
 import org.apache.jetspeed.container.PortletWindow;
 import org.apache.jetspeed.om.page.ContentFragment;
 import org.apache.jetspeed.om.portlet.PortletDefinition;
 import org.apache.jetspeed.request.RequestContext;
 
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.security.AccessControlContext;
+
 /**
- * Worker thread processes jobs and notify its WorkerMonitor when completed.
- * When no work is available, the worker simply sets itself in a waiting mode
- * pending reactivation by the WorkerMonitor
+ * A rendering worker, running on its own thread if using parallel rendering. This worker thread
+ * processes rendering jobs of portlet windows and notifies the WorkerMonitor when the job is completed.
  *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id: $
  */
 public interface RenderingJob extends Runnable
 {
-
     /**
      * Worker attribute name of AccessControlContext object in the current request processing context.
      */
     String ACCESS_CONTROL_CONTEXT_WORKER_ATTR = AccessControlContext.class.getName();
 
+    /**
+     * Execute the rendering of a portlet window, delegating to the portlet container. Exceptions are never thrown
+     * from this method since it can be run in a separate thread. All exceptions are kept internal and returned in the
+     * job's state and content. Portlet tracking and timeout processing should be handled by implementations.
+     */
     void execute();
 
+    /**
+     * Returns the portlet renderer service managing this job
+     *
+     * @return the renderer service
+     * @deprecated
+     */
     PortletRenderer getRenderer();
 
+    /**
+     * Returns the portlet window associated with this job
+     *
+     * @return the portlet window
+     */
     PortletWindow getWindow();
 
+    /**
+     * Returns the portlet content buffer associated with this job
+     *
+     * @return the portlet content buffer
+     */
     PortletContent getPortletContent();
 
+    /**
+     * The timeout for rendering this job in milliseconds. Depending on the {@link PortletTrackingManager} policy,
+     * this portlet can be taken out of service after timing out repeatedly.
+     *
+     * @param portletTimeout the rendering timeout in milliseconds
+     */
     void setTimeout(long portletTimeout);
 
+    /**
+     * The timeout for rendering this job in milliseconds. Depending on the {@link PortletTrackingManager} policy,
+     * this portlet can be taken out of service after timing out repeatedly.
+     *
+     * @return  the rendering timeout in milliseconds
+     */
     long getTimeout();
 
+    /**
+     * Determines if this job has exceeded the timeout for rendering this job in milliseconds.
+     * Depending on the {@link PortletTrackingManager} policy this portlet can be taken out of
+     * service after timing out repeatedly.
+     *
+     * @return <tt>true</tt> if this job has exceeded the timeout in rendering
+     */
     boolean isTimeout();
 
+    /**
+     * Returns the portlet definition associated with this portlet window and job
+     *
+     * @return the portlet definition from the portlet registry
+     */
     PortletDefinition getPortletDefinition();
 
+    /**
+     * The underlying HttpServletRequest used to render this job
+     *
+     * @return the underlying HttpServletRequest
+     */
     HttpServletRequest getRequest();
 
+    /**
+     * The underlying HttpServletResponse used to render this job
+     *
+     * @return the underlying HttpServletResponse
+     */
     HttpServletResponse getResponse();
 
+    /**
+     * The content fragment to hold the rendered output of this job
+     *
+     * @return the content fragment
+     */
     ContentFragment getFragment();
 
+    /**
+     * The request context associated with this job
+     *
+     * @return the request context
+     */
     RequestContext getRequestContext();
 
+    /**
+     *  The expiration cache timeout value in seconds for the content of this job
+     *
+     * @return the expiration cache timeout in seconds
+     */
     int getExpirationCache();
 
+    /**
+     * Set a generic worker attribute and associate it with this job.
+     *
+     * @param name the name of the attribute
+     * @param value the value of the attribute
+     */
     void setWorkerAttribute(String name, Object value);
 
+    /**
+     * Retrieve a generic worker attribute associated it with this job.
+     *
+     * @param name the name of the attribute
+     * @return the value of the attribute
+     */
     Object getWorkerAttribute(String name);
 
+    /**
+     * Remove a generic worker attribute associated with this job.
+     * @param name the name oof the attribute
+     */
     void removeWorkerAttribute(String name);
 }
 

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/UnknownPortletDefinitionException.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/UnknownPortletDefinitionException.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/UnknownPortletDefinitionException.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/UnknownPortletDefinitionException.java Sat Aug  3 23:35:19 2013
@@ -25,12 +25,11 @@ package org.apache.jetspeed.aggregator;
 import org.apache.jetspeed.exception.JetspeedException;
 
 /**
- * <p>
- * UnknownPortletDefinitionException
- * </p>
- * 
+ * When rendering, a portlet may not be found, and the aggregator will throw this exception.
+ *
  * @author <a href="mailto:weaver@apache.org">Scott T. Weaver</a>
  * @version $Id$
+ * @deprecated
  *
  */
 public class UnknownPortletDefinitionException extends JetspeedException

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/UnrenderedContentException.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/UnrenderedContentException.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/UnrenderedContentException.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/UnrenderedContentException.java Sat Aug  3 23:35:19 2013
@@ -19,15 +19,11 @@ package org.apache.jetspeed.aggregator;
 import org.apache.jetspeed.exception.JetspeedException;
 
 /**
- * <p>
- * UnrenderedContentException
- * </p>
- * <p>
- *  This excpetion is raised when trying to access portlet content that did not render correctly or not at all.
- * </p>
+ *  This exception is raised when trying to access portlet content that did not render correctly or not at all.
+ *
  * @author <a href="mailto:weaver@apache.org">Scott T. Weaver</a>
  * @version $Id$
- *
+ * @deprecated
  */
 public class UnrenderedContentException extends JetspeedException
 {

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/Worker.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/Worker.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/Worker.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/Worker.java Sat Aug  3 23:35:19 2013
@@ -19,52 +19,72 @@ package org.apache.jetspeed.aggregator;
 import java.security.AccessControlContext;
 
 /**
- * Worker thread processes jobs and notify its WorkerMonitor when completed.
+ * A Worker represents a single thread in the parallel aggregation engine.
+ * These worker threads process {@link RenderingJob} and notify its WorkerMonitor when completed.
  * When no work is available, the worker simply sets itself in a waiting mode
- * pending reactivation by the WorkerMonitor
+ * pending reactivation by the WorkerMonitor.
  *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id: $
  */
-public interface Worker
-{
-     int getJobCount();
+public interface Worker {
+    /**
+     * Return the count of jobs this worker is processing
+     *
+     * @return the count of jobs
+     */
+    int getJobCount();
 
     /**
      * Reset the processed job counter
+     *
      */
-     void resetJobCount();
+    void resetJobCount();
 
     /**
      * Sets the running status of this Worker. If set to false, the Worker will
      * stop after processing its current job.
+     *
+     * @param status set to <tt>true</tt> to set this worker to running, false to turn off running
      */
-     void setRunning(boolean status);
+    void setRunning(boolean status);
 
     /**
-     * Sets the moitor of this worker
+     * Sets the WorkMonitor for this worker
+     *
+     * @param monitor the WorkerMonitor who is monitoring this worker
      */
-     void setMonitor(WorkerMonitor monitor);
+    void setMonitor(WorkerMonitor monitor);
 
     /**
      * Sets the job to execute in security context
      *
+     * @param job the job to run
+     * @context the security context
      * @deprecated Use only {@link #setJob(Runnable)} because AccessControlContext must not be directly accessed by
-     * a worker thread. Instead AccessControlContext must be accessed directly by the job implementation in order
-     * to use the AccessControlContext instance safely regardless of the physical worker thread implementation
-     * (e.g, WorkerImpl or container managed thread by commonj worker monitor).
+     *             a worker thread. Instead AccessControlContext must be accessed directly by the job implementation in order
+     *             to use the AccessControlContext instance safely regardless of the physical worker thread implementation
+     *             (e.g, WorkerImpl or container managed thread by commonj worker monitor).
      */
-     void setJob(Runnable job, AccessControlContext context);
+    void setJob(Runnable job, AccessControlContext context);
 
     /**
      * Sets the job to execute
+     *
+     * @param job the job to execute for this worker
      */
-     void setJob(Runnable job);
+    void setJob(Runnable job);
 
     /**
-     * Retrieves the job to execute
+     * Retrieves the job to execute for this worker
+     *
+     * @return the job executing
      */
-     Runnable getJob();
+    Runnable getJob();
 
-     void start();
+    /**
+     * Start executing the job on this worker thread
+     *
+     */
+    void start();
 }

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/WorkerMonitor.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/WorkerMonitor.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/WorkerMonitor.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/aggregator/WorkerMonitor.java Sat Aug  3 23:35:19 2013
@@ -19,8 +19,7 @@ package org.apache.jetspeed.aggregator;
 import java.util.List;
 
 /**
- * The Worker Monitor is a thread manager and monitor for async portlet aggregation
- * and rendering.
+ * The Worker Monitor is a thread manager and monitor for asynchronous (parallel) portlet aggregation and rendering.
  *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id: $

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/pipeline/valve/Valve.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/pipeline/valve/Valve.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/pipeline/valve/Valve.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/pipeline/valve/Valve.java Sat Aug  3 23:35:19 2013
@@ -28,7 +28,6 @@ import org.apache.jetspeed.pipeline.Pipe
  * @author <a href="mailto:david@bluesunrise.com">David Sean Taylor</a>
  * @version $Id: Valve.java 186726 2004-06-05 05:13:09Z taylor $
  *
- * @see org.apache.jetspeed.pipeline.JetspeedPipeline
  * @see org.apache.jetspeed.pipeline.Pipeline
  */
 public interface Valve

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/ProfileLocator.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/ProfileLocator.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/ProfileLocator.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/ProfileLocator.java Sat Aug  3 23:35:19 2013
@@ -138,9 +138,9 @@ public interface ProfileLocator 
     void createFromLocatorPath(String path);
     
     /**
-     * <p>Profiles can be converted to a normalized <i>Profile Locator Path</i>
+     * Profiles can be converted to a normalized <i>Profile Locator Path</i>
      * The format of the path is name/value pairs of all property, separated by a <i>path separator</i>.
-     * An example locator path:</p>
+     * An example locator path:
      * 
      *      <pre>:page:default.psml:artist:joni-mitchell:song:cary</pre>
      * 
@@ -149,8 +149,8 @@ public interface ProfileLocator 
     String getLocatorPath();
         
     /**
-     * <p>Normalize profile properties obtained from profile locator iterators
-     * into a <i>Profile Locator Path</i>.</p>
+     * Normalize profile properties obtained from profile locator iterators
+     * into a <i>Profile Locator Path</i>.
      * 
      * @param properties The array of profile properties.
      * @return The normalized path for properties.
@@ -165,19 +165,19 @@ public interface ProfileLocator 
     String toString();
     
     /**
-     * <p>Locators are intended to be sufficient to locate managed pages, so the request
+     * Locators are intended to be sufficient to locate managed pages, so the request
      * path must be generally available in the event it is not otherwise captured in a
-     * rule criterion.</p>
+     * rule criterion.
      * 
-     * @return The request path.
+     * @return The request path
      */
     String getRequestPath();
     
     /**
-     * <p>Retain the request server name to support additional page location mapping
-     * not part of the profiler rule criterion.</p>
+     * Retain the request server name to support additional page location mapping
+     * not part of the profiler rule criterion.
      * 
-     * @return The request server name.
+     * @return The request server name
      */
     String getRequestServerName();
 }

Modified: portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/ProfileLocatorProperty.java
URL: http://svn.apache.org/viewvc/portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/ProfileLocatorProperty.java?rev=1510080&r1=1510079&r2=1510080&view=diff
==============================================================================
--- portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/ProfileLocatorProperty.java (original)
+++ portals/jetspeed-2/portal/trunk/jetspeed-api/src/main/java/org/apache/jetspeed/profiler/ProfileLocatorProperty.java Sat Aug  3 23:35:19 2013
@@ -17,7 +17,11 @@
 package org.apache.jetspeed.profiler;
 
 /**
- * ProfileLocatorElement
+ * Profile locator properties represent the individual path elements in a {@link ProfileLocator}
+ * An example locator path with locator properties as each name value segment pairs in the path:
+ *
+ *      <pre>page:default.psml:artist:al-stewart:song:on-the-border</pre>
+ *      <pre>path:/sports/football/nfl/chiefs:language:en</pre>
  *
  * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
  * @version $Id$
@@ -33,50 +37,68 @@ public interface ProfileLocatorProperty
     
     /**
      * Sets the value of the locator property.
+     *
      * @param value The value of the property.
      */
     void setValue(String value);
 
-
     /**
      * Returns the fallback type of the property.
-     * see 
-     * 
-     * @return
+     * @see org.apache.jetspeed.profiler.rules.RuleCriterion#FALLBACK_CONTINUE
+     * @see org.apache.jetspeed.profiler.rules.RuleCriterion#FALLBACK_LOOP
+     * @see org.apache.jetspeed.profiler.rules.RuleCriterion#FALLBACK_STOP
+     *
+     * @return the fallback type of the property
      */
     int getFallbackType();
 
     /**
-     * @return
+     * Returns the fallback type of the property.
+     * @see org.apache.jetspeed.profiler.rules.RuleCriterion#FALLBACK_CONTINUE
+     * @see org.apache.jetspeed.profiler.rules.RuleCriterion#FALLBACK_LOOP
+     * @see org.apache.jetspeed.profiler.rules.RuleCriterion#FALLBACK_STOP
+     *
+     * @param type the fallback type of the property
      */
-    String getName();
+    void setFallbackType(int type);
 
     /**
-     * @return
+     * The name of the locator property
+     *
+     * @return the name of the locator property
      */
-    String getType();
+    String getName();
 
     /**
-     * @param i
+     * The name of the locator property
+     *
+     * @param string the name of the locator property
      */
-    void setFallbackType(int type);
+    void setName(String string);
 
     /**
-     * @param string
+     * @return
+     * @deprecated
      */
-    void setName(String string);
-    
+    String getType();
+
     /**
-     * @param string
+     *
+     * @param type
+     * @deprecated
      */
-    void setType(String type);    
+    void setType(String type);
 
     /**
-     * @return control classification flag
+     * Determines if this locator property is a control
+     *
+     * @return control classification flag, is it a control
      */
     boolean isControl();
     
     /**
+     * Determines if this locator property is a navigation
+     *
      * @return true if a property is a navigation
      */
     boolean isNavigation();



---------------------------------------------------------------------
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