JavaDoc polishing.

spring-webflow/src/main/java/org/springframework/webflow/executor/jsf/FlowExecutionKeyStateHolder.java

@@ -103,7 +103,7 @@ public class FlowExecutionKeyStateHolder extends UIComponentBase {
 	}
 
 	/**
-	 * Restore the FlowExecution from the stored FlowExecutionKey
+	 * Restore the FlowExecution from the stored FlowExecutionKey.
 	 */
 	public void restoreState(FacesContext context, Object state) {
 		Object values[] = (Object[]) state;
@@ -116,8 +116,8 @@ public class FlowExecutionKeyStateHolder extends UIComponentBase {
 		// restore only if the key is present and the current flow execution has not already been restored
 		if (StringUtils.hasText(flowExecutionKey) && !FlowExecutionHolderUtils.isFlowExecutionRestored(facesContext)) {
 			// restore the "current" flow execution from repository so it will be available to variable/property
-			// resolvers
-			// and the flow navigation handler (this could happen as part of a view action like a form submission)
+			// resolvers and the flow navigation handler (this could happen as part of a view action like a form
+			// submission)
 			FlowExecutionRepository repository = getRepository(context);
 			// restore the key from the stored encoded key string
 			FlowExecutionKey key = repository.parseFlowExecutionKey(flowExecutionKey);
@@ -127,10 +127,9 @@ public class FlowExecutionKeyStateHolder extends UIComponentBase {
 				try {
 					FlowExecution flowExecution = repository.getFlowExecution(key);
 					if (logger.isDebugEnabled()) {
-						logger
-								.debug("Loaded existing flow execution with key '"
-										+ flowExecutionKey
-										+ "' as part of component restoration [triggered via an action event like a button click]");
+						logger.debug("Restorted existing flow execution with key '" + flowExecutionKey
+								+ "' as part of component restoration"
+								+ " [triggered via an action event like a button click]");
 					}
 					FlowExecutionHolderUtils.setFlowExecutionHolder(new FlowExecutionHolder(key, flowExecution, lock),
 							facesContext);
@@ -141,6 +140,9 @@ public class FlowExecutionKeyStateHolder extends UIComponentBase {
 					lock.unlock();
 					throw e;
 				}
+
+				// in the normal case, the FlowPhaseListener will do lock.unlock(), or failing that the
+				// FlowSystemCleanupFilter
 			} catch (FlowExecutionAccessException e) {
 				handleFlowExecutionAccessException(e, facesContext);
 			}
@@ -170,6 +172,8 @@ public class FlowExecutionKeyStateHolder extends UIComponentBase {
 		return COMPONENT_ID;
 	}
 
+	// internal helpers
+
 	private FlowExecutionRepository getRepository(JsfExternalContext context) {
 		return FlowFacesUtils.getExecutionRepository(context.getFacesContext());
 	}

spring-webflow/src/main/java/org/springframework/webflow/executor/jsf/FlowNavigationHandler.java

@@ -38,20 +38,18 @@ import org.springframework.webflow.executor.support.FlowExecutorArgumentExtracto
 /**
  * An implementation of a JSF <code>NavigationHandler</code> that provides integration with Spring Web Flow.
  * Responsible for delegating to Spring Web Flow to launch and resume flow executions, treating JSF action outcomes
- * (like a command button click) as web flow events.
- * 
+ * (like a command button click) as Web Flow events.
+ * <p>
  * This class delegates to the standard NavigationHandler implementation when a navigation request does not pertain to a
  * flow execution.
  * <p>
  * The following navigation handler algorithm is implemented by default:
- * </p>
  * <p>
  * If a flow execution has been restored in the current request:
  * <ul>
  * <li>Resume the flow execution by signaling the JSF action outcome as an event against the current state.
  * <li>Once event processing completes expose the selected view as the "current" {@link ViewSelection}.
  * </ul>
- * </p>
  * <p>
  * If a flow execution has not been restored in the current request:
  * <ul>
@@ -61,12 +59,12 @@ import org.springframework.webflow.executor.support.FlowExecutorArgumentExtracto
  * <li>If the specified logical outcome is not of the form <em>flowId:xxx</em>, simply delegate to the standard
  * <code>NavigationHandler</code> implementation and return.
  * </ul>
- * </p>
+ * <p>
  * How the flowId and eventId arguments are extracted can be customized by setting a custom
  * {@link #setArgumentExtractor(FlowExecutorArgumentExtractor) argument extractor}.
- * 
- * Note about customization: since NavigationHandlers managed directly by the JSF provider cannot be benefit from
- * DependencyInjection, See Spring's {@link org.springframework.web.jsf.DelegatingNavigationHandlerProxy} when you need
+ * <p>
+ * Note about customization: since NavigationHandlers managed directly by the JSF provider cannot benefit from
+ * dependency injection, See Spring's {@link org.springframework.web.jsf.DelegatingNavigationHandlerProxy} when you need
  * to customize a FlowNavigationHandler instance.
  * 
  * @author Craig McClanahan
@@ -101,7 +99,6 @@ public class FlowNavigationHandler extends DecoratingNavigationHandler {
 	 * Create a new {@link FlowNavigationHandler} using the default constructor.
 	 */
 	public FlowNavigationHandler() {
-		super();
 	}
 
 	/**

spring-webflow/src/main/java/org/springframework/webflow/executor/jsf/FlowNavigationHandlerArgumentExtractor.java

@@ -22,8 +22,8 @@ import org.springframework.webflow.executor.support.FlowExecutorArgumentExtracto
 
 /**
  * An {@link FlowExecutorArgumentExtractor} that is aware of JSF outcomes that communicate requests to launch flow
- * executions and signal event in existing flow executions. Designed to be used wih a {@link FlowNavigationHandler}.
- * 
+ * executions and signal events in existing flow executions. Designed to be used wih a {@link FlowNavigationHandler}.
+ * <p>
  * Note: this class only implements flow id and event id extraction methods. A FlowNavigationHandler is not expected to
  * extract a flow execution key, as flow execution restoration is fully handled by the {@link FlowPhaseListener} and the
  * JSF restore view phase.
@@ -100,6 +100,7 @@ public class FlowNavigationHandlerArgumentExtractor implements FlowExecutorArgum
 	}
 
 	// helpers
+
 	private String getOutcome(ExternalContext context) {
 		return ((JsfExternalContext) context).getOutcome();
 	}

spring-webflow/src/main/java/org/springframework/webflow/executor/jsf/FlowPhaseListener.java

@@ -61,7 +61,6 @@ import org.springframework.webflow.executor.support.ResponseInstructionHandler;
  * and NavigationHandlers may access during the request lifecycle. Once in the holder the execution is considered
  * "restored" and referred to as the "current" flow execution for this request.
  * <p>
- * <p>
  * This phase listener implements the following algorithm:
  * <ul>
  * <li>On BEFORE_RESTORE_VIEW, restore a {@link FlowExecution} if a call to
@@ -72,7 +71,7 @@ import org.springframework.webflow.executor.support.ResponseInstructionHandler;
  * {@link FlowExecutorArgumentHandler#extractFlowId(ExternalContext)} returns a valid flow id. This occurs when a
  * browser accesses a flow definition URL directly and is used to launch a new flow execution.
  * <li>During RESTORE_VIEW, the {@link FlowExecutionKeyStateHolder state holder component} will restore the current
- * FlowExecution if it is present in the JSF ViewRoot. This occurs when a postback from a JSF view that is participating
+ * FlowExecution if it is present in the JSF ViewRoot. This occurs on a postback from a JSF view that is participating
  * in a flow.
  * <li>On BEFORE_RENDER_RESPONSE, if a flow execution was restored in the RESTORE_VIEW phase generate a new key that
  * will identify the updated execution within the configured {@link FlowExecutionRepository}. Expose the new flow
@@ -80,10 +79,10 @@ import org.springframework.webflow.executor.support.ResponseInstructionHandler;
  * <li>On AFTER_RENDER_RESPONSE, if a flow execution was restored in the RESTORE_VIEW phase <em>save</em> the updated
  * execution to the repository using the new key generated in the BEFORE_RENDER_RESPONSE phase.
  * </ul>
- * 
- * Note about customization: since PhaseListeners managed directly by the JSF provider cannot be benefit from
- * DependencyInjection, See Spring's {@link org.springframework.web.jsf.DelegatingPhaseListenerMulticaster} when you
- * need to customize a FlowPhaseListener instance.
+ * <p>
+ * Note about customization: since PhaseListeners managed directly by the JSF provider cannot benefit from dependency
+ * injection, See Spring's {@link org.springframework.web.jsf.DelegatingPhaseListenerMulticaster} when you need to
+ * customize a FlowPhaseListener instance.
  * 
  * @author Colin Sampaleanu
  * @author Keith Donald