KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > springframework > webflow > engine > builder > FlowBuilder


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.builder;
17
18 import org.springframework.webflow.core.collection.AttributeMap;
19 import org.springframework.webflow.engine.Flow;
20
21 /**
22  * Builder interface used to build a flow definition. The process of building a
23  * flow consists of the following steps:
24  * <ol>
25  * <li> Initialize this builder, creating the initial flow definition, by
26  * calling {@link #init(String, AttributeMap)}.
27  * <li> Call {@link #buildVariables()} to create any variables of the flow and
28  * add them to the flow definition.
29  * <li> Call {@link #buildInputMapper()} to create and set the input mapper for
30  * the flow.
31  * <li> Call {@link #buildStartActions()} to create and add any start actions to
32  * the flow.
33  * <li> Call {@link #buildInlineFlows()} to create any inline flows
34  * encapsulated by the flow and add them to the flow definition.
35  * <li> Call {@link #buildStates()} to create the states of the flow and add
36  * them to the flow definition.
37  * <li> Call {@link #buildGlobalTransitions()} to create the any transitions
38  * shared by all states of the flow and add them to the flow definition.
39  * <li> Call {@link #buildEndActions()} to create and add any end actions to
40  * the flow.
41  * <li> Call {@link #buildOutputMapper()} to create and set the output mapper
42  * for the flow.
43  * <li> Call {@link #buildExceptionHandlers()} to create the exception
44  * handlers of the flow and add them to the flow definition.
45  * <li> Call {@link #getFlow()} to return the fully-built {@link Flow}
46  * definition.
47  * <li> Dispose this builder, releasing any resources allocated during the
48  * building process by calling {@link #dispose()}.
49  * </ol>
50  * <p>
51  * Implementations should encapsulate flow construction logic, either for a
52  * specific kind of flow, for example, an <code>OrderFlowBuilder</code> built
53  * in Java code, or a generic flow builder strategy, like the
54  * <code>XmlFlowBuilder</code>, for building flows from an XML-definition.
55  * <p>
56  * Flow builders are used by the
57  * {@link org.springframework.webflow.engine.builder.FlowAssembler}, which acts as an
58  * assembler (director). Flow Builders may be reused, however, exercise caution
59  * when doing this as these objects are not thread safe. Also, for each use be
60  * sure to call init, followed by the build* methods, getFlow, and dispose
61  * completely in that order.
62  * <p>
63  * This is an example of the classic GoF builder pattern.
64  *
65  * @see Flow
66  * @see org.springframework.webflow.engine.builder.FlowAssembler
67  * @see org.springframework.webflow.engine.builder.AbstractFlowBuilder
68  * @see org.springframework.webflow.engine.builder.xml.XmlFlowBuilder
69  *
70  * @author Keith Donald
71  * @author Erwin Vervaet
72  */
73 public interface FlowBuilder {
74
75     /**
76      * Initialize this builder. This could cause the builder to open a stream to
77      * an externalized resource representing the flow definition, for example.
78      * @param flowId the identifier to assign to the flow
79      * @param attributes custom attributes to assign to the flow
80      * @throws FlowBuilderException an exception occured building the flow
81      */
82     public void init(String JavaDoc flowId, AttributeMap attributes) throws FlowBuilderException;
83
84     /**
85      * Builds any variables initialized by the flow when it starts.
86      * @throws FlowBuilderException an exception occured building the flow
87      */
88     public void buildVariables() throws FlowBuilderException;
89
90     /**
91      * Builds the input mapper responsible for mapping flow input on start.
92      * @throws FlowBuilderException an exception occured building the flow
93      */
94     public void buildInputMapper() throws FlowBuilderException;
95
96     /**
97      * Builds any start actions to execute when the flow starts.
98      * @throws FlowBuilderException an exception occured building the flow
99      */
100     public void buildStartActions() throws FlowBuilderException;
101
102     /**
103      * Builds any "in-line" flows encapsulated by the flow.
104      * @throws FlowBuilderException an exception occured building the flow
105      */
106     public void buildInlineFlows() throws FlowBuilderException;
107
108     /**
109      * Builds the states of the flow.
110      * @throws FlowBuilderException an exception occured building the flow
111      */
112     public void buildStates() throws FlowBuilderException;
113
114     /**
115      * Builds any transitions shared by all states of the flow.
116      * @throws FlowBuilderException an exception occured building the flow
117      */
118     public void buildGlobalTransitions() throws FlowBuilderException;
119
120     /**
121      * Builds any end actions to execute when the flow ends.
122      * @throws FlowBuilderException an exception occured building the flow
123      */
124     public void buildEndActions() throws FlowBuilderException;
125
126     /**
127      * Builds the output mapper responsible for mapping flow output on end.
128      * @throws FlowBuilderException an exception occured building the flow
129      */
130     public void buildOutputMapper() throws FlowBuilderException;
131
132     /**
133      * Creates and adds all exception handlers to the flow built by this
134      * builder.
135      * @throws FlowBuilderException an exception occured building this flow
136      */
137     public void buildExceptionHandlers() throws FlowBuilderException;
138
139     /**
140      * Get the fully constructed and configured Flow object - called by the
141      * builder's assembler (director) after assembly. When this method is called
142      * by the assembler, it is expected flow construction has completed
143      * and the returned flow is ready for use.
144      */
145     public Flow getFlow();
146
147     /**
148      * Shutdown the builder, releasing any resources it holds. A new flow
149      * construction process should start with another call to the
150      * {@link #init(String, AttributeMap)} method.
151      */
152     public void dispose();
153 }
Popular Tags