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.di.ClassLoaderProvider;
19 import net.sf.jguiraffe.di.InvocationHelper;
20 import net.sf.jguiraffe.di.MutableBeanStore;
21 import net.sf.jguiraffe.locators.Locator;
22
23 /**
24 * <p>
25 * Definition of an interface for processing scripts with bean definitions.
26 * </p>
27 * <p>
28 * A <em>bean builder</em> is able to create and populate
29 * {@link net.sf.jguiraffe.di.BeanStore BeanStore} objects to be used by the
30 * <em>dependency injection</em> framework. After a successful build operation
31 * the defined beans can be easily accessed.
32 * </p>
33 * <p>
34 * This interface is pretty lean. It defines methods for executing a script with
35 * bean definitions. The return value is a data object, from which the
36 * initialized <code>BeanStore</code> instances can be queried. Another method
37 * can be called to free all resources used by produced beans. This method
38 * should be called if the builder results are no longer needed.
39 * </p>
40 * <p>
41 * For obtaining concrete implementations of this interface, usually a
42 * {@link BeanBuilderFactory} is used.
43 * </p>
44 *
45 * @author Oliver Heger
46 * @version $Id: BeanBuilder.java 205 2012-01-29 18:29:57Z oheger $
47 */
48 public interface BeanBuilder
49 {
50 /**
51 * Executes a script with bean definitions.
52 *
53 * @param script points to the script to be executed (must not be
54 * <b>null</b>)
55 * @param rootStore the root <code>BeanStore</code> object; if defined, the
56 * processed bean definitions will be added to this store unless
57 * otherwise specified; if <b>null</b>, a new bean store will be
58 * created
59 * @param loaderProvider an object with information about registered class
60 * loaders; can be <b>null</b>, then a default class loader provider
61 * will be used
62 * @return an object providing access to the <code>BeanStore</code>
63 * instances created or populated during the builder operation
64 * @throws BuilderException if an error occurs
65 * @throws IllegalArgumentException if the script is <b>null</b>
66 */
67 BeanBuilderResult build(Locator script, MutableBeanStore rootStore,
68 ClassLoaderProvider loaderProvider) throws BuilderException;
69
70 /**
71 * Executes a script with bean definitions and the specified helper objects.
72 * With this method all helper objects taking part in the builder operation
73 * can be specified. Passing the {@link InvocationHelper} can be useful if
74 * the script defines special beans which require custom data type
75 * converters. These converters can be configured in the
76 * {@link net.sf.jguiraffe.di.ConversionHelper ConversionHelper} instance
77 * contained in the {@link InvocationHelper}. It is possible to pass
78 * <b>null</b> references for the helper objects. In this case default
79 * objects are created.
80 *
81 * @param script points to the script to be executed (must not be
82 * <b>null</b>)
83 * @param rootStore the root <code>BeanStore</code> object; if defined, the
84 * processed bean definitions will be added to this store unless
85 * otherwise specified; if <b>null</b>, a new bean store will be
86 * created
87 * @param loaderProvider an object with information about registered class
88 * loaders; can be <b>null</b>, then a default class loader provider
89 * will be used
90 * @param invHlp a helper object for reflection operations; can be
91 * <b>null</b>, then a default helper object will be used
92 * @return an object providing access to the <code>BeanStore</code>
93 * instances created or populated during the builder operation
94 * @throws BuilderException if an error occurs
95 * @throws IllegalArgumentException if the script is <b>null</b>
96 */
97 BeanBuilderResult build(Locator script, MutableBeanStore rootStore,
98 ClassLoaderProvider loaderProvider, InvocationHelper invHlp)
99 throws BuilderException;
100
101 /**
102 * Releases the specified {@code BeanBuilderResult} object. This frees all
103 * resources associated with that data object. Especially on all
104 * {@code BeanProvider} objects found in one of the {@code BeanStore}s
105 * referenced by the {@code BeanBuilderResult} object the {@code shutdown()}
106 * method is called. When the data produced by a {@code BeanBuilder} is no
107 * more needed clients should invoke this method to ensure a proper clean
108 * up.
109 *
110 * @param result the {@code BeanBuilderResult} object to be released (must
111 * not be <b>null</b>)
112 * @throws IllegalArgumentException if the data object is <b>null</b>
113 */
114 void release(BeanBuilderResult result);
115 }