KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > webflow > engine > FlowAttributeMapper


1 /*
2  * Copyright 2002-2006 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.springframework.webflow.engine;
17
18 import org.springframework.webflow.core.collection.AttributeMap;
19 import org.springframework.webflow.core.collection.MutableAttributeMap;
20 import org.springframework.webflow.execution.RequestContext;
21
22 /**
23  * A service interface that maps attributes between two flows. Used by the
24  * subflow state to map attributes between a parent flow and its sub flow.
25  * <p>
26  * An attribute mapper may map attributes of a parent flow down to a child flow
27  * as <i>input</i> when the child is spawned as a subflow. In addition, a
28  * mapper may map output attributes of a subflow into a resuming parent flow as
29  * <i>output</i> when the child session ends and control is returned to the
30  * parent flow.
31  * <p>
32  * For example, say you have the following parent flow session:
33  * <p>
34  *
35  * <pre>
36  * Parent Flow Session
37  * -------------------
38  * -&gt; flow = myFlow
39  * -&gt; flowScope = [map-&gt; attribute1=value1, attribute2=value2, attribute3=value3]
40  * </pre>
41  *
42  * <p>
43  * For the "Parent Flow Session" above, there are 3 attributes in flow scope
44  * ("attribute1", "attribute2" and "attribute3", respectively). Any of these
45  * three attributes may be mapped as input down to child subflows when those
46  * subflows are spawned. An implementation of this interface performs the actual
47  * mapping, encapsulating knowledge of <i>which</i> attributes should be
48  * mapped, and <i>how</i> they will be mapped (for example, will the same
49  * attribute names be used between flows or not?).
50  * <p>
51  * For example:
52  * <p>
53  *
54  * <pre>
55  * Flow Attribute Mapper Configuration
56  * -----------------------------------
57  * -&gt; inputMappings = [map-&gt; flowScope.attribute1-&gt;attribute1, flowScope.attribute3-&gt;attribute4]
58  * -&gt; outputMappings = [map-&gt; attribute4-&gt;flowScope.attribute3]
59  * </pre>
60  *
61  * <p>
62  * The above example "Flow Attribute Mapper" specifies
63  * <code>inputMappings</code> that define which parent attributes to map as
64  * input to the child. In this case, two attributes in flow scope of the parent
65  * are mapped, "attribute1" and "attribute3". "attribute1" is mapped with the
66  * name "attribute1" (given the same name in both flows), while "attribute3" is
67  * mapped to "attribute4", given a different name that is local to the child
68  * flow.
69  * <p>
70  * Likewise, when a child flow ends the <code>outputMappings</code> define
71  * which output attributes to map into the parent. In this case the subflow
72  * output attribute "attribute4" will be mapped up to the parent as "attribute3",
73  * updating the value of "attribute3" in the parent's flow scope. Note: only
74  * output attributes exposed by the end state of the ending subflow are eligible
75  * for mapping.
76  * <p>
77  * A FlowAttributeMapper is typically implemented using 2 distinct
78  * {@link org.springframework.binding.mapping.AttributeMapper} implementations:
79  * one responsible for input mapping and one taking care of output mapping.
80  * <p>
81  * Note: because FlowAttributeMappers are singletons, take care not to store
82  * and/or modify caller-specific state in a unsafe manner. The
83  * FlowAttributeMapper methods run in an independently executing thread on each
84  * invocation so make sure you deal only with local data or internal,
85  * thread-safe services.
86  *
87  * @see org.springframework.webflow.engine.SubflowState
88  * @see org.springframework.binding.mapping.AttributeMapper
89  *
90  * @author Keith Donald
91  * @author Erwin Vervaet
92  */
93 public interface FlowAttributeMapper {
94
95     /**
96      * Create a map of attributes that should be passed as <i>input</i> to a
97      * spawning flow.
98      * <p>
99      * Attributes set in the map returned by this method are availale
100      * as input to the subflow when its session is spawned.
101      * @param context the current request execution context, which gives access
102      * to the parent flow scope, the request scope, any event parameters, etcetera
103      * @return a map of attributes (name=value pairs) to pass as input to the
104      * spawning subflow
105      */
106     public MutableAttributeMap createFlowInput(RequestContext context);
107
108     /**
109      * Map output attributes of an ended flow to a resuming parent flow session.
110      * This maps the <i>output</i> of the child as new input to the resuming
111      * parent, typically adding data to flow scope.
112      * @param flowOutput the output attributes exposed by the ended subflow
113      * @param context the current request execution context, which gives access
114      * to the parent flow scope
115      */
116     public void mapFlowOutput(AttributeMap flowOutput, RequestContext context);
117 }
Popular Tags