You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jetspeed-dev@portals.apache.org by ta...@apache.org on 2013/08/04 01:35:20 UTC
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...
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