001: /**
002: * Copyright 2006 Webmedia Group Ltd.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: **/package org.araneaframework.framework;
016:
017: import java.io.Serializable;
018: import org.apache.commons.collections.Closure;
019: import org.araneaframework.EnvironmentAwareCallback;
020: import org.araneaframework.Widget;
021: import org.araneaframework.core.ApplicationWidget;
022:
023: /**
024: * This context provides support for flow navigation and nesting. A flow is started using
025: * {@link #start(Widget, org.araneaframework.framework.FlowContext.Configurator, org.araneaframework.framework.FlowContext.Handler)}
026: * and continues to be active until it explicitly returns control to the caller using {@link #finish(Object)} or
027: * {@link #cancel()}.
028: *
029: * @see org.araneaframework.framework.container.StandardFlowContainerWidget
030: *
031: * @author "Toomas Römer" <toomas@webmedia.ee>
032: * @author Jevgeni Kabanov (ekabanov <i>at</i> araneaframework <i>dot</i> org)
033: */
034: public interface FlowContext extends Serializable {
035: /** @since 1.1 */
036: int TRANSITION_START = 1;
037: /** @since 1.1 */
038: int TRANSITION_FINISH = 2;
039: /** @since 1.1 */
040: int TRANSITION_CANCEL = 3;
041: /** @since 1.1 */
042: int TRANSITION_REPLACE = 4;
043: /** @since 1.1 */
044: int TRANSITION_RESET = 5;
045:
046: /**
047: * Starts a new nested subflow. Current flow becomes inactive untils subflow calls {@link #finish(Object)} or
048: * {@link #cancel()}.
049: * @since 1.0.9
050: */
051: public void start(Widget flow);
052:
053: /**
054: * Starts a new nested subflow. Current flow becomes inactive untils subflow calls {@link #finish(Object)} or
055: * {@link #cancel()}. {@link Handler} allows to receive notification, when the subflow ends execution.
056: * @since 1.0.9
057: */
058: public void start(Widget flow, Handler handler);
059:
060: /**
061: * Starts a new nested subflow, that can be configured using the configurator. Current flow becomes inactive
062: * untils subflow calls {@link #finish(Object)} or {@link #cancel()}. {@link Handler} allows to receive notification,
063: * when the subflow ends execution.
064: */
065: public void start(Widget flow, Configurator configurator,
066: Handler handler);
067:
068: /**
069: * Destroys the current flow and starts a new one. When the new flow will end execution it will return control
070: * to the caller of the current flow (if there is one).
071: */
072: public void replace(Widget flow);
073:
074: /**
075: * Destroys the current flow and starts a new one. When the new flow will end execution it will return control
076: * to the caller of the current flow (if there is one). Started subflow can be configured using the configurator.
077: * @since 1.0.9
078: */
079: public void replace(Widget flow, Configurator configurator);
080:
081: /**
082: * Finisheds the current flow passing control back to the calling flow. Optionally may return some value that
083: * can be interpreted by the calling flow as the result of the call.
084: */
085: public void finish(Object result);
086:
087: /**
088: * Finished the current flow passing control back to the calling flow.
089: * Should be interpreted by the calling flow as a unsuccessful return.
090: */
091: public void cancel();
092:
093: /**
094: * Returns whether the current flow is nested, that is has a caller flow.
095: */
096: public boolean isNested();
097:
098: /**
099: * Resets all currently running flows and calls the <code>callback</code> allowing to start
100: * new flows. Useful e.g. in a menu, when selecting a new menu item and reseting the old
101: * stack.
102: */
103: public void reset(EnvironmentAwareCallback callback);
104:
105: /**
106: * Returns a reference to the current flow that can be used later to manipulate the current flow.
107: * @deprecated to be removed in Aranea 2.0. Also see {@link FlowReference}
108: */
109: public FlowReference getCurrentReference();
110:
111: /**
112: * Adds an environment entry that is visible in all subflows.
113: */
114: public void addNestedEnvironmentEntry(ApplicationWidget scope,
115: final Object entryId, Object envEntry);
116:
117: /**
118: * This is unused -- only implementation is a protected class StandardFlowContainerWidget.FlowReference
119: * FlowReference.reset() is not called from anywhere and is duplicate of FlowContext.reset() anyway.
120: * @deprecated to be removed in Aranea 2.0
121: */
122: public interface FlowReference extends Serializable {
123: /**
124: * Resets the flow stack up to the referred flow and provides the callback with the local environment
125: * that can be used to manipulate the flow stack further.
126: */
127: public void reset(EnvironmentAwareCallback callback)
128: throws Exception;
129: }
130:
131: /**
132: * Sets the {@link TransitionHandler} which performs the flow navigation.
133: * @since 1.1 */
134: void setTransitionHandler(TransitionHandler handler);
135:
136: /**
137: * Returns currently active {@link TransitionHandler}
138: * @since 1.1 */
139: TransitionHandler getTransitionHandler();
140:
141: /**
142: * Callback that will be run when flow has finished some way.
143: */
144: public interface Handler extends Serializable {
145: public void onFinish(Object returnValue) throws Exception;
146:
147: public void onCancel() throws Exception;
148: }
149:
150: /**
151: * Configurator runs when {@link FlowContext} starts flow.
152: */
153: public interface Configurator extends Serializable {
154: public void configure(Widget flow) throws Exception;
155: }
156:
157: /**
158: * Performs the flow transitions in {@link FlowContext}.
159: *
160: * @author Taimo Peelo (taimo@araneaframework.org)
161: * @since 1.1
162: */
163: interface TransitionHandler extends Serializable {
164: /**
165: * @param eventType <code>FlowContext.START<code> .. <code>FlowContext.RESET<code>
166: * @param activeFlow active flow at the moment of transition request
167: * @param transition <code>Serializable</code> closure that needs to be executed for transition to happen
168: */
169: void doTransition(int eventType, Widget activeFlow,
170: Closure transition);
171: }
172: }
|