org.springframework.webflow.engine.FlowAttributeMapper Maven / Gradle / Ivy
/*
* Copyright 2002-2006 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.engine;
import org.springframework.webflow.core.collection.AttributeMap;
import org.springframework.webflow.core.collection.MutableAttributeMap;
import org.springframework.webflow.execution.RequestContext;
/**
* A service interface that maps attributes between two flows. Used by the
* subflow state to map attributes between a parent flow and its sub flow.
*
* An attribute mapper may map attributes of a parent flow down to a child flow
* as input when the child is spawned as a subflow. In addition, a
* mapper may map output attributes of a subflow into a resuming parent flow as
* output when the child session ends and control is returned to the
* parent flow.
*
* For example, say you have the following parent flow session:
*
*
*
* Parent Flow Session
* -------------------
* -> flow = myFlow
* -> flowScope = [map-> attribute1=value1, attribute2=value2, attribute3=value3]
*
*
*
* For the "Parent Flow Session" above, there are 3 attributes in flow scope
* ("attribute1", "attribute2" and "attribute3", respectively). Any of these
* three attributes may be mapped as input down to child subflows when those
* subflows are spawned. An implementation of this interface performs the actual
* mapping, encapsulating knowledge of which attributes should be
* mapped, and how they will be mapped (for example, will the same
* attribute names be used between flows or not?).
*
* For example:
*
*
*
* Flow Attribute Mapper Configuration
* -----------------------------------
* -> inputMappings = [map-> flowScope.attribute1->attribute1, flowScope.attribute3->attribute4]
* -> outputMappings = [map-> attribute4->flowScope.attribute3]
*
*
*
* The above example "Flow Attribute Mapper" specifies
* inputMappings that define which parent attributes to map as
* input to the child. In this case, two attributes in flow scope of the parent
* are mapped, "attribute1" and "attribute3". "attribute1" is mapped with the
* name "attribute1" (given the same name in both flows), while "attribute3" is
* mapped to "attribute4", given a different name that is local to the child
* flow.
*
* Likewise, when a child flow ends the outputMappings define
* which output attributes to map into the parent. In this case the subflow
* output attribute "attribute4" will be mapped up to the parent as "attribute3",
* updating the value of "attribute3" in the parent's flow scope. Note: only
* output attributes exposed by the end state of the ending subflow are eligible
* for mapping.
*
* A FlowAttributeMapper is typically implemented using 2 distinct
* {@link org.springframework.binding.mapping.AttributeMapper} implementations:
* one responsible for input mapping and one taking care of output mapping.
*
* Note: because FlowAttributeMappers are singletons, take care not to store
* and/or modify caller-specific state in a unsafe manner. The
* FlowAttributeMapper methods run in an independently executing thread on each
* invocation so make sure you deal only with local data or internal,
* thread-safe services.
*
* @see org.springframework.webflow.engine.SubflowState
* @see org.springframework.binding.mapping.AttributeMapper
*
* @author Keith Donald
* @author Erwin Vervaet
*/
public interface FlowAttributeMapper {
/**
* Create a map of attributes that should be passed as input to a
* spawning flow.
*
* Attributes set in the map returned by this method are availale
* as input to the subflow when its session is spawned.
* @param context the current request execution context, which gives access
* to the parent flow scope, the request scope, any event parameters, etcetera
* @return a map of attributes (name=value pairs) to pass as input to the
* spawning subflow
*/
public MutableAttributeMap createFlowInput(RequestContext context);
/**
* Map output attributes of an ended flow to a resuming parent flow session.
* This maps the output of the child as new input to the resuming
* parent, typically adding data to flow scope.
* @param flowOutput the output attributes exposed by the ended subflow
* @param context the current request execution context, which gives access
* to the parent flow scope
*/
public void mapFlowOutput(AttributeMap flowOutput, RequestContext context);
}