1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
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 net.sf.jguiraffe.gui.builder;
17
18 import net.sf.jguiraffe.gui.builder.window.Window;
19 import net.sf.jguiraffe.locators.Locator;
20
21 /**
22 * <p>
23 * The main builder interface.
24 * </p>
25 * <p>
26 * A builder is an object that can produce artifacts of the GUI from builder
27 * scripts. So the GUI is no longer constructed in the application's code, but
28 * can be defined in external resources, which are easier to maintain. This also
29 * allows for dynamic GUIs, e.g. when different builder scripts are processed
30 * based on some condition or even when builder scripts are generated at
31 * runtime.
32 * </p>
33 * <p>
34 * The builder interface itself is not too complex. There is one very generic
35 * <code>build()</code> method that can be used to build arbitrary GUI
36 * elements. Then there are a few convenience methods that are suitable for
37 * specific elements like windows.
38 * </p>
39 *
40 * @author Oliver Heger
41 * @version $Id: Builder.java 205 2012-01-29 18:29:57Z oheger $
42 */
43 public interface Builder
44 {
45 /**
46 * A generic builder method. This method initializes the builder with the
47 * passed in parameter object and then executes the given builder script.
48 * Results of the builder operation are stored in the parameter object, from
49 * which they can be obtained using the
50 * <code>{@link BuilderData#getProperty(String)}</code> method with
51 * appropriate keys.
52 *
53 * @param script the script to be executed
54 * @param data the parameter object
55 * @throws BuilderException if an error occurs
56 */
57 void build(Locator script, BuilderData data) throws BuilderException;
58
59 /**
60 * A convenience method for building windows like top-level frames or
61 * dialogs. This method behaves similar to the generic <code>build()</code>
62 * method, but directly returns the resulting window object.
63 *
64 * @param script the script to be executed
65 * @param data the parameter object
66 * @return the result window of the builder operation
67 * @throws BuilderException if an error occurs
68 */
69 Window buildWindow(Locator script, BuilderData data)
70 throws BuilderException;
71
72 /**
73 * A convenience method for constructing the GUI of the given passed in
74 * container. This method is useful if an application already has a
75 * reference to an (empty) window or panel, which now should be filled. It
76 * sets the container as the builder's root container and then invokes the
77 * specified script.
78 *
79 * @param script the script to be executed
80 * @param data the parameter object
81 * @param container the container to be filled with components
82 * @throws BuilderException if an error occurs
83 */
84 void buildContainer(Locator script, BuilderData data, Object container)
85 throws BuilderException;
86
87 /**
88 * Releases the specified {@code BuilderData} object. This will free all
89 * resources associated with this data object. Especially the {@code
90 * BeanContext} created by the {@code Builder} will be closed, and on all
91 * {@code BeanProvider} objects found in the {@code BeanStore}s that are
92 * part of the {@code BeanBuilderResult} the {@code shutdown()} method is
93 * invoked. Clients of the builder should call this method when the results
94 * of a builder operation are no more needed, e.g. when closing a window
95 * created by a builder.
96 *
97 * @param data the {@code BuilderData} object used for a builder operation
98 * (must not be <b>null</b>)
99 * @throws IllegalArgumentException if the passed in object is <b>null</b>
100 * or invalid
101 */
102 void release(BuilderData data);
103 }