1 /*
2 * (c) Copyright 2006-2020 by rapiddweller GmbH & Volker Bergmann. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, is permitted under the terms of the
6 * GNU General Public License.
7 *
8 * For redistributing this software or a derivative work under a license other
9 * than the GPL-compatible Free Software License as defined by the Free
10 * Software Foundation or approved by OSI, you must first obtain a commercial
11 * license to this software product from rapiddweller GmbH & Volker Bergmann.
12 *
13 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
14 * WITHOUT A WARRANTY OF ANY KIND. ALL EXPRESS OR IMPLIED CONDITIONS,
15 * REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF
16 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
17 * HEREBY EXCLUDED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
18 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
19 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
20 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
21 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
22 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
23 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
24 * POSSIBILITY OF SUCH DAMAGE.
25 */
26
27 package com.rapiddweller.benerator;
28
29 import com.rapiddweller.benerator.wrapper.ProductWrapper;
30 import com.rapiddweller.common.Resettable;
31 import com.rapiddweller.common.ThreadAware;
32
33 import java.io.Closeable;
34
35 /**
36 * This is the basic Generator interface, the mother of all generators.<br/>
37 * <br/>
38 * <b>Generator States</b><br/>
39 * A Generator may be in one of three states:
40 * <ul>
41 * <li><i>constructing</i>: The generator is under construction.
42 * This may take several steps, since generators need to be JavaBeans.
43 * The generator may transit into the available state automatically
44 * or manually when the validate() method is called.</li>
45 * <li><i>available</i>: Generator construction is done and the generator is available.
46 * The user may loop the Generator via generate().</li>
47 * <li><i>unavailable</i>: The Generator may become unavailable automatically if its value space is depleted or
48 * manually when close() has been invoked. The Generator may be made <i>available</i> again by calling reset().
49 * When <i>unavailable</i>, the generator must be in a state in which it can be safely garbage collected.</li>
50 * </ul>
51 *
52 * <b>Developer Notes:</b><br/>
53 * When implementing a custom generator, you should make it a JavaBean:
54 * <ul>
55 * <li>Implement a public default (no-arg) constructor</li>
56 * <li>make each relevant property configurable by a set-method</li>
57 * </ul>
58 * <br/>
59 * Created: 07.06.2006 18:51:28
60 *
61 * @param <E> the type parameter
62 * @author Volker Bergmann
63 * @since 0.1
64 */
65 public interface Generator<E> extends ThreadAware, Resettable, Closeable {
66
67 /**
68 * Declares the type of the objects returned by the generate() method.
69 *
70 * @return the generated type
71 */
72 Class<E> getGeneratedType();
73
74 /**
75 * Init.
76 *
77 * @param context the context
78 */
79 void init(GeneratorContext context);
80
81 /**
82 * Was initialized boolean.
83 *
84 * @return the boolean
85 */
86 boolean wasInitialized();
87
88 /**
89 * Returns an instance of the generic type E, using the {@link ProductWrapper}
90 * instance provided as argument.
91 * The wrapper may wrap a null value as a regular generator product.
92 * If the generator is not available (any more), it returns null instead of
93 * the ProductWrapper instance.
94 *
95 * @param wrapper the wrapper
96 * @return the product wrapper
97 */
98 ProductWrapper<E> generate(ProductWrapper<E> wrapper);
99
100 /**
101 * Closes the generator. After invocation the state is <i>unavailable</i>.
102 */
103 @Override
104 void close();
105
106 }