diff --git a/spring-webflow/src/main/java/org/springframework/webflow/mvc/AjaxHandler.java b/spring-webflow/src/main/java/org/springframework/webflow/mvc/AjaxHandler.java index 678a2dc6..029848c2 100644 --- a/spring-webflow/src/main/java/org/springframework/webflow/mvc/AjaxHandler.java +++ b/spring-webflow/src/main/java/org/springframework/webflow/mvc/AjaxHandler.java @@ -1,3 +1,18 @@ +/* + * Copyright 2004-2008 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package org.springframework.webflow.mvc; import javax.servlet.http.HttpServletRequest; @@ -11,14 +26,14 @@ import javax.servlet.http.HttpServletResponse; public interface AjaxHandler { /** - * Is the request from the client an Ajax request? + * Is the current request an Ajax request? * @param request the current request */ public boolean isAjaxRequest(HttpServletRequest request); /** - * Send a redirect request to the Ajax client. This should cause the client to send a new request to the specified - * target url. + * Send a redirect request to the Ajax client. This should cause the client-side agent to send a new request to the + * specified target url. * @param response the response object * @param targetUrl the target url to redirect to * @param popup wheter the redirect should be sent from a new popup dialog window diff --git a/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowController.java b/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowController.java index b90ba2ad..0775d57f 100644 --- a/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowController.java +++ b/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowController.java @@ -1,3 +1,18 @@ +/* + * Copyright 2004-2008 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package org.springframework.webflow.mvc; import java.io.IOException; @@ -23,22 +38,40 @@ import org.springframework.webflow.executor.FlowExecutionResult; import org.springframework.webflow.executor.FlowExecutor; /** - * Adapter between the Spring MVC Controller layer and the Spring Web Flow engine. This controller allows Spring Web - * Flow to run in "embedded" mode as a Controller within a DispatcherServlet. + * The adapter between the Spring MVC Controller layer and the Spring Web Flow engine. This controller allows Spring Web + * Flow to run embedded as a Controller within a DispatcherServlet, the key piece of the Spring Web MVC platform. It is + * expected a DispatcherServlet HandlerMapping will care for mapping all requests for flows to this controller for + * handling. + * + * @author Keith Donald */ public class FlowController extends AbstractController { private static final Log logger = LogFactory.getLog(FlowController.class); + /** + * The entry point into Spring Web Flow. + */ private FlowExecutor flowExecutor; + /** + * A strategy for extracting flow arguments and generating flow urls. + */ private FlowUrlHandler urlHandler; + /** + * The representation of an Ajax client service capable of interacting with web flow. + */ private AjaxHandler ajaxHandler; + /** + * Specific handlers this controller should delegate to, for customizing the control logic associated with managing + * the execution of a specific flow. + */ private Map flowHandlers = new HashMap(); /** + * Creates a new flow controller. * @param flowExecutor the web flow executor service */ public FlowController(FlowExecutor flowExecutor) { @@ -49,14 +82,40 @@ public class FlowController extends AbstractController { setCacheSeconds(0); } + /** + * Returns the configured flow url handler. + */ public FlowUrlHandler getFlowUrlHandler() { return urlHandler; } + /** + * Sets the configured flow url handler. + * @param urlHandler the flow url handler. + */ public void setFlowRequestUrlHandler(FlowUrlHandler urlHandler) { this.urlHandler = urlHandler; } + /** + * Returns the configured Ajax handler. + */ + public AjaxHandler getAjaxHandler() { + return ajaxHandler; + } + + /** + * Sets the configured Ajax handler. + * @param ajaxHandler the ajax handler + */ + public void setAjaxHandler(AjaxHandler ajaxHandler) { + this.ajaxHandler = ajaxHandler; + } + + /** + * Registers a handler for managing access to a specific flow definition. + * @param handler the flow handler + */ public void registerFlowHandler(FlowHandler handler) { flowHandlers.put(handler.getFlowId(), handler); } diff --git a/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowHandler.java b/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowHandler.java index aec5f351..f77bd46e 100644 --- a/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowHandler.java +++ b/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowHandler.java @@ -1,3 +1,18 @@ +/* + * Copyright 2004-2008 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package org.springframework.webflow.mvc; import javax.servlet.http.HttpServletRequest; @@ -8,13 +23,54 @@ import org.springframework.webflow.core.FlowException; import org.springframework.webflow.core.collection.AttributeMap; import org.springframework.webflow.core.collection.MutableAttributeMap; +/** + * A controller helper used for customizing access to a single flow definition. This helper is used to: + *
    + *
  1. Launch executions of that flow with data in the execution input map + *
  2. Handle outcomes reached by that flow in a custom manner. + *
  3. Handle un-handled exceptions dealing with that flow in a custom manner. + *
+ * Such a handler can be visually thought of as a "flow reference" on a Garrett IA diagram. It holds a reference to the + * flow id to launch, how to provision its input, how to process its outcomes, and how to handle uncaught exceptions. + * + * @author Keith Donald + */ public interface FlowHandler { + + /** + * Returns the id of the flow handled by this handler. Used by a Controller to load the flow definition. + * @return the flow id + */ public String getFlowId(); + /** + * Creates the flow execution input map to pass to a new instance of the flow being started. Used by a Controller to + * launch the flow execution with the correct input. + * @param request the current request + * @return the input map + */ public MutableAttributeMap createExecutionInputMap(HttpServletRequest request); + /** + * Handles a specific flow execution outcome. Used by a Controller to select a new view to render after the flow + * ends. + * @param outcome the outcome that was reached + * @param output the output returned by the flow execution + * @param request the current request + * @param response the current response + * @return the model and view to render on the occurrence of this outcome, or null if the outcome was not handled + */ public ModelAndView handleExecutionOutcome(String outcome, AttributeMap output, HttpServletRequest request, HttpServletResponse response); + /** + * Handles a flow exception that was not handled by the Web Flow system. Used by a Controller to handle a specific + * type of exception dealing with this flow in a custom manner. + * @param e the unhandled exception orignating from Spring Web Flow. May be thrown by the flow execution itself or + * the flow executor system if no execution could be restored. + * @param request the current request + * @param response the current response + * @return the model and view to render on the occurrence of this exception, or null if the exception is not handled + */ public ModelAndView handleException(FlowException e, HttpServletRequest request, HttpServletResponse response); } diff --git a/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowHandlerAdapter.java b/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowHandlerAdapter.java index e76f03dc..c34c1e15 100644 --- a/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowHandlerAdapter.java +++ b/spring-webflow/src/main/java/org/springframework/webflow/mvc/FlowHandlerAdapter.java @@ -1,3 +1,18 @@ +/* + * Copyright 2004-2008 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package org.springframework.webflow.mvc; import java.io.IOException; @@ -22,8 +37,8 @@ import org.springframework.webflow.executor.FlowExecutionResult; import org.springframework.webflow.executor.FlowExecutor; /** - * A Spring MVC handler adapter that encapsulates the generic workflow associated with executing flows. Delegates to - * mapped flow handlers to manage the specific execution semantics required for particular registered flow definition. + * A custom MVC HandlerAdapter that encapsulates the generic workflow associated with executing flows. Delegates to + * mapped {@link FlowHandler flow handlers} to manage the interaction with executions of specific flow definitions. * * @author Keith Donald */ @@ -31,10 +46,19 @@ public class FlowHandlerAdapter extends WebApplicationObjectSupport implements H private static final Log logger = LogFactory.getLog(FlowHandlerAdapter.class); + /** + * The entry point into Spring Web Flow. + */ private FlowExecutor flowExecutor; + /** + * A strategy for extracting flow arguments and generating flow urls. + */ private FlowUrlHandler urlHandler; + /** + * The representation of an Ajax client service capable of interacting with web flow. + */ private AjaxHandler ajaxHandler; /** @@ -62,6 +86,21 @@ public class FlowHandlerAdapter extends WebApplicationObjectSupport implements H this.urlHandler = urlHandler; } + /** + * Returns the configured Ajax handler. + */ + public AjaxHandler getAjaxHandler() { + return ajaxHandler; + } + + /** + * Sets the configured Ajax handler. + * @param ajaxHandler the ajax handler + */ + public void setAjaxHandler(AjaxHandler ajaxHandler) { + this.ajaxHandler = ajaxHandler; + } + public boolean supports(Object handler) { return handler instanceof FlowHandler; } diff --git a/spring-webflow/src/main/java/org/springframework/webflow/mvc/MvcViewFactoryCreator.java b/spring-webflow/src/main/java/org/springframework/webflow/mvc/MvcViewFactoryCreator.java index 9142f850..05835fd3 100644 --- a/spring-webflow/src/main/java/org/springframework/webflow/mvc/MvcViewFactoryCreator.java +++ b/spring-webflow/src/main/java/org/springframework/webflow/mvc/MvcViewFactoryCreator.java @@ -1,3 +1,18 @@ +/* + * Copyright 2004-2008 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package org.springframework.webflow.mvc; import java.util.HashMap; @@ -27,7 +42,7 @@ import org.springframework.webflow.execution.View; import org.springframework.webflow.execution.ViewFactory; /** - * View factory creator implementation that produces View Factories that create Spring MVC-based views. + * View factory creator implementation that produces View Factories that create native Spring MVC-based views. * * This class is used by a flow builder in a Spring MVC environment to configure view factories on flows that render * Spring MVC-based views. diff --git a/spring-webflow/src/main/java/org/springframework/webflow/mvc/SpringJavascriptAjaxHandler.java b/spring-webflow/src/main/java/org/springframework/webflow/mvc/SpringJavascriptAjaxHandler.java index a3ccde51..2ea6a0ed 100644 --- a/spring-webflow/src/main/java/org/springframework/webflow/mvc/SpringJavascriptAjaxHandler.java +++ b/spring-webflow/src/main/java/org/springframework/webflow/mvc/SpringJavascriptAjaxHandler.java @@ -1,3 +1,18 @@ +/* + * Copyright 2004-2008 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ package org.springframework.webflow.mvc; import javax.servlet.http.HttpServletRequest; @@ -6,7 +21,7 @@ import javax.servlet.http.HttpServletResponse; import org.springframework.util.StringUtils; /** - * Ajax handler that works with Spring Javascript (Spring.js). + * Ajax handler for Spring Javascript (Spring.js). * * @author Jeremy Grelle * @author Keith Donald @@ -50,4 +65,4 @@ public class SpringJavascriptAjaxHandler implements AjaxHandler { response.setHeader(FLOW_REDIRECT_URL_HEADER, response.encodeRedirectURL(targetUrl)); } -} +} \ No newline at end of file