001: /*
002: * Copyright 2004-2007 the original author or authors.
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: */
016: package org.springframework.webflow.engine.builder;
017:
018: import org.springframework.webflow.core.collection.AttributeMap;
019: import org.springframework.webflow.engine.Flow;
020:
021: /**
022: * Builder interface used to build a flow definition. The process of building a
023: * flow consists of the following steps:
024: * <ol>
025: * <li> Initialize this builder, creating the initial flow definition, by
026: * calling {@link #init(String, AttributeMap)}.
027: * <li> Call {@link #buildVariables()} to create any variables of the flow and
028: * add them to the flow definition.
029: * <li> Call {@link #buildInputMapper()} to create and set the input mapper for
030: * the flow.
031: * <li> Call {@link #buildStartActions()} to create and add any start actions to
032: * the flow.
033: * <li> Call {@link #buildInlineFlows()} to create any inline flows
034: * encapsulated by the flow and add them to the flow definition.
035: * <li> Call {@link #buildStates()} to create the states of the flow and add
036: * them to the flow definition.
037: * <li> Call {@link #buildGlobalTransitions()} to create the any transitions
038: * shared by all states of the flow and add them to the flow definition.
039: * <li> Call {@link #buildEndActions()} to create and add any end actions to
040: * the flow.
041: * <li> Call {@link #buildOutputMapper()} to create and set the output mapper
042: * for the flow.
043: * <li> Call {@link #buildExceptionHandlers()} to create the exception
044: * handlers of the flow and add them to the flow definition.
045: * <li> Call {@link #getFlow()} to return the fully-built {@link Flow}
046: * definition.
047: * <li> Dispose this builder, releasing any resources allocated during the
048: * building process by calling {@link #dispose()}.
049: * </ol>
050: * <p>
051: * Implementations should encapsulate flow construction logic, either for a
052: * specific kind of flow, for example, an <code>OrderFlowBuilder</code> built
053: * in Java code, or a generic flow builder strategy, like the
054: * <code>XmlFlowBuilder</code>, for building flows from an XML-definition.
055: * <p>
056: * Flow builders are used by the
057: * {@link org.springframework.webflow.engine.builder.FlowAssembler}, which acts as an
058: * assembler (director). Flow Builders may be reused, however, exercise caution
059: * when doing this as these objects are not thread safe. Also, for each use be
060: * sure to call init, followed by the build* methods, getFlow, and dispose
061: * completely in that order.
062: * <p>
063: * This is an example of the classic GoF builder pattern.
064: *
065: * @see Flow
066: * @see org.springframework.webflow.engine.builder.FlowAssembler
067: * @see org.springframework.webflow.engine.builder.AbstractFlowBuilder
068: * @see org.springframework.webflow.engine.builder.xml.XmlFlowBuilder
069: *
070: * @author Keith Donald
071: * @author Erwin Vervaet
072: */
073: public interface FlowBuilder {
074:
075: /**
076: * Initialize this builder. This could cause the builder to open a stream to
077: * an externalized resource representing the flow definition, for example.
078: * @param flowId the identifier to assign to the flow
079: * @param attributes custom attributes to assign to the flow
080: * @throws FlowBuilderException an exception occured building the flow
081: */
082: public void init(String flowId, AttributeMap attributes)
083: throws FlowBuilderException;
084:
085: /**
086: * Builds any variables initialized by the flow when it starts.
087: * @throws FlowBuilderException an exception occured building the flow
088: */
089: public void buildVariables() throws FlowBuilderException;
090:
091: /**
092: * Builds the input mapper responsible for mapping flow input on start.
093: * @throws FlowBuilderException an exception occured building the flow
094: */
095: public void buildInputMapper() throws FlowBuilderException;
096:
097: /**
098: * Builds any start actions to execute when the flow starts.
099: * @throws FlowBuilderException an exception occured building the flow
100: */
101: public void buildStartActions() throws FlowBuilderException;
102:
103: /**
104: * Builds any "in-line" flows encapsulated by the flow.
105: * @throws FlowBuilderException an exception occured building the flow
106: */
107: public void buildInlineFlows() throws FlowBuilderException;
108:
109: /**
110: * Builds the states of the flow.
111: * @throws FlowBuilderException an exception occured building the flow
112: */
113: public void buildStates() throws FlowBuilderException;
114:
115: /**
116: * Builds any transitions shared by all states of the flow.
117: * @throws FlowBuilderException an exception occured building the flow
118: */
119: public void buildGlobalTransitions() throws FlowBuilderException;
120:
121: /**
122: * Builds any end actions to execute when the flow ends.
123: * @throws FlowBuilderException an exception occured building the flow
124: */
125: public void buildEndActions() throws FlowBuilderException;
126:
127: /**
128: * Builds the output mapper responsible for mapping flow output on end.
129: * @throws FlowBuilderException an exception occured building the flow
130: */
131: public void buildOutputMapper() throws FlowBuilderException;
132:
133: /**
134: * Creates and adds all exception handlers to the flow built by this
135: * builder.
136: * @throws FlowBuilderException an exception occured building this flow
137: */
138: public void buildExceptionHandlers() throws FlowBuilderException;
139:
140: /**
141: * Get the fully constructed and configured Flow object - called by the
142: * builder's assembler (director) after assembly. When this method is called
143: * by the assembler, it is expected flow construction has completed
144: * and the returned flow is ready for use.
145: */
146: public Flow getFlow();
147:
148: /**
149: * Shutdown the builder, releasing any resources it holds. A new flow
150: * construction process should start with another call to the
151: * {@link #init(String, AttributeMap)} method.
152: */
153: public void dispose();
154: }
|